emeraldengine 2.2.0 → 3.0.0

package/src/ParticleEmitter.js

@@ -0,0 +1,284 @@
+import GameObject from "./components/GameObject.js";
+import Texture from "./Texture.js";
+import Color from "./Color.js";
+import { Vector2, Vector3 } from "./Physics.js";
+
+const DEFAULT_CAPACITY = 256;
+const PARK_Y = -1e9;
+
+/**
+ * @class ParticleEmitter
+ * @description A reliable, allocation-free particle system built from a fixed
+ * pool of ordinary textured GameObjects. Each live particle's transform, tint
+ * and opacity are driven by hand every frame — there is no instanced-draw /
+ * dynamic-buffer lifecycle to desync, so it keeps drawing for the whole session
+ * (unlike the InstancedTexture-based `Particles`, which can stop emitting after
+ * heavy reuse on some GPUs).
+ *
+ * Spawn with `burst(n, cfg)` or `emit(cfg)`; advance with `update(dt)` once per
+ * frame. Every `cfg` field is optional and has a sensible default, so the
+ * minimal call is `emitter.burst(8, { x, y })`.
+ *
+ * @example
+ * const fx = new ParticleEmitter(scene, { texture: smokeImg, layer: 50 });
+ * fx.burst(12, {
+ *   x: 100, y: 200, dir: -Math.PI / 2, spread: Math.PI, speed: 180,
+ *   gy: -300, drag: 2, life: 0.4, size: 8, sFrom: 1, sTo: 0.1,
+ *   aFrom: 0.7, aTo: 0, cr: 255, cg: 220, cb: 120, additive: true,
+ *   shape: "circle", radius: 6,
+ * });
+ * // in the loop: fx.update(dt);
+ */
+class ParticleEmitter {
+  /**
+   * @param {Scene} scene - Scene the particle GameObjects are added to
+   * @param {Object} [options]
+   * @param {string|HTMLImageElement} [options.texture] - Particle sprite source
+   * @param {number} [options.capacity=256] - Pool size (max live particles)
+   * @param {number} [options.layer=0] - Render layer for every particle
+   * @param {boolean} [options.pixelart=false] - Pixel-art sampling for the sprite
+   * @param {Function} [options.spriteFactory] - `(texture, options) => Drawable`
+   *   override used to build each particle's drawable (handy for tests / custom
+   *   shaders). Defaults to a non-lit `Texture`.
+   */
+  constructor(scene, options = {}) {
+    this.scene = scene;
+    this.capacity = options.capacity ?? DEFAULT_CAPACITY;
+    this.layer = options.layer ?? 0;
+
+    const texture = options.texture ?? options.texturePath ?? null;
+    const makeSprite =
+      options.spriteFactory ||
+      ((tex) =>
+        new Texture(
+          tex,
+          0,
+          0,
+          1,
+          1,
+          0,
+          false,
+          options.pixelart ?? false,
+          false
+        ));
+
+    this.parts = [];
+    this.free = [];
+
+    for (let i = 0; i < this.capacity; i++) {
+      const go = new GameObject(
+        "particle",
+        new Vector3(0, PARK_Y, 0),
+        0,
+        new Vector2(4, 4)
+      );
+      const drawable = makeSprite(texture, options);
+      if (drawable && typeof drawable.setUseLighting === "function") {
+        drawable.setUseLighting(false);
+      }
+      go.addComponent(drawable);
+      go.setLayer(this.layer);
+      go.setOpacity(0);
+      if (scene && typeof scene.add === "function") scene.add(go);
+
+      const p = {
+        go,
+        drawable,
+        color: new Color(255, 255, 255, 255),
+        alive: false,
+        x: 0,
+        y: 0,
+        vx: 0,
+        vy: 0,
+        gx: 0,
+        gy: 0,
+        drag: 0,
+        age: 0,
+        life: 1,
+        base: 4,
+        sFrom: 1,
+        sTo: 1,
+        aFrom: 1,
+        aTo: 0,
+        rot: 0,
+        rotSpeed: 0,
+        additive: false,
+      };
+      this.parts.push(p);
+      this.free.push(p);
+    }
+  }
+
+  /**
+   * @member activeCount
+   * @description Number of particles currently alive.
+   */
+  get activeCount() {
+    return this.capacity - this.free.length;
+  }
+
+  /**
+   * @method emit
+   * @description Spawns a single particle. Returns the emitter for chaining.
+   * @param {Object} cfg - Spawn config (see class example; all fields optional)
+   */
+  emit(cfg = {}) {
+    this._spawn(cfg);
+    return this;
+  }
+
+  /**
+   * @method burst
+   * @description Spawns `n` particles with the same config.
+   * @param {number} n - How many to spawn
+   * @param {Object} cfg - Spawn config
+   */
+  burst(n, cfg = {}) {
+    for (let i = 0; i < n; i++) this._spawn(cfg);
+    return this;
+  }
+
+  /** @private */
+  _spawn(cfg) {
+    const p = this.free.pop();
+    if (!p) return;
+
+    p.alive = true;
+
+    const x = cfg.x || 0;
+    const y = cfg.y || 0;
+    let ox = 0;
+    let oy = 0;
+    const shape = cfg.shape;
+    if (shape === "ring") {
+      const a = Math.random() * Math.PI * 2;
+      const r = cfg.radius || 0;
+      ox = Math.cos(a) * r;
+      oy = Math.sin(a) * r;
+    } else if (shape === "circle") {
+      const a = Math.random() * Math.PI * 2;
+      const r = Math.sqrt(Math.random()) * (cfg.radius || 0);
+      ox = Math.cos(a) * r;
+      oy = Math.sin(a) * r;
+    } else if (shape === "box") {
+      ox = (Math.random() - 0.5) * (cfg.boxw || 0);
+      oy = (Math.random() - 0.5) * (cfg.boxh || 0);
+    }
+    p.x = x + ox;
+    p.y = y + oy;
+
+    const dir = cfg.dir || 0;
+    const spread = cfg.spread || 0;
+    const speed = cfg.speed || 0;
+    const ang = dir + (Math.random() - 0.5) * spread;
+    const spd = speed * (0.6 + Math.random() * 0.4);
+    p.vx = Math.cos(ang) * spd;
+    p.vy = Math.sin(ang) * spd;
+
+    p.gx = cfg.gx || 0;
+    p.gy = cfg.gy || 0;
+    p.drag = cfg.drag || 0;
+    p.age = 0;
+    p.life = cfg.life || 0.5;
+    p.base = cfg.size ?? 6;
+    p.sFrom = cfg.sFrom ?? 1;
+    p.sTo = cfg.sTo ?? 0;
+    p.aFrom = cfg.aFrom ?? 1;
+    p.aTo = cfg.aTo ?? 0;
+    p.rot = cfg.rot ?? Math.random() * Math.PI * 2;
+    p.rotSpeed = cfg.rotSpeed || 0;
+
+    p.color.r = cfg.cr ?? 255;
+    p.color.g = cfg.cg ?? 255;
+    p.color.b = cfg.cb ?? 255;
+    p.color.a = 255;
+    if (p.drawable) {
+      if (typeof p.drawable.setColor === "function")
+        p.drawable.setColor(p.color);
+      if (typeof p.drawable.setBlendMode === "function") {
+        p.drawable.setBlendMode(cfg.additive ? "additive" : "normal");
+      }
+    }
+
+    const tr = p.go.transform;
+    tr.position.x = p.x;
+    tr.position.y = p.y;
+    tr.scale.x = p.base * p.sFrom;
+    tr.scale.y = p.base * p.sFrom;
+    tr.rotation = p.rot;
+    p.go.setOpacity(p.aFrom);
+  }
+
+  /**
+   * @method update
+   * @description Advances and renders every live particle. Call once per frame.
+   * @param {number} dt - Seconds since the last frame
+   */
+  update(dt) {
+    for (let i = 0; i < this.parts.length; i++) {
+      const p = this.parts[i];
+      if (!p.alive) continue;
+
+      p.age += dt;
+      if (p.age >= p.life) {
+        p.alive = false;
+        p.go.setOpacity(0);
+        p.go.transform.position.y = PARK_Y;
+        this.free.push(p);
+        continue;
+      }
+
+      const t = p.age / p.life;
+      p.vx += p.gx * dt;
+      p.vy += p.gy * dt;
+      if (p.drag) {
+        const d = Math.max(0, 1 - p.drag * dt);
+        p.vx *= d;
+        p.vy *= d;
+      }
+      p.x += p.vx * dt;
+      p.y += p.vy * dt;
+      p.rot += p.rotSpeed * dt;
+
+      const sc = p.base * (p.sFrom + (p.sTo - p.sFrom) * t);
+      const tr = p.go.transform;
+      tr.position.x = p.x;
+      tr.position.y = p.y;
+      tr.scale.x = sc;
+      tr.scale.y = sc;
+      tr.rotation = p.rot;
+      p.go.setOpacity(p.aFrom + (p.aTo - p.aFrom) * t);
+    }
+  }
+
+  /**
+   * @method reset
+   * @description Kills every live particle immediately (no fade).
+   */
+  reset() {
+    for (let i = 0; i < this.parts.length; i++) {
+      const p = this.parts[i];
+      if (!p.alive) continue;
+      p.alive = false;
+      p.go.setOpacity(0);
+      p.go.transform.position.y = PARK_Y;
+    }
+    this.free = this.parts.slice();
+  }
+
+  /**
+   * @method destroy
+   * @description Removes every particle GameObject from the scene.
+   */
+  destroy() {
+    if (this.scene && typeof this.scene.remove === "function") {
+      for (let i = 0; i < this.parts.length; i++) {
+        this.scene.remove(this.parts[i].go);
+      }
+    }
+    this.parts = [];
+    this.free = [];
+  }
+}
+
+export default ParticleEmitter;

package/src/Physics.js

@@ -1,5 +1,26 @@
 import * as planck from "planck";
 
+/**
+ * @function dispatchCollision
+ * @description Calls onCollisionEnter/onCollisionExit on an object and its
+ * component list (Behaviours), passing the other object. Duck-typed so this
+ * module doesn't need to import the component classes.
+ * @private
+ */
+function dispatchCollision(object, other, contact, type) {
+  if (!object) return;
+  if (typeof object[type] === "function") {
+    object[type](other, contact);
+  }
+  if (Array.isArray(object.components)) {
+    for (const comp of object.components) {
+      if (comp && typeof comp[type] === "function") {
+        comp[type](other, contact);
+      }
+    }
+  }
+}
+
 /**
  * @class Physics
  * @description Represents the physics engine
@@ -15,6 +36,101 @@ class Physics {
     planck.Settings.velocityThreshold = velocityThreshold;
     this.gravity = gravity;
     this.scale = scale;
+
+    this.fixedTimeStep = 1 / 60;
+    this.maxSubSteps = 5;
+    /** @private */
+    this._accumulator = 0;
+
+    this._dispatchContacts();
+  }
+
+  /**
+   * @method _dispatchContacts
+   * @description Routes planck contacts to the owning objects so Behaviour
+   * components receive onCollisionEnter/onCollisionExit. Bodies created through
+   * RigidBody carry the owner via userData.
+   * @private
+   */
+  _dispatchContacts() {
+    const fire = (contact, type) => {
+      const a = contact.getFixtureA().getBody().getUserData();
+      const b = contact.getFixtureB().getBody().getUserData();
+      const objA = a && a.parentObject ? a.parentObject : null;
+      const objB = b && b.parentObject ? b.parentObject : null;
+      dispatchCollision(objA, objB, contact, type);
+      dispatchCollision(objB, objA, contact, type);
+    };
+    this.world.on("begin-contact", (contact) =>
+      fire(contact, "onCollisionEnter")
+    );
+    this.world.on("end-contact", (contact) => fire(contact, "onCollisionExit"));
+  }
+
+  /**
+   * @method raycast
+   * @description Casts a ray through the world and returns the closest hit.
+   * @param {Object} origin - World-space { x, y } start point
+   * @param {Object} direction - Ray direction { x, y } (need not be normalized)
+   * @param {number} maxDistance - Max ray length in world units
+   * @returns {{object, rigidBody, point, normal, fraction}|null}
+   */
+  raycast(origin, direction, maxDistance) {
+    const scale = this.scale;
+    const len = Math.hypot(direction.x, direction.y) || 1;
+    const dx = direction.x / len;
+    const dy = direction.y / len;
+    const p1 = new planck.Vec2(origin.x / scale, origin.y / scale);
+    const p2 = new planck.Vec2(
+      (origin.x + dx * maxDistance) / scale,
+      (origin.y + dy * maxDistance) / scale
+    );
+
+    let result = null;
+    this.world.rayCast(p1, p2, (fixture, point, normal, fraction) => {
+      const rb = fixture.getBody().getUserData();
+      result = {
+        object: rb && rb.parentObject ? rb.parentObject : null,
+        rigidBody: rb || null,
+        point: { x: point.x * scale, y: point.y * scale },
+        normal: { x: normal.x, y: normal.y },
+        fraction,
+      };
+      return fraction;
+    });
+    return result;
+  }
+
+  /**
+   * @method queryPoint
+   * @description Returns the objects whose colliders contain a world-space point.
+   * @param {Object} point - World-space { x, y }
+   * @returns {Array} - Owning objects at the point
+   */
+  queryPoint(point) {
+    const p = new planck.Vec2(point.x / this.scale, point.y / this.scale);
+    const results = [];
+    for (let body = this.world.getBodyList(); body; body = body.getNext()) {
+      for (let f = body.getFixtureList(); f; f = f.getNext()) {
+        if (f.testPoint(p)) {
+          const rb = body.getUserData();
+          if (rb && rb.parentObject) results.push(rb.parentObject);
+          break;
+        }
+      }
+    }
+    return results;
+  }
+
+  /**
+   * @method setFixedTimeStep
+   * @description Sets the fixed physics step (seconds) and optional substep cap.
+   * @param {number} step - Fixed step in seconds (e.g. 1/60)
+   * @param {number} [maxSubSteps] - Max steps per process() call (spiral guard)
+   */
+  setFixedTimeStep(step, maxSubSteps = this.maxSubSteps) {
+    if (step > 0) this.fixedTimeStep = step;
+    this.maxSubSteps = maxSubSteps;
   }
 
   /**
@@ -100,7 +216,22 @@ class Physics {
    * @param {number} dt - The delta time
    */
   process(dt) {
-    this.world.step(dt);
+    if (!isFinite(dt) || dt <= 0) return;
+
+    this._accumulator += dt;
+    let steps = 0;
+    while (
+      this._accumulator >= this.fixedTimeStep &&
+      steps < this.maxSubSteps
+    ) {
+      this.world.step(this.fixedTimeStep);
+      this._accumulator -= this.fixedTimeStep;
+      steps++;
+    }
+
+    if (steps === this.maxSubSteps) {
+      this._accumulator = 0;
+    }
   }
 
   /**
@@ -111,6 +242,7 @@ class Physics {
     this.world = new planck.World({
       gravity: new planck.Vec2(0, this.gravity),
     });
+    this._accumulator = 0;
   }
 
   /**
@@ -152,8 +284,31 @@ class Physics {
  * @param {number} y - The y coordinate of the vector
  */
 class Vector2 {
-  constructor(x, y) {
-    return new planck.Vec2(x, y);
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+  }
+
+  /**
+   * @method set
+   * @description Sets the x and y coordinates in place
+   * @param {number} x - The x coordinate
+   * @param {number} y - The y coordinate
+   * @returns {Vector2} - This vector
+   */
+  set(x, y) {
+    this.x = x;
+    this.y = y;
+    return this;
+  }
+
+  /**
+   * @method clone
+   * @description Returns a copy of the vector
+   * @returns {Vector2} - The cloned vector
+   */
+  clone() {
+    return new Vector2(this.x, this.y);
   }
 
   /**
@@ -195,8 +350,34 @@ class Vector2 {
  * @param {number} z - The z coordinate of the vector
  */
 class Vector3 {
-  constructor(x, y, z) {
-    return new planck.Vec3(x, y, z);
+  constructor(x = 0, y = 0, z = 0) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+  }
+
+  /**
+   * @method set
+   * @description Sets the x, y and z coordinates in place
+   * @param {number} x - The x coordinate
+   * @param {number} y - The y coordinate
+   * @param {number} z - The z coordinate
+   * @returns {Vector3} - This vector
+   */
+  set(x, y, z) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+    return this;
+  }
+
+  /**
+   * @method clone
+   * @description Returns a copy of the vector
+   * @returns {Vector3} - The cloned vector
+   */
+  clone() {
+    return new Vector3(this.x, this.y, this.z);
   }
 
   /**

package/src/Pool.js

@@ -0,0 +1,85 @@
+/**
+ * @class Pool
+ * @description Generic object pool to avoid per-frame allocations for churny
+ * objects (bullets, particles, enemies). Provide a factory and an optional
+ * reset function; acquire reused objects and release them when done.
+ *
+ * @example
+ * const bullets = new Pool(() => new Bullet(), (b, x, y) => b.spawn(x, y), 50);
+ * const b = bullets.acquire(px, py);
+ * // later...
+ * bullets.release(b);
+ */
+class Pool {
+  /**
+   * @param {Function} factory - Creates a new pooled object
+   * @param {Function} [reset] - Called on acquire as reset(obj, ...args)
+   * @param {number} [initialSize] - Number of objects to pre-create
+   */
+  constructor(factory, reset = null, initialSize = 0) {
+    if (typeof factory !== "function") {
+      throw new Error("[Pool] > factory must be a function");
+    }
+    this.factory = factory;
+    this.reset = reset;
+    this.available = [];
+    this.active = new Set();
+
+    for (let i = 0; i < initialSize; i++) {
+      this.available.push(factory());
+    }
+  }
+
+  /**
+   * @method acquire
+   * @description Returns a pooled object (reused or freshly created). Extra
+   * arguments are forwarded to the reset function.
+   * @returns {*} - The acquired object
+   */
+  acquire(...args) {
+    const obj = this.available.length ? this.available.pop() : this.factory();
+    this.active.add(obj);
+    if (this.reset) this.reset(obj, ...args);
+    return obj;
+  }
+
+  /**
+   * @method release
+   * @description Returns an object to the pool.
+   * @param {*} obj - The object to release
+   */
+  release(obj) {
+    if (this.active.delete(obj)) {
+      this.available.push(obj);
+    }
+  }
+
+  /**
+   * @method releaseAll
+   * @description Returns every active object to the pool.
+   */
+  releaseAll() {
+    for (const obj of this.active) {
+      this.available.push(obj);
+    }
+    this.active.clear();
+  }
+
+  /**
+   * @member activeCount
+   * @description Number of currently-acquired objects.
+   */
+  get activeCount() {
+    return this.active.size;
+  }
+
+  /**
+   * @member size
+   * @description Total objects managed by the pool (active + available).
+   */
+  get size() {
+    return this.available.length + this.active.size;
+  }
+}
+
+export default Pool;