emeraldengine 2.2.1 → 3.1.0

package/src/RenderTarget.js

@@ -0,0 +1,134 @@
+import GLManager from "./managers/GLManager.js";
+
+/**
+ * @class RenderTarget
+ * @description An offscreen render surface: a framebuffer backed by a color
+ * texture (and an optional depth buffer). Bind it to render the scene (or a
+ * post-processing pass) into a texture instead of the screen. The resulting
+ * `texture` can then be sampled by another pass or drawn to the canvas.
+ *
+ * Used by the post-processing pipeline, but also useful on its own for
+ * minimaps, mirrors, render-to-texture effects, or picture-in-picture.
+ *
+ * @example
+ * const rt = new RenderTarget(512, 512);
+ * rt.bind();
+ * // ...draw...
+ * rt.unbind();
+ * // rt.texture now holds the rendered image
+ */
+class RenderTarget {
+  /**
+   * @param {number} width - Width in pixels
+   * @param {number} height - Height in pixels
+   * @param {Object} [options] - { depth = false, pixelart = false }
+   */
+  constructor(width, height, options = {}) {
+    this.gl = GLManager.getGL();
+    this.width = Math.max(1, width | 0);
+    this.height = Math.max(1, height | 0);
+    this.depth = !!options.depth;
+    this.pixelart = !!options.pixelart;
+
+    const gl = this.gl;
+    this.framebuffer = gl.createFramebuffer();
+    this.texture = gl.createTexture();
+    this.depthBuffer = this.depth ? gl.createRenderbuffer() : null;
+
+    this._allocate();
+  }
+
+  /** @private */
+  _allocate() {
+    const gl = this.gl;
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      gl.RGBA,
+      this.width,
+      this.height,
+      0,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      null
+    );
+    const filter = this.pixelart ? gl.NEAREST : gl.LINEAR;
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+    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.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.framebufferTexture2D(
+      gl.FRAMEBUFFER,
+      gl.COLOR_ATTACHMENT0,
+      gl.TEXTURE_2D,
+      this.texture,
+      0
+    );
+
+    if (this.depth) {
+      gl.bindRenderbuffer(gl.RENDERBUFFER, this.depthBuffer);
+      gl.renderbufferStorage(
+        gl.RENDERBUFFER,
+        gl.DEPTH_COMPONENT16,
+        this.width,
+        this.height
+      );
+      gl.framebufferRenderbuffer(
+        gl.FRAMEBUFFER,
+        gl.DEPTH_ATTACHMENT,
+        gl.RENDERBUFFER,
+        this.depthBuffer
+      );
+    }
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+
+  /**
+   * @method resize
+   * @description Resizes the surface (reallocating storage) if dimensions change.
+   */
+  resize(width, height) {
+    const w = Math.max(1, width | 0);
+    const h = Math.max(1, height | 0);
+    if (w === this.width && h === this.height) return;
+    this.width = w;
+    this.height = h;
+    this._allocate();
+  }
+
+  /**
+   * @method bind
+   * @description Binds this framebuffer and sets the viewport to its full size.
+   */
+  bind() {
+    const gl = this.gl;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, this.width, this.height);
+  }
+
+  /**
+   * @method unbind
+   * @description Restores the default framebuffer (the canvas).
+   */
+  unbind() {
+    this.gl.bindFramebuffer(this.gl.FRAMEBUFFER, null);
+  }
+
+  /**
+   * @method dispose
+   * @description Frees all GL resources held by this target.
+   */
+  dispose() {
+    const gl = this.gl;
+    if (this.framebuffer) gl.deleteFramebuffer(this.framebuffer);
+    if (this.texture) gl.deleteTexture(this.texture);
+    if (this.depthBuffer) gl.deleteRenderbuffer(this.depthBuffer);
+    this.framebuffer = this.texture = this.depthBuffer = null;
+  }
+}
+
+export default RenderTarget;

package/src/Scene.js

@@ -1,83 +1,115 @@
-import GameObject from "./components/GameObject.js";
-
-/**
- * @class Scene
- * @description Represents a scene
- * @param {Array} objects - The objects in the scene
- */
-class Scene {
-  constructor(objects = []) {
-    this.objects = objects;
-  }
-
-  /**
-   * @method add
-   * @description Adds an object to the scene
-   * @param {GameObject} object - The object to add
-   */
-  add(object) {
-    if (!(object instanceof GameObject)) {
-      throw new Error("Object is not a GameObject");
-    }
-    object.setIsActive(true);
-    if (!this.objects.some((obj) => obj.id === object.id)) {
-      this.objects.push(object);
-    }
-  }
-
-  /**
-   * @method remove
-   * @description Removes an object from the scene
-   * @param {GameObject} object - The object to remove
-   */
-  remove(object) {
-    if (!(object instanceof GameObject)) {
-      throw new Error("Object is not a GameObject");
-    }
-    object.setIsActive(false);
-    this.objects = this.objects.filter(function (obj) {
-      var objId = obj ? obj.id : undefined;
-      var targetId = object ? object.id : undefined;
-      return objId !== targetId;
-    });
-  }
-
-  /**
-   * @method setIsActive
-   * @description Sets the active state of the scene
-   * @param {boolean} bool - The active state
-   */
-  setIsActive(bool) {
-    for (let object of this.objects) {
-      this.setActiveRecursive(object, bool);
-    }
-  }
-
-  /**
-   * @method setActiveRecursive
-   * @description Sets the active state of the scene recursively
-   * @param {Object} object - The object to set the active state of
-   * @param {boolean} bool - The active state
-   */
-  setActiveRecursive(object, bool) {
-    object.setIsActive(bool);
-  }
-
-  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator
-  [Symbol.iterator]() {
-    let index = -1;
-    const data = this.objects;
-
-    return {
-      next: () => ({ value: data[++index], done: !(index in data) }),
-    };
-  }
-
-  forEach(callback) {
-    for (const obj of this.objects) {
-      callback(obj);
-    }
-  }
-}
-
-export default Scene;
+import GameObject from "./components/GameObject.js";
+
+/**
+ * @class Scene
+ * @description Represents a scene
+ * @param {Array} objects - The objects in the scene
+ */
+class Scene {
+  constructor(objects = []) {
+    this.objects = objects;
+  }
+
+  /**
+   * @method add
+   * @description Adds an object to the scene
+   * @param {GameObject} object - The object to add
+   */
+  add(object) {
+    if (!(object instanceof GameObject)) {
+      throw new Error("Object is not a GameObject");
+    }
+    object.setIsActive(true);
+    if (!this.objects.some((obj) => obj.id === object.id)) {
+      this.objects.push(object);
+    }
+  }
+
+  /**
+   * @method remove
+   * @description Removes an object from the scene. By default the object's GPU
+   * resources stay alive so it can be re-added later; pass { dispose: true }
+   * to also destroy it (free GL buffers/textures, physics bodies) when it is
+   * being removed for good.
+   * @param {GameObject} object - The object to remove
+   * @param {Object} [options] - { dispose = false }
+   */
+  remove(object, options = {}) {
+    if (!(object instanceof GameObject)) {
+      throw new Error("Object is not a GameObject");
+    }
+    object.setIsActive(false);
+    this.objects = this.objects.filter(function (obj) {
+      var objId = obj ? obj.id : undefined;
+      var targetId = object ? object.id : undefined;
+      return objId !== targetId;
+    });
+    if (options.dispose) object.destroy();
+  }
+
+  /**
+   * @method dispose
+   * @description Destroys every object in the scene (freeing their GPU
+   * resources and physics bodies) and empties it. Call when a level/screen is
+   * torn down for good; removing objects without disposing leaks GL buffers
+   * over repeated scene swaps.
+   */
+  dispose() {
+    for (const object of this.objects) {
+      if (object && typeof object.destroy === "function") object.destroy();
+    }
+    this.objects = [];
+  }
+
+  /**
+   * @method update
+   * @description Ticks every active object's component lifecycle. Call once per
+   * frame (before or after drawScene) to drive Behaviour components.
+   * @param {number} deltaTime - Seconds since the previous frame
+   */
+  update(deltaTime) {
+    for (const object of this.objects) {
+      if (object.isActive && typeof object.update === "function") {
+        object.update(deltaTime);
+      }
+    }
+  }
+
+  /**
+   * @method setIsActive
+   * @description Sets the active state of the scene
+   * @param {boolean} bool - The active state
+   */
+  setIsActive(bool) {
+    for (let object of this.objects) {
+      this.setActiveRecursive(object, bool);
+    }
+  }
+
+  /**
+   * @method setActiveRecursive
+   * @description Sets the active state of the scene recursively
+   * @param {Object} object - The object to set the active state of
+   * @param {boolean} bool - The active state
+   */
+  setActiveRecursive(object, bool) {
+    object.setIsActive(bool);
+  }
+
+  [Symbol.iterator]() {
+    let index = -1;
+    const data = this.objects;
+
+    return {
+      next: () => ({ value: data[++index], done: !(index in data) }),
+    };
+  }
+
+  forEach(callback) {
+    for (const obj of this.objects) {
+      callback(obj);
+    }
+  }
+}
+
+export default Scene;

package/src/ScreenEffects.js

@@ -0,0 +1,266 @@
+import GameObject from "./components/GameObject.js";
+import { Square2D } from "./Shapes.js";
+import { Vector2, Vector3 } from "./Physics.js";
+import Color from "./Color.js";
+import Easing from "./Easing.js";
+
+/**
+ * @class ScreenEffects
+ * @description In-engine full-screen camera/transition effects: fade to/from a
+ * color, screen flash, and cinematic letterbox bars. Everything is drawn with
+ * the engine's own screen-space quads (no DOM/CSS overlay), so it survives
+ * resolution changes, post-processing, and split-screen (the quads overfill
+ * every viewport and are clipped per camera).
+ *
+ * Add it to your scene's update loop by calling `update(dt)` each frame.
+ *
+ * @example
+ * const fx = new ScreenEffects(scene, { layer: 100000 });
+ * await fx.fadeOut(0.4, new Color(0,0,0,255));  // to black
+ * loadNextLevel();
+ * await fx.fadeIn(0.4);
+ * // bumps:
+ * fx.flash(new Color(255,255,255,255), 0.15);
+ * // in the loop, before drawScene: fx.update(dt);
+ */
+class ScreenEffects {
+  /**
+   * @param {Scene} scene - The scene to draw the overlays into
+   * @param {Object} [options] - { layer = 100000, size = 5000 }
+   */
+  constructor(scene, options = {}) {
+    this.scene = scene;
+    const layer = options.layer ?? 100000;
+    const half = options.size ?? 5000;
+
+    /** @private */
+    this._fade = this._makeQuad(layer, half, new Color(0, 0, 0, 255));
+    /** @private */
+    this._flashQuad = this._makeQuad(
+      layer + 1,
+      half,
+      new Color(255, 255, 255, 255)
+    );
+
+    /** @private */
+    this._barTop = this._makeQuad(layer + 2, half, new Color(0, 0, 0, 255));
+    /** @private */
+    this._barBottom = this._makeQuad(layer + 2, half, new Color(0, 0, 0, 255));
+    this._barTop.setOpacity(0);
+    this._barBottom.setOpacity(0);
+    /** @private */
+    this._letterboxHeight = 0;
+    /** @private */
+    this._letterboxTarget = 0;
+    /** @private */
+    this._barHalf = half;
+
+    /** @private */
+    this._fadeAnim = null;
+    /** @private */
+    this._flashAnim = null;
+  }
+
+  /** @private */
+  _makeQuad(layer, half, color) {
+    const go = new GameObject(
+      "ScreenEffect",
+      new Vector3(0, 0, 0),
+      0,
+      new Vector2(half, half)
+    );
+    const shape = new Square2D();
+    shape.setColor(color);
+    shape.setUseLighting(false);
+    go.addComponent(shape);
+    go.setScreenSpace(true);
+    go.setLayer(layer);
+    go.alwaysVisible = true;
+    go.setOpacity(0);
+    /** @private */
+    this._shapeOf = this._shapeOf || new WeakMap();
+    this._shapeOf.set(go, shape);
+    this.scene.add(go);
+    return go;
+  }
+
+  /** @private */
+  _setColor(go, color) {
+    const shape = this._shapeOf.get(go);
+    if (shape) shape.setColor(color);
+  }
+
+  /**
+   * @method fadeOut
+   * @description Fades the screen to a solid color (opacity 0 -> 1).
+   * @param {number} duration - Seconds
+   * @param {Color} [color] - Target color (default black)
+   * @param {Function} [easing] - Easing function (default linear)
+   * @returns {Promise<void>} - Resolves when the fade completes
+   */
+  fadeOut(
+    duration = 0.4,
+    color = new Color(0, 0, 0, 255),
+    easing = Easing.linear
+  ) {
+    this._setColor(this._fade, color);
+    return this._startFade(this._fade.getOpacity(), 1, duration, easing);
+  }
+
+  /**
+   * @method fadeIn
+   * @description Fades the screen back in from the current overlay (opacity -> 0).
+   * @param {number} duration - Seconds
+   * @param {Function} [easing] - Easing function (default linear)
+   * @returns {Promise<void>}
+   */
+  fadeIn(duration = 0.4, easing = Easing.linear) {
+    return this._startFade(this._fade.getOpacity(), 0, duration, easing);
+  }
+
+  /** @private */
+  _startFade(from, to, duration, easing) {
+    return new Promise((resolve) => {
+      if (this._fadeAnim && this._fadeAnim.resolve) this._fadeAnim.resolve();
+      if (duration <= 0) {
+        this._fade.setOpacity(to);
+        resolve();
+        this._fadeAnim = null;
+        return;
+      }
+      this._fadeAnim = { from, to, elapsed: 0, duration, easing, resolve };
+    });
+  }
+
+  /**
+   * @method flash
+   * @description Flashes a color that ramps to full then fades out.
+   * @param {Color} [color] - Flash color (default white)
+   * @param {number} duration - Total seconds for the flash
+   * @returns {Promise<void>}
+   */
+  flash(color = new Color(255, 255, 255, 255), duration = 0.2) {
+    this._setColor(this._flashQuad, color);
+    return new Promise((resolve) => {
+      if (this._flashAnim && this._flashAnim.resolve) this._flashAnim.resolve();
+      this._flashAnim = {
+        elapsed: 0,
+        duration: Math.max(0.0001, duration),
+        resolve,
+      };
+    });
+  }
+
+  /**
+   * @method transition
+   * @description Fades the screen out to a color, runs a swap callback at the
+   * darkest point (e.g. tear down the old scene and build the new one), then
+   * fades back in. Requires `update(dt)` to be pumped each frame by your loop.
+   * @param {Function} swap - Called (and awaited) while the screen is covered
+   * @param {Object} [options] - { duration = 0.4, color = black, outDuration,
+   *   inDuration, easing }
+   * @returns {Promise<void>} - Resolves after the fade-in completes
+   */
+  async transition(swap, options = {}) {
+    const {
+      duration = 0.4,
+      color = new Color(0, 0, 0, 255),
+      outDuration,
+      inDuration,
+      easing = Easing.linear,
+    } = options;
+    await this.fadeOut(outDuration ?? duration, color, easing);
+    if (typeof swap === "function") await swap();
+    await this.fadeIn(inDuration ?? duration, easing);
+  }
+
+  /**
+   * @method setLetterbox
+   * @description Animates cinematic black bars to the given height (in pixels,
+   * per bar). Pass 0 to retract them.
+   * @param {number} heightPx - Target bar height in pixels
+   */
+  setLetterbox(heightPx) {
+    this._letterboxTarget = Math.max(0, heightPx);
+  }
+
+  /**
+   * @method update
+   * @description Advances all active transitions. Call once per frame.
+   * @param {number} dt - Seconds since last frame
+   */
+  update(dt) {
+    if (this._fadeAnim) {
+      const a = this._fadeAnim;
+      a.elapsed += dt;
+      const k = Math.min(1, a.elapsed / a.duration);
+      const eased = a.easing(k);
+      this._fade.setOpacity(a.from + (a.to - a.from) * eased);
+      if (k >= 1) {
+        const resolve = a.resolve;
+        this._fadeAnim = null;
+        if (resolve) resolve();
+      }
+    }
+
+    if (this._flashAnim) {
+      const a = this._flashAnim;
+      a.elapsed += dt;
+      const k = Math.min(1, a.elapsed / a.duration);
+      const opacity = k < 0.25 ? k / 0.25 : 1 - (k - 0.25) / 0.75;
+      this._flashQuad.setOpacity(Math.max(0, opacity));
+      if (k >= 1) {
+        const resolve = a.resolve;
+        this._flashAnim = null;
+        this._flashQuad.setOpacity(0);
+        if (resolve) resolve();
+      }
+    }
+
+    if (this._letterboxHeight !== this._letterboxTarget) {
+      const speed = 1200;
+      const dir = Math.sign(this._letterboxTarget - this._letterboxHeight);
+      this._letterboxHeight += dir * speed * dt;
+      if (
+        (dir > 0 && this._letterboxHeight > this._letterboxTarget) ||
+        (dir < 0 && this._letterboxHeight < this._letterboxTarget)
+      ) {
+        this._letterboxHeight = this._letterboxTarget;
+      }
+    }
+    const visible = this._letterboxHeight > 0.5;
+    this._barTop.setOpacity(visible ? 1 : 0);
+    this._barBottom.setOpacity(visible ? 1 : 0);
+    if (visible) {
+      const offset =
+        this._barHalf + this._screenHalfHeight() - this._letterboxHeight;
+      this._barTop.transform.position.y = offset;
+      this._barBottom.transform.position.y = -offset;
+    }
+  }
+
+  /** @private */
+  _screenHalfHeight() {
+    if (typeof window !== "undefined" && window.innerHeight) {
+      return window.innerHeight / 2;
+    }
+    return 360;
+  }
+
+  /**
+   * @method destroy
+   * @description Removes all overlay objects from the scene.
+   */
+  destroy() {
+    for (const go of [
+      this._fade,
+      this._flashQuad,
+      this._barTop,
+      this._barBottom,
+    ]) {
+      this.scene.remove(go);
+    }
+  }
+}
+
+export default ScreenEffects;