emeraldengine 2.2.1 → 3.0.0

package/src/managers/NetworkManager.js

@@ -0,0 +1,178 @@
+import Interpolator from "../Interpolator.js";
+
+/**
+ * @class NetworkManager
+ * @description A thin, optional multiplayer layer over Colyseus. `colyseus.js`
+ * is an optional peer dependency and is imported dynamically, so the engine has
+ * no hard dependency on it — games that don't use networking never load it.
+ *
+ * It wraps connection/room lifecycle, exposes a small event API
+ * (onStateChange / onMessage / onAdd / onRemove / onLeave), and bundles an
+ * {@link Interpolator} so remote entities can be rendered smoothly.
+ *
+ * @example
+ * const net = new NetworkManager();
+ * await net.connect("wss://my-server");
+ * const room = await net.join("arena", { name: "P1" });
+ * net.onMessage("hit", (msg) => applyHit(msg));
+ * net.onStateChange((state) => {
+ *   for (const [id, p] of state.players) net.interpolator.push(id, p, net.now());
+ * });
+ * // each frame:
+ * const pos = net.interpolator.sample(remoteId, net.now());
+ */
+class NetworkManager {
+  constructor(options = {}) {
+    this.client = null;
+    this.room = null;
+    this.interpolator = new Interpolator(options.interpolation || {});
+    /** @private */
+    this._messageHandlers = new Map();
+    /** @private */
+    this._stateHandlers = [];
+    /** @private */
+    this._leaveHandlers = [];
+    /** @private */
+    this._startTime = NetworkManager._now();
+  }
+
+  /**
+   * @method connect
+   * @description Dynamically imports colyseus.js and creates a Client.
+   * @param {string} endpoint - The server endpoint (e.g. "wss://host:2567")
+   * @returns {Promise<NetworkManager>} - this
+   */
+  async connect(endpoint) {
+    let colyseus;
+    try {
+      colyseus = await import("colyseus.js");
+    } catch (err) {
+      throw new Error(
+        "[NetworkManager] colyseus.js is not installed. Run `npm install colyseus.js` to use networking."
+      );
+    }
+    const Client =
+      colyseus.Client || (colyseus.default && colyseus.default.Client);
+    this.client = new Client(endpoint);
+    return this;
+  }
+
+  /**
+   * @method join
+   * @description Joins (or creates) a room by name and wires up the event hooks.
+   * @param {string} roomName - The room name
+   * @param {Object} [options] - Join options forwarded to the server
+   * @returns {Promise<Object>} - The joined room
+   */
+  async join(roomName, options = {}) {
+    if (!this.client) {
+      throw new Error("[NetworkManager] Call connect() before join().");
+    }
+    this.room = await this.client.joinOrCreate(roomName, options);
+    this._wireRoom(this.room);
+    return this.room;
+  }
+
+  /** @private */
+  _wireRoom(room) {
+    if (typeof room.onStateChange === "function") {
+      room.onStateChange((state) => {
+        for (const handler of this._stateHandlers) handler(state);
+      });
+    }
+    if (typeof room.onLeave === "function") {
+      room.onLeave((code) => {
+        for (const handler of this._leaveHandlers) handler(code);
+      });
+    }
+    if (typeof room.onMessage === "function") {
+      for (const [type, handlers] of this._messageHandlers) {
+        room.onMessage(type, (payload) => handlers.forEach((h) => h(payload)));
+      }
+    }
+  }
+
+  /**
+   * @method onStateChange
+   * @description Registers a handler for full room-state updates.
+   */
+  onStateChange(handler) {
+    this._stateHandlers.push(handler);
+    return this;
+  }
+
+  /**
+   * @method onMessage
+   * @description Registers a handler for a server message type.
+   */
+  onMessage(type, handler) {
+    if (!this._messageHandlers.has(type)) {
+      this._messageHandlers.set(type, []);
+      if (this.room && typeof this.room.onMessage === "function") {
+        this.room.onMessage(type, (payload) =>
+          this._messageHandlers.get(type).forEach((h) => h(payload))
+        );
+      }
+    }
+    this._messageHandlers.get(type).push(handler);
+    return this;
+  }
+
+  /**
+   * @method onLeave
+   * @description Registers a handler invoked when the room is left.
+   */
+  onLeave(handler) {
+    this._leaveHandlers.push(handler);
+    return this;
+  }
+
+  /**
+   * @method send
+   * @description Sends a typed message to the server.
+   */
+  send(type, payload) {
+    if (this.room && typeof this.room.send === "function") {
+      this.room.send(type, payload);
+    }
+    return this;
+  }
+
+  /**
+   * @method now
+   * @description Seconds since this manager was created — a convenient clock for
+   * feeding the interpolator.
+   * @returns {number}
+   */
+  now() {
+    return (NetworkManager._now() - this._startTime) / 1000;
+  }
+
+  /**
+   * @method leave
+   * @description Leaves the current room.
+   */
+  async leave() {
+    if (this.room && typeof this.room.leave === "function") {
+      await this.room.leave();
+    }
+    this.room = null;
+  }
+
+  /**
+   * @method sessionId
+   * @returns {string|null} - This client's session id, if joined.
+   */
+  get sessionId() {
+    return this.room ? this.room.sessionId : null;
+  }
+
+  /** @private */
+  static _now() {
+    return typeof performance !== "undefined" && performance.now
+      ? performance.now()
+      : Date.now();
+  }
+}
+
+export default NetworkManager;

package/src/managers/RenderStats.js

@@ -0,0 +1,34 @@
+/**
+ * @class RenderStats
+ * @description Frame-level render counters, incremented by every draw site in
+ * the engine (Drawable, InstancedTexture, SpriteBatch, post-processing) and
+ * reset at the start of each drawScene. Read the previous completed frame via
+ * `RenderStats.frame` or `emerald.getRenderStats()` — DebugOverlay shows it
+ * automatically.
+ *
+ * - drawCalls:    GPU draw commands issued (the batching win shows up here)
+ * - quads:        sprites/shapes drawn, counting every instance in a batch
+ * - textureBinds: texture switches (high numbers = poor batching order)
+ */
+class RenderStats {
+  /**
+   * @method beginFrame
+   * @description Snapshots the counters gathered since the previous call into
+   * `frame` and zeroes the accumulators. Called by Emerald.drawScene.
+   */
+  static beginFrame() {
+    RenderStats.frame.drawCalls = RenderStats.drawCalls;
+    RenderStats.frame.quads = RenderStats.quads;
+    RenderStats.frame.textureBinds = RenderStats.textureBinds;
+    RenderStats.drawCalls = 0;
+    RenderStats.quads = 0;
+    RenderStats.textureBinds = 0;
+  }
+}
+
+RenderStats.drawCalls = 0;
+RenderStats.quads = 0;
+RenderStats.textureBinds = 0;
+RenderStats.frame = { drawCalls: 0, quads: 0, textureBinds: 0 };
+
+export default RenderStats;

package/src/managers/SceneManager.js

@@ -20,6 +20,36 @@ class SceneManager {
   static getScene() {
     return SceneManager.scene;
   }
+
+  /**
+   * @method transitionTo
+   * @description Switches the active scene, optionally behind a ScreenEffects
+   * fade. With `screenEffects` provided the screen fades out, the scene is
+   * swapped (and your optional `onSwap` runs) while covered, then fades back in.
+   * Without it the swap happens immediately.
+   *
+   * @param {Scene} scene - The scene to make active
+   * @param {Object} [options]
+   * @param {ScreenEffects} [options.screenEffects] - Effects layer to fade with
+   * @param {Function} [options.onSwap] - `(scene) => void|Promise`, run during
+   *   the covered swap (e.g. (re)build the new scene's contents)
+   * @param {number} [options.duration] - Fade duration (seconds)
+   * @param {Color} [options.color] - Fade color
+   * @returns {Promise<Scene>} - Resolves with the new scene
+   */
+  static async transitionTo(scene, options = {}) {
+    const { screenEffects, onSwap, ...fadeOptions } = options;
+    const swap = async () => {
+      SceneManager.setScene(scene);
+      if (typeof onSwap === "function") await onSwap(scene);
+    };
+    if (screenEffects && typeof screenEffects.transition === "function") {
+      await screenEffects.transition(swap, fadeOptions);
+    } else {
+      await swap();
+    }
+    return scene;
+  }
 }
 
 SceneManager.scene = null;

package/src/managers/ShaderManager.js

@@ -109,7 +109,6 @@ export class ShaderManager {
     return {
       vertexPosition: this.gl.getAttribLocation(program, "aVertexPosition"),
       textureCoord: this.gl.getAttribLocation(program, "aTextureCoord"),
-      // Add other attributes as needed
     };
   }
 
@@ -127,7 +126,6 @@ export class ShaderManager {
       ),
       modelViewMatrix: this.gl.getUniformLocation(program, "uModelViewMatrix"),
       sampler: this.gl.getUniformLocation(program, "uSampler"),
-      // Add other uniforms as needed
     };
   }
 }

package/src/managers/TextureManager.js

@@ -0,0 +1,218 @@
+import GLManager from "./GLManager.js";
+
+/**
+ * @class TextureManager
+ * @description Caches loaded images and GL textures so that many drawables
+ * sharing the same texture path download and upload the image only once.
+ *
+ * Textures are immutable after upload in this engine, so the same GL texture
+ * object can safely be bound by any number of objects. The GL-texture cache is
+ * keyed by path *and* filter mode, because pixel-art (NEAREST) and smooth
+ * (LINEAR) sampling require separate texture objects.
+ */
+class TextureManager {
+  /**
+   * @method loadImage
+   * @description Loads (and caches) an HTMLImageElement for a given path.
+   * Concurrent requests for the same path share a single in-flight load.
+   * @param {string} path - The path (or data URL) of the image
+   * @returns {Promise<HTMLImageElement>} - The loaded image
+   */
+  static loadImage(path) {
+    if (TextureManager.images.has(path)) {
+      return TextureManager.images.get(path);
+    }
+
+    const promise = new Promise((resolve, reject) => {
+      const image = new Image();
+      image.crossOrigin = "Anonymous";
+      image.addEventListener("load", () => resolve(image));
+      image.addEventListener("error", () => {
+        TextureManager.images.delete(path);
+        reject(
+          new Error(
+            `[TextureManager.js] > Failed to load image: ${path}. Check that the file exists and the path is correct.`
+          )
+        );
+      });
+      image.src = path;
+    });
+
+    TextureManager.images.set(path, promise);
+    return promise;
+  }
+
+  /**
+   * @method getTexture
+   * @description Returns a cached GL texture for the given path, creating and
+   * uploading it on first request. Subsequent calls reuse the same texture.
+   * @param {string} path - The path (or data URL) of the texture
+   * @param {boolean} pixelart - Whether to sample with NEAREST (pixel art) filtering
+   * @returns {Promise<{texture: WebGLTexture, width: number, height: number}>}
+   */
+  static getTexture(path, pixelart = false) {
+    const key = `${path}|${pixelart ? "nearest" : "linear"}`;
+    if (TextureManager.textures.has(key)) {
+      return TextureManager.textures.get(key);
+    }
+
+    const promise = TextureManager._upload(path, pixelart);
+    TextureManager.textures.set(key, promise);
+    return promise;
+  }
+
+  /**
+   * @method _upload
+   * @description Loads the image (via the shared image cache) and uploads it
+   * as a GL texture with the requested filtering.
+   * @private
+   */
+  static _upload(path, pixelart) {
+    return TextureManager.loadImage(path).then((image) => {
+      const gl = GLManager.getGL();
+      if (!gl) {
+        throw new Error(
+          "[TextureManager] > No GL context set. Create an Emerald instance before loading textures."
+        );
+      }
+
+      const texture = gl.createTexture();
+      gl.bindTexture(gl.TEXTURE_2D, texture);
+      gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+      gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+      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);
+      const filter = 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.texImage2D(
+        gl.TEXTURE_2D,
+        0,
+        gl.RGBA,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        image
+      );
+
+      return { texture, width: image.width, height: image.height };
+    });
+  }
+
+  /**
+   * @method restoreAll
+   * @description Re-uploads every cached texture after a WebGL context loss.
+   * The image cache survives the loss, so this is upload-only (no network).
+   * Reference counts are untouched — they track logical ownership by
+   * drawables, which still exist.
+   */
+  static restoreAll() {
+    for (const key of Array.from(TextureManager.textures.keys())) {
+      const sep = key.lastIndexOf("|");
+      const path = key.slice(0, sep);
+      const pixelart = key.slice(sep + 1) === "nearest";
+      TextureManager.textures.set(key, TextureManager._upload(path, pixelart));
+    }
+  }
+
+  /**
+   * @method preload
+   * @description Eagerly loads a list of texture paths so they are ready (and
+   * cached) before the first frame that needs them.
+   * @param {string[]} paths - The texture paths to preload
+   * @param {boolean} pixelart - Whether to use pixel-art filtering
+   * @returns {Promise<void>}
+   */
+  static async preload(paths, pixelart = false) {
+    await Promise.all(
+      paths.map((path) => TextureManager.getTexture(path, pixelart))
+    );
+  }
+
+  /**
+   * @method has
+   * @description Checks whether a GL texture is already cached for a path
+   * @param {string} path - The texture path
+   * @param {boolean} pixelart - Whether the pixel-art variant is meant
+   * @returns {boolean}
+   */
+  static has(path, pixelart = false) {
+    return TextureManager.textures.has(
+      `${path}|${pixelart ? "nearest" : "linear"}`
+    );
+  }
+
+  /**
+   * @method retain
+   * @description Increments the reference count for a cached texture. Every
+   * Drawable that resolves a texture through getTexture() retains it; when the
+   * last user releases it, the GL texture is freed. Call retain/release in
+   * pairs (Drawable.dispose does the release for you).
+   * @param {string} path - The texture path
+   * @param {boolean} pixelart - Whether the pixel-art variant is meant
+   */
+  static retain(path, pixelart = false) {
+    const key = `${path}|${pixelart ? "nearest" : "linear"}`;
+    TextureManager.refs.set(key, (TextureManager.refs.get(key) || 0) + 1);
+  }
+
+  /**
+   * @method release
+   * @description Decrements a texture's reference count; when it reaches zero
+   * the GL texture is deleted and dropped from the cache (the CPU-side image
+   * cache is kept so a later reload is cheap).
+   * @param {string} path - The texture path
+   * @param {boolean} pixelart - Whether the pixel-art variant is meant
+   */
+  static release(path, pixelart = false) {
+    const key = `${path}|${pixelart ? "nearest" : "linear"}`;
+    const count = TextureManager.refs.get(key);
+    if (count == null) return;
+    if (count > 1) {
+      TextureManager.refs.set(key, count - 1);
+      return;
+    }
+    TextureManager.refs.delete(key);
+    const promise = TextureManager.textures.get(key);
+    TextureManager.textures.delete(key);
+    const gl = GLManager.getGL();
+    if (promise && gl) {
+      promise.then(({ texture }) => gl.deleteTexture(texture)).catch(() => {});
+    }
+  }
+
+  /**
+   * @method refCount
+   * @description Current reference count for a texture (0 if uncached).
+   * @returns {number}
+   */
+  static refCount(path, pixelart = false) {
+    return (
+      TextureManager.refs.get(`${path}|${pixelart ? "nearest" : "linear"}`) || 0
+    );
+  }
+
+  /**
+   * @method clear
+   * @description Deletes all cached GL textures and clears the image cache.
+   * Useful when tearing down a context or freeing memory between levels.
+   */
+  static clear() {
+    const gl = GLManager.getGL();
+    if (gl) {
+      TextureManager.textures.forEach((promise) => {
+        promise
+          .then(({ texture }) => gl.deleteTexture(texture))
+          .catch(() => {});
+      });
+    }
+    TextureManager.textures.clear();
+    TextureManager.images.clear();
+    TextureManager.refs.clear();
+  }
+}
+
+TextureManager.images = new Map();
+TextureManager.textures = new Map();
+TextureManager.refs = new Map();
+
+export default TextureManager;

package/src/particlesystem/Particle.js

@@ -10,12 +10,24 @@ import Instance from "../Instance.js";
  * @param {ParticleSettings} settings - The settings for the particle
  */
 class Particle {
-  constructor(instancedTexture, position, rotation, scale, settings) {
+  constructor(instancedTexture, position, rotation, scale, settings, velocity) {
+    this.reset(instancedTexture, position, rotation, scale, settings, velocity);
+  }
+
+  /**
+   * @method reset
+   * @description (Re)initializes the particle. Used by the pool so particle
+   * objects can be reused without allocating. `velocity` overrides
+   * settings.velocity when provided (avoids a ParticleSettings allocation per
+   * particle).
+   */
+  reset(instancedTexture, position, rotation, scale, settings, velocity) {
     this.settings = settings;
     this.lifetime = settings.lifetime;
     this.age = 0;
-    this.velocity = { ...settings.velocity };
-    this.gravity = { ...settings.gravity };
+    const v = velocity || settings.velocity;
+    this.velocity = { x: v.x, y: v.y };
+    this.gravity = { x: settings.gravity.x, y: settings.gravity.y };
     this.instance = new Instance(
       `Particle at ${position.x}, ${position.y}`,
       position,
@@ -23,16 +35,68 @@ class Particle {
       rotation,
       settings.frame
     );
+    /** @private */
+    this._baseScaleX = scale ? scale.x : 1;
+    /** @private */
+    this._baseScaleY = scale ? scale.y : 1;
+
+    /** @private */
+    this._colFrom = null;
+    /** @private */
+    this._colTo = null;
+    if (settings.colorOverLife) {
+      this._colFrom = Particle._normColor(settings.colorOverLife.from);
+      this._colTo = Particle._normColor(settings.colorOverLife.to);
+    }
+
     this.instancedTexture = instancedTexture;
-    if(this.settings.animation) {
+    if (this.settings.animation) {
       this.instance.playAnimation(
         this.settings.animation.frames,
         this.settings.animation.speed
       );
     }
+    this._applyOverLife(0);
     instancedTexture.addInstance(this.instance);
   }
 
+  /** @private */
+  static _normColor(c) {
+    if (!c) return [1, 1, 1];
+    return [(c.r ?? 255) / 255, (c.g ?? 255) / 255, (c.b ?? 255) / 255];
+  }
+
+  /** @private */
+  _applyOverLife(t) {
+    const s = this.settings;
+    const tr = this.instance.transform;
+
+    if (s.scaleOverLife) {
+      const m =
+        s.scaleOverLife.from + (s.scaleOverLife.to - s.scaleOverLife.from) * t;
+      tr.scale.x = this._baseScaleX * m;
+      tr.scale.y = this._baseScaleY * m;
+    }
+
+    if (this._colFrom || s.alphaOverLife) {
+      let r = 1;
+      let g = 1;
+      let b = 1;
+      let a = 1;
+      if (this._colFrom) {
+        r = this._colFrom[0] + (this._colTo[0] - this._colFrom[0]) * t;
+        g = this._colFrom[1] + (this._colTo[1] - this._colFrom[1]) * t;
+        b = this._colFrom[2] + (this._colTo[2] - this._colFrom[2]) * t;
+      }
+      if (s.alphaOverLife) {
+        a =
+          s.alphaOverLife.from +
+          (s.alphaOverLife.to - s.alphaOverLife.from) * t;
+      }
+      this.instance.setColor(r, g, b, a);
+    }
+  }
+
   /**
    * @method update
    * @description Updates the particle
@@ -40,12 +104,23 @@ class Particle {
    */
   update(dt) {
     this.age += dt;
-    // Apply gravity
+    const s = this.settings;
+
     this.velocity.x += this.gravity.x * dt;
     this.velocity.y += this.gravity.y * dt;
-    // Update position
+    if (s.drag) {
+      const damp = Math.max(0, 1 - s.drag * dt);
+      this.velocity.x *= damp;
+      this.velocity.y *= damp;
+    }
     this.instance.transform.position.x += this.velocity.x * dt;
     this.instance.transform.position.y += this.velocity.y * dt;
+    if (s.rotationSpeed) {
+      this.instance.transform.rotation += s.rotationSpeed * dt;
+    }
+
+    const t = this.lifetime > 0 ? Math.min(1, this.age / this.lifetime) : 1;
+    this._applyOverLife(t);
   }
 
   /**
@@ -64,7 +139,7 @@ class Particle {
   destroy() {
     if (this.instancedTexture && this.instance) {
       if (this.instancedTexture.instances.length > 0) {
-        if(this.instancedTexture.getInstanceWithId(this.instance.id)) {
+        if (this.instancedTexture.getInstanceWithId(this.instance.id)) {
           this.instancedTexture.removeInstance(this.instance.id);
         }
       }

package/src/particlesystem/ParticleSettings.js

@@ -24,12 +24,20 @@ class ParticleSettings {
     amount = 10,
     direction = new Vector2(1, 0),
     spread = Math.PI / 4,
-    emissionRate = Infinity, // particles per second
+    emissionRate = Infinity,
     frame,
     offset,
     rotation,
     scale,
-    animation
+    animation,
+    shape = "cone",
+    shapeRadius = 0,
+    shapeSize = new Vector2(0, 0),
+    scaleOverLife = null,
+    alphaOverLife = null,
+    colorOverLife = null,
+    rotationSpeed = 0,
+    drag = 0,
   } = {}) {
     this.lifetime = lifetime;
     this.velocity = velocity;
@@ -43,7 +51,17 @@ class ParticleSettings {
     this.rotation = rotation;
     this.scale = scale;
     this.animation = animation;
+
+    this.shape = shape;
+    this.shapeRadius = shapeRadius;
+    this.shapeSize = shapeSize;
+
+    this.scaleOverLife = scaleOverLife;
+    this.alphaOverLife = alphaOverLife;
+    this.colorOverLife = colorOverLife;
+    this.rotationSpeed = rotationSpeed;
+    this.drag = drag;
   }
 }
 
-export default ParticleSettings; 
+export default ParticleSettings;