emeraldengine 2.2.1 → 3.1.0

package/src/CameraController.js

@@ -0,0 +1,192 @@
+import MathUtils from "./MathUtils.js";
+
+/**
+ * @class CameraController
+ * @description Drives an Emerald camera with follow, bounds clamping, zoom and
+ * screen shake. Construct it with `emerald.camera` and call `update(dt)` once
+ * per frame.
+ *
+ * @example
+ * const cam = new CameraController(emerald.camera);
+ * cam.follow(player.gameObject, 0.1).setBounds(-1000, -1000, 1000, 1000);
+ * // in the loop: cam.update(deltaTime);
+ */
+class CameraController {
+  /**
+   * @param {Object} camera - The Emerald camera (e.g. emerald.camera)
+   */
+  constructor(camera) {
+    this.camera = camera;
+    this.target = null;
+    this.smoothing = 1;
+    this.bounds = null;
+
+    const start = camera.getPosition ? camera.getPosition() : { x: 0, y: 0 };
+    this.position = { x: start.x, y: start.y };
+
+    this.shakeIntensity = 0;
+    this.shakeDuration = 0;
+    this.shakeElapsed = Infinity;
+
+    this.deadzone = null;
+  }
+
+  /**
+   * @method setDeadzone
+   * @description Sets a centered follow deadzone. The camera only scrolls when
+   * the target moves outside this box, giving the player room to move without
+   * the camera reacting to every step. Pass 0/0 or null to disable.
+   * @param {number} halfWidth - Horizontal half-extent in world units
+   * @param {number} halfHeight - Vertical half-extent in world units
+   * @returns {CameraController} - this
+   */
+  setDeadzone(halfWidth, halfHeight) {
+    this.deadzone =
+      halfWidth || halfHeight
+        ? { x: Math.abs(halfWidth || 0), y: Math.abs(halfHeight || 0) }
+        : null;
+    return this;
+  }
+
+  /**
+   * @method follow
+   * @description Follows a target each frame.
+   * @param {Object} target - GameObject/Instance (uses transform.position) or a { x, y }
+   * @param {number} smoothing - 0..1, higher snaps faster (1 = instant)
+   * @returns {CameraController} - this
+   */
+  follow(target, smoothing = 0.1) {
+    this.target = target;
+    this.smoothing = smoothing;
+    return this;
+  }
+
+  /**
+   * @method stopFollow
+   * @description Stops following the current target.
+   * @returns {CameraController} - this
+   */
+  stopFollow() {
+    this.target = null;
+    return this;
+  }
+
+  /**
+   * @method setBounds
+   * @description Clamps the camera center to a world-space rectangle.
+   * @returns {CameraController} - this
+   */
+  setBounds(minX, minY, maxX, maxY) {
+    this.bounds = { minX, minY, maxX, maxY };
+    return this;
+  }
+
+  /**
+   * @method clearBounds
+   * @description Removes bounds clamping.
+   * @returns {CameraController} - this
+   */
+  clearBounds() {
+    this.bounds = null;
+    return this;
+  }
+
+  /**
+   * @method setZoom
+   * @description Sets the camera zoom (1 = default, >1 zooms in).
+   * @returns {CameraController} - this
+   */
+  setZoom(zoom) {
+    if (this.camera.setZoom) this.camera.setZoom(zoom);
+    return this;
+  }
+
+  /**
+   * @method getZoom
+   * @returns {number} - The current zoom
+   */
+  getZoom() {
+    return this.camera.getZoom ? this.camera.getZoom() : 1;
+  }
+
+  /**
+   * @method setPosition
+   * @description Immediately moves the camera center.
+   * @returns {CameraController} - this
+   */
+  setPosition(x, y) {
+    this.position.x = x;
+    this.position.y = y;
+    this.camera.setPosition(x, y, 0);
+    return this;
+  }
+
+  /**
+   * @method shake
+   * @description Triggers a screen shake that decays over its duration.
+   * @param {number} intensity - Max offset in world units
+   * @param {number} duration - Duration in seconds
+   * @returns {CameraController} - this
+   */
+  shake(intensity, duration) {
+    this.shakeIntensity = intensity;
+    this.shakeDuration = duration;
+    this.shakeElapsed = 0;
+    return this;
+  }
+
+  /** @private */
+  _targetPosition() {
+    const t = this.target;
+    if (!t) return null;
+    if (t.transform && t.transform.position) return t.transform.position;
+    return t;
+  }
+
+  /**
+   * @method update
+   * @description Advances follow/shake and applies the result to the camera.
+   * @param {number} dt - Seconds since the last frame
+   */
+  update(dt) {
+    const targetPos = this._targetPosition();
+    if (targetPos) {
+      let goalX = targetPos.x;
+      let goalY = targetPos.y;
+      if (this.deadzone) {
+        goalX = this.position.x;
+        goalY = this.position.y;
+        const dx = targetPos.x - this.position.x;
+        const dy = targetPos.y - this.position.y;
+        if (dx > this.deadzone.x) goalX = targetPos.x - this.deadzone.x;
+        else if (dx < -this.deadzone.x) goalX = targetPos.x + this.deadzone.x;
+        if (dy > this.deadzone.y) goalY = targetPos.y - this.deadzone.y;
+        else if (dy < -this.deadzone.y) goalY = targetPos.y + this.deadzone.y;
+      }
+
+      const s = MathUtils.clamp(this.smoothing, 0, 1);
+      const a = s >= 1 ? 1 : 1 - Math.pow(1 - s, dt * 60);
+      this.position.x = MathUtils.lerp(this.position.x, goalX, a);
+      this.position.y = MathUtils.lerp(this.position.y, goalY, a);
+    }
+
+    let x = this.position.x;
+    let y = this.position.y;
+
+    if (this.bounds) {
+      x = MathUtils.clamp(x, this.bounds.minX, this.bounds.maxX);
+      y = MathUtils.clamp(y, this.bounds.minY, this.bounds.maxY);
+    }
+
+    if (this.shakeElapsed < this.shakeDuration) {
+      this.shakeElapsed += dt;
+      const falloff = Math.max(0, 1 - this.shakeElapsed / this.shakeDuration);
+      x += (Math.random() * 2 - 1) * this.shakeIntensity * falloff;
+      y += (Math.random() * 2 - 1) * this.shakeIntensity * falloff;
+    }
+
+    this.camera.setPosition(x, y, 0);
+  }
+}
+
+export default CameraController;

package/src/CanvasText.js

@@ -0,0 +1,281 @@
+import Drawable from "./Drawable.js";
+import GameObject from "./components/GameObject.js";
+import GLManager from "./managers/GLManager.js";
+import { initVertexBuffer } from "./GLUtils.js";
+import { Vector2, Vector3 } from "./Physics.js";
+
+/**
+ * @class CanvasText
+ * @description Renders dynamic text using a system font by drawing to an
+ * offscreen 2D canvas and uploading it as a texture. Unlike BitmapText it needs
+ * no font sheet and supports any installed font. It's a Drawable component;
+ * `CanvasText.create()` returns a ready GameObject sized to the text.
+ *
+ * @example
+ * const label = CanvasText.create("Score: 0", {
+ *   font: "bold 28px monospace", color: "#6ee7b7", screenSpace: true,
+ * });
+ * label.transform.position = new Vector3(-300, 260, 100);
+ * scene.add(label);
+ * label.getComponent(CanvasText).setText("Score: 120");
+ */
+class CanvasText extends Drawable {
+  constructor(text, options = {}) {
+    const gl = GLManager.getGL();
+    const vertices = [1.0, 1.0, -1.0, 1.0, 1.0, -1.0, -1.0, -1.0];
+    const verticesBuffer = initVertexBuffer(gl, vertices);
+    const texCoords = [1.0, 1.0, 0.0, 1.0, 1.0, 0.0, 0.0, 0.0];
+    const texCoordBuffer = initVertexBuffer(gl, texCoords);
+
+    super(
+      gl,
+      GLManager.getProgramInfo(),
+      verticesBuffer,
+      texCoordBuffer,
+      vertices,
+      false,
+      "",
+      0,
+      0,
+      1,
+      1,
+      0,
+      false,
+      false,
+      options.useLighting === true
+    );
+
+    this.font = options.font || "24px sans-serif";
+    this.fillStyle = options.color || "#ffffff";
+    this.padding = options.padding != null ? options.padding : 6;
+    this.maxWidth = options.maxWidth || 0;
+    this.align = options.align || "center";
+    this.lineHeight = options.lineHeight || 0;
+    /** @private */
+    this._canvas = document.createElement("canvas");
+    /** @private */
+    this._ctx = this._canvas.getContext("2d");
+
+    this.useTexture = true;
+    this.texture = gl.createTexture();
+    this.width = 1;
+    this.height = 1;
+
+    this.setText(text);
+  }
+
+  /**
+   * @method setText
+   * @description Re-renders the text and re-uploads the texture. If attached to
+   * a GameObject, its scale is updated to match the new size.
+   * @param {string} text
+   */
+  setText(text) {
+    this.text = text;
+    const ctx = this._ctx;
+    const dpr = (typeof window !== "undefined" && window.devicePixelRatio) || 1;
+
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.font = this.font;
+    const fontSize = parseInt(this.font, 10) || 24;
+    const lineHeight = this.lineHeight || Math.ceil(fontSize * 1.4);
+
+    const lines = CanvasText.wrapText(
+      (s) => ctx.measureText(s).width,
+      String(text),
+      this.maxWidth
+    );
+
+    let maxLineW = 1;
+    for (const ln of lines) {
+      const m = ctx.measureText(ln);
+      let lw = m.width;
+      if (m.actualBoundingBoxLeft != null && m.actualBoundingBoxRight != null) {
+        lw = Math.max(lw, m.actualBoundingBoxLeft + m.actualBoundingBoxRight);
+      }
+      maxLineW = Math.max(maxLineW, lw);
+    }
+    const contentW = this.maxWidth
+      ? Math.max(maxLineW, this.maxWidth)
+      : maxLineW;
+    const w = Math.max(1, Math.ceil(contentW) + this.padding * 2);
+    const h = lines.length * lineHeight + this.padding * 2;
+
+    this._canvas.width = Math.max(1, Math.round(w * dpr));
+    this._canvas.height = Math.max(1, Math.round(h * dpr));
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, w, h);
+    ctx.font = this.font;
+    ctx.textBaseline = "middle";
+    ctx.textAlign = this.align;
+    ctx.fillStyle = this.fillStyle;
+
+    const x =
+      this.align === "left"
+        ? this.padding
+        : this.align === "right"
+          ? w - this.padding
+          : w / 2;
+    for (let i = 0; i < lines.length; i++) {
+      const y = this.padding + lineHeight * (i + 0.5);
+      ctx.fillText(lines[i], x, y);
+    }
+
+    const gl = this.gl;
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      gl.RGBA,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      this._canvas
+    );
+
+    this.textureWidth = this._canvas.width;
+    this.textureHeight = this._canvas.height;
+    this.originalTexture = this.texture;
+    this.width = w;
+    this.height = h;
+    /** @private */
+    this._lastTextureWidth = -1;
+
+    if (this.parentObject && this.parentObject.transform) {
+      this.parentObject.transform.scale.x = w / 2;
+      this.parentObject.transform.scale.y = h / 2;
+    }
+  }
+
+  /**
+   * @method wrapText
+   * @description Pure helper that breaks `text` into rendered lines. Honors
+   * explicit `\n` line breaks and, when `maxWidth > 0`, greedily word-wraps each
+   * paragraph so no line measures wider than `maxWidth`. A single word longer
+   * than `maxWidth` is kept on its own line rather than being split.
+   * @param {(s:string)=>number} measure - Returns the pixel width of a string
+   * @param {string} text - The text to lay out
+   * @param {number} maxWidth - Wrap width in pixels (0 disables wrapping)
+   * @returns {string[]} - The lines to render top to bottom
+   */
+  static wrapText(measure, text, maxWidth) {
+    const hardLines = text.split("\n");
+    if (!maxWidth || maxWidth <= 0) return hardLines;
+    const out = [];
+    for (const hard of hardLines) {
+      const words = hard.split(" ");
+      let line = "";
+      for (const word of words) {
+        const test = line ? line + " " + word : word;
+        if (line && measure(test) > maxWidth) {
+          out.push(line);
+          line = word;
+        } else {
+          line = test;
+        }
+      }
+      out.push(line);
+    }
+    return out;
+  }
+
+  /**
+   * @method setMaxWidth
+   * @description Sets the wrap width in pixels (0 disables wrapping) and
+   * re-renders.
+   * @param {number} px
+   */
+  setMaxWidth(px) {
+    this.maxWidth = px || 0;
+    this.setText(this.text);
+  }
+
+  /**
+   * @method setAlign
+   * @description Sets horizontal alignment ("left" | "center" | "right") and
+   * re-renders.
+   * @param {string} align
+   */
+  setAlign(align) {
+    this.align = align;
+    this.setText(this.text);
+  }
+
+  /**
+   * @method setColor
+   * @description Sets the text color (CSS color string) and re-renders.
+   * @param {string} cssColor
+   */
+  setColor(cssColor) {
+    this.fillStyle = cssColor;
+    this.setText(this.text);
+  }
+
+  /**
+   * @method getSize
+   * @returns {{width:number, height:number}} - The canvas pixel size
+   */
+  getSize() {
+    return { width: this.width, height: this.height };
+  }
+
+  /**
+   * @method _restoreGL
+   * @description After a context loss: rebuild the base buffers, recreate this
+   * text's own texture, and re-render the current string into it.
+   * @private
+   */
+  _restoreGL() {
+    if (this._disposed) return;
+    super._restoreGL();
+    if (!this.gl) return;
+    this._canvas = this._canvas || document.createElement("canvas");
+    this._ctx = this._canvas.getContext("2d");
+    this.texture = this.gl.createTexture();
+    this.setText(this.text);
+  }
+
+  /**
+   * @method dispose
+   * @description Frees the GL texture this text owns (CanvasText renders into
+   * its own texture, unlike path-loaded Textures which are shared) plus the
+   * base Drawable buffers. Safe to call twice.
+   */
+  dispose() {
+    if (this._disposed) return;
+    if (this.gl && this.texture) this.gl.deleteTexture(this.texture);
+    this.texture = null;
+    this.originalTexture = null;
+    this._canvas = null;
+    this._ctx = null;
+    super.dispose();
+  }
+
+  /**
+   * @method create
+   * @description Convenience factory returning a GameObject sized to the text.
+   * @param {string} text
+   * @param {Object} [options] - { name, position, screenSpace, font, color,
+   *   maxWidth, align, lineHeight, padding }
+   * @returns {GameObject}
+   */
+  static create(text, options = {}) {
+    const component = new CanvasText(text, options);
+    const go = new GameObject(
+      options.name || `text:${text}`,
+      options.position || new Vector3(0, 0, 0),
+      0,
+      new Vector2(component.width / 2, component.height / 2)
+    );
+    go.addComponent(component);
+    if (options.screenSpace) go.setScreenSpace(true);
+    return go;
+  }
+}
+
+export default CanvasText;

package/src/CollisionLayers.js

@@ -0,0 +1,86 @@
+/**
+ * @class CollisionLayers
+ * @description A small registry that maps human-readable layer names to the
+ * category bits the physics engine uses for collision filtering, so games can
+ * "players collide with ground and enemies, but not with each other" without
+ * juggling raw bitmasks.
+ *
+ * Two fixtures collide only if each one's category is in the other's mask, so
+ * filtering is symmetric by construction. Up to 16 distinct layers are
+ * supported (filter bits are 16-bit).
+ *
+ * @example
+ * CollisionLayers.define("ground", "player", "enemy", "pickup");
+ * playerCollider.setCategory("player");
+ * playerCollider.setCollidesWith(["ground", "enemy", "pickup"]);
+ * enemyCollider.setCategory("enemy");
+ * enemyCollider.setCollidesWith(["ground", "player"]); // enemies ignore each other
+ */
+const ALL_BITS = 0xffff;
+
+class CollisionLayers {
+  /**
+   * @method define
+   * @description Registers one or more named layers (in order), assigning each
+   * the next free category bit. Re-defining an existing name returns its
+   * existing bit. Returns the bit of the last name passed.
+   * @param {...string} names
+   * @returns {number}
+   */
+  static define(...names) {
+    let last = 0;
+    for (const name of names) last = CollisionLayers.bit(name);
+    return last;
+  }
+
+  /**
+   * @method bit
+   * @description Returns the category bit for a layer name, registering it on
+   * first use.
+   * @param {string} name
+   * @returns {number}
+   */
+  static bit(name) {
+    if (CollisionLayers._bits.has(name)) return CollisionLayers._bits.get(name);
+    if (CollisionLayers._next > 15) {
+      throw new Error(
+        "[CollisionLayers] Exceeded 16 collision layers (filter bit limit)."
+      );
+    }
+    const bit = 1 << CollisionLayers._next++;
+    CollisionLayers._bits.set(name, bit);
+    return bit;
+  }
+
+  /**
+   * @method mask
+   * @description Computes a combined mask from layer names. Accepts a single
+   * name, an array of names, a number (passed through), or "all"/null for
+   * "collide with everything".
+   * @param {string|string[]|number|null} layers
+   * @returns {number}
+   */
+  static mask(layers) {
+    if (layers == null || layers === "all") return ALL_BITS;
+    if (typeof layers === "number") return layers;
+    const list = Array.isArray(layers) ? layers : [layers];
+    let m = 0;
+    for (const name of list) m |= CollisionLayers.bit(name);
+    return m;
+  }
+
+  /**
+   * @method reset
+   * @description Clears all registered layers (mainly for tests).
+   */
+  static reset() {
+    CollisionLayers._bits.clear();
+    CollisionLayers._next = 0;
+  }
+}
+
+CollisionLayers._bits = new Map();
+CollisionLayers._next = 0;
+CollisionLayers.ALL = ALL_BITS;
+
+export default CollisionLayers;

package/src/Color.js

@@ -1,18 +1,26 @@
-/**
- * @class Color
- * @description Represents a color
- * @param {number} r - The red value
- * @param {number} g - The green value
- * @param {number} b - The blue value
- * @param {number} a - The alpha value
- */
-class Color {
-  constructor(r, g, b, a = 255) {
-    this.r = r;
-    this.g = g;
-    this.b = b;
-    this.a = a;
-  }
-}
-
-export default Color;
+/**
+ * @class Color
+ * @description Represents a color
+ * @param {number} r - The red value
+ * @param {number} g - The green value
+ * @param {number} b - The blue value
+ * @param {number} a - The alpha value
+ */
+class Color {
+  constructor(r, g, b, a = 255) {
+    this.r = r;
+    this.g = g;
+    this.b = b;
+    this.a = a;
+  }
+
+  static fromHex(hex) {
+    const value = hex.startsWith("#") ? hex.slice(1) : hex;
+    const r = parseInt(value.slice(0, 2), 16);
+    const g = parseInt(value.slice(2, 4), 16);
+    const b = parseInt(value.slice(4, 6), 16);
+    return new Color(r, g, b, 255);
+  }
+}
+
+export default Color;