emeraldengine 2.2.1 → 3.0.0

package/src/Camera.js

@@ -0,0 +1,183 @@
+import Transform from "./Transform.js";
+import { Vector2, Vector3 } from "./Physics.js";
+
+/**
+ * @class Camera
+ * @description A view into the scene with its own transform (position, zoom,
+ * rotation) and a viewport rectangle. Multiple cameras can be added to an
+ * Emerald instance to render split-screen or picture-in-picture. The viewport
+ * is expressed in normalized [0..1] coordinates with the origin at the
+ * bottom-left of the canvas (matching WebGL).
+ *
+ * Backward compatible with the previous inline camera: position is stored
+ * negated internally, and setPosition/getPosition/setZoom/getZoom behave the
+ * same, so EventManager and CameraController are unaffected.
+ *
+ * @example
+ * const left = new Camera({ viewport: { x: 0, y: 0, width: 0.5, height: 1 } });
+ * const right = new Camera({ viewport: { x: 0.5, y: 0, width: 0.5, height: 1 } });
+ * emerald.setCameras([left, right]);
+ */
+class Camera {
+  constructor(options = {}) {
+    this.transform = new Transform(new Vector3(0, 0, 0), 0, new Vector2(1, 1));
+
+    const vp = options.viewport || {};
+    this.viewport = {
+      x: vp.x ?? 0,
+      y: vp.y ?? 0,
+      width: vp.width ?? 1,
+      height: vp.height ?? 1,
+    };
+
+    this.active = options.active !== false;
+    this.clearColor = options.clearColor || null;
+
+    this.ignoreLayers = new Set(options.ignoreLayers || []);
+
+    this.onlyLayers = options.onlyLayers ? new Set(options.onlyLayers) : null;
+
+    this.excludeFromPost = options.excludeFromPost === true;
+
+    this.pixelSnap = options.pixelSnap === true;
+  }
+
+  /**
+   * @method setPixelSnap
+   * @description When true, the camera's rendered position is rounded to whole
+   * screen pixels each frame (the stored position stays smooth). Use it for
+   * pixel-art games to eliminate sub-pixel shimmer and tile seams while a
+   * smooth-follow camera moves. Ignored while the camera is rotated.
+   * @param {boolean} snap
+   * @returns {Camera} - this
+   */
+  setPixelSnap(snap) {
+    this.pixelSnap = snap !== false;
+    return this;
+  }
+
+  /**
+   * @method setExcludeFromPost
+   * @description When true, this camera renders straight to the screen AFTER the
+   * post-processing pass instead of into the post-processed scene buffer. Use it
+   * for HUD/UI cameras so effects like bloom don't affect the interface.
+   * @param {boolean} exclude
+   * @returns {Camera} - this
+   */
+  setExcludeFromPost(exclude) {
+    this.excludeFromPost = exclude !== false;
+    return this;
+  }
+
+  /**
+   * @method setOnlyLayers
+   * @description Restricts the camera to rendering only the given layers (or
+   * pass null to clear the restriction).
+   * @param {number[]|null} layers
+   * @returns {Camera} - this
+   */
+  setOnlyLayers(layers) {
+    this.onlyLayers = layers ? new Set(layers) : null;
+    return this;
+  }
+
+  /**
+   * @method setIgnoreLayers
+   * @description Replaces the set of layers this camera skips when rendering.
+   * @param {number[]} layers - Layer indices to ignore
+   * @returns {Camera} - this
+   */
+  setIgnoreLayers(layers) {
+    this.ignoreLayers = new Set(layers);
+    return this;
+  }
+
+  /**
+   * @method ignoreLayer
+   * @description Adds a single layer to the ignore set.
+   * @param {number} layer
+   * @returns {Camera} - this
+   */
+  ignoreLayer(layer) {
+    this.ignoreLayers.add(layer);
+    return this;
+  }
+
+  /**
+   * @method setPosition
+   * @description Sets the world-space center of the camera.
+   */
+  setPosition(x, y, z = 0) {
+    this.transform.position.x = -x;
+    this.transform.position.y = -y;
+    this.transform.position.z = -z;
+  }
+
+  /**
+   * @method getPosition
+   * @description Returns the world-space center of the camera.
+   */
+  getPosition() {
+    return {
+      x: -this.transform.position.x,
+      y: -this.transform.position.y,
+      z: -this.transform.position.z,
+    };
+  }
+
+  /**
+   * @method setZoom
+   * @description Sets the zoom (1 = default, >1 zooms in).
+   */
+  setZoom(zoom) {
+    const z = Math.max(0.0001, zoom);
+    this.transform.scale.x = z;
+    this.transform.scale.y = z;
+  }
+
+  /**
+   * @method getZoom
+   * @returns {number}
+   */
+  getZoom() {
+    return this.transform.scale.x;
+  }
+
+  /**
+   * @method setRotation
+   * @description Sets the camera rotation in radians.
+   */
+  setRotation(radians) {
+    this.transform.rotation = radians;
+  }
+
+  /**
+   * @method getRotation
+   * @returns {number}
+   */
+  getRotation() {
+    return this.transform.rotation;
+  }
+
+  /**
+   * @method setViewport
+   * @description Sets the normalized viewport rectangle (origin bottom-left).
+   * @returns {Camera} - this
+   */
+  setViewport(x, y, width, height) {
+    this.viewport = { x, y, width, height };
+    return this;
+  }
+
+  /**
+   * @method setActive
+   * @description Enables/disables rendering of this camera.
+   * @returns {Camera} - this
+   */
+  setActive(active) {
+    this.active = active;
+    return this;
+  }
+}
+
+export default Camera;

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;