emeraldengine 2.2.1 → 3.1.0

package/src/components/BoxColliderDebug.js

@@ -14,13 +14,12 @@ class BoxColliderDebug {
     this.physics = this.rigidbody.physics;
     this.scale = this.physics.getScale();
     this.color = color || new Color(255, 0, 0, 255);
+    const body = this.rigidbody.getBody();
     this.gameObject = new GameObject(
       "BoxColliderDebug",
       new Vector3(
-        this.rigidbody.getBody().getPosition().x *
-          this.rigidbody.getPhysics().getScale(),
-        this.rigidbody.getBody().getPosition().y *
-          this.rigidbody.getPhysics().getScale(),
+        body.getPosition().x * this.scale,
+        body.getPosition().y * this.scale,
         100
       ),
       this.rigidbody.getAngle(),

package/src/components/CircleCollider.js

@@ -1,4 +1,4 @@
-import * as planck from "planck";
+import { Circle } from "../physics/index.js";
 import SceneManager from "../managers/SceneManager.js";
 import CircleColliderDebug from "./CircleColliderDebug.js";
 import Collider from "./Collider.js";
@@ -22,21 +22,34 @@ class CircleCollider extends Collider {
     friction,
     restitution,
     isSensor = false,
-    parentObject = null
+    parentObject = null,
+    filter = null
   ) {
     super(rigidbody, isSensor, parentObject);
-    this.collider = rigidbody
-      .getBody()
-      .createFixture(new planck.Circle(radius), {
-        density: density,
-        friction: friction,
-        restitution: restitution,
-        isSensor: isSensor,
-      });
+    this.collider = rigidbody.createFixture(Circle(radius), {
+      density: density,
+      friction: friction,
+      restitution: restitution,
+      isSensor: isSensor,
+    });
     this.radius = radius;
     this.rigidbody.setCollider(this);
     this.name = "CircleCollider" + this.id;
-    this.debugShape = new CircleColliderDebug(this.rigidbody);
+    this._applyFilterSpec(filter);
+  }
+
+  /**
+   * @method debugShape
+   * @description Lazily builds the debug visualization on first access, so a
+   * collider stays free of any GameObject/GL allocation until it is debugged.
+   * @returns {CircleColliderDebug} - The debug shape
+   */
+  get debugShape() {
+    if (!this._debugShape) {
+      /** @private */
+      this._debugShape = new CircleColliderDebug(this.rigidbody);
+    }
+    return this._debugShape;
   }
 
   /**
@@ -55,9 +68,10 @@ class CircleCollider extends Collider {
    * @description Hides the debug shape of the collider
    */
   hideDebugShape() {
+    if (!this._debugShape) return;
     var scene = SceneManager.getScene();
     if (scene) {
-      scene.remove(this.debugShape.gameObject);
+      scene.remove(this._debugShape.gameObject);
     }
   }
 

package/src/components/CircleColliderDebug.js

@@ -1,4 +1,4 @@
-import  Color from "../Color.js";
+import Color from "../Color.js";
 import { Vector2, Vector3 } from "../Physics.js";
 import { Circle2D } from "../Shapes.js";
 import GameObject from "./GameObject.js";
@@ -9,28 +9,29 @@ import GameObject from "./GameObject.js";
  * @param {Color} color - The color of the collider
  */
 class CircleColliderDebug {
-    constructor(rigidbody, color = null) {
-        this.rigidbody = rigidbody;
-        this.physics = this.rigidbody.physics;
-        this.scale = this.physics.getScale();
-        this.color = color || new Color(255, 0, 0, 255);
-        this.gameObject = new GameObject(
-            "CircleColliderDebug",
-            new Vector3(
-                this.rigidbody.getBody().getPosition().x * this.scale,
-                this.rigidbody.getBody().getPosition().y * this.scale,
-                100
-            ),
-            this.rigidbody.getAngle(),
-            new Vector2(
-                this.rigidbody.getCollider().getRadius() * this.scale,
-                this.rigidbody.getCollider().getRadius() * this.scale
-            )
-        );
-        this.gameObject.addComponent(new Circle2D());
-        this.gameObject.getComponent(Circle2D).setColor(this.color);
-        this.gameObject.setOpacity(0.3);
-    }
+  constructor(rigidbody, color = null) {
+    this.rigidbody = rigidbody;
+    this.physics = this.rigidbody.physics;
+    this.scale = this.physics.getScale();
+    this.color = color || new Color(255, 0, 0, 255);
+    const body = this.rigidbody.getBody();
+    this.gameObject = new GameObject(
+      "CircleColliderDebug",
+      new Vector3(
+        body.getPosition().x * this.scale,
+        body.getPosition().y * this.scale,
+        100
+      ),
+      this.rigidbody.getAngle(),
+      new Vector2(
+        this.rigidbody.getCollider().getRadius() * this.scale,
+        this.rigidbody.getCollider().getRadius() * this.scale
+      )
+    );
+    this.gameObject.addComponent(new Circle2D());
+    this.gameObject.getComponent(Circle2D).setColor(this.color);
+    this.gameObject.setOpacity(0.3);
+  }
 }
 
-export default CircleColliderDebug;
+export default CircleColliderDebug;

package/src/components/Collider.js

@@ -1,4 +1,5 @@
 import IDManager from "../managers/IDManager.js";
+import CollisionLayers from "../CollisionLayers.js";
 
 /**
  * @class Collider
@@ -7,45 +8,160 @@ import IDManager from "../managers/IDManager.js";
  * @param {GameObject} parentObject - The parent object of the collider
  */
 class Collider {
-    constructor(rigidbody, isSensor = false, parentObject = null) {
-        this.rigidbody = rigidbody;
-        this.parentObject = parentObject;
-        this.isSensor = isSensor;
-        this.id = IDManager.generateUniqueID();
-        this.name = "Collider" + this.id;
-    }
+  constructor(rigidbody, isSensor = false, parentObject = null) {
+    this.rigidbody = rigidbody;
+    this.parentObject = parentObject;
+    this.isSensor = isSensor;
+    this.id = IDManager.generateUniqueID();
+    this.name = "Collider" + this.id;
 
-    /**
-     * @method getRigidBody
-     * @description Returns the rigidbody of the collider
-     */
-    getRigidBody() {
-        return this.rigidbody;
-    }
+    /** @private */
+    this._debugShape = null;
+  }
 
-    /**
-     * @method getCollider
-     * @description Returns the collider
-     */
-    getCollider() {
-        return this.collider;
-    }
+  /**
+   * @method syncDebugShape
+   * @description Mirrors a transform onto the debug shape, but only if one has
+   * already been created. Never forces lazy creation.
+   *
+   * The rigidbody's spawn offset is added back, because the collider sits at
+   * `transform + offset` while the transform tracks the renderable. Without it
+   * the debug shape would drift away from the collider it is supposed to be
+   * showing on any body built with an offset.
+   *
+   * @param {Transform} transform - The source transform
+   */
+  syncDebugShape(transform) {
+    if (!this._debugShape) return;
+    const t = this._debugShape.gameObject.transform;
+    const offset =
+      this.rigidbody && typeof this.rigidbody.getOffset === "function"
+        ? this.rigidbody.getOffset()
+        : null;
+    t.position.x = transform.position.x + (offset ? offset.x : 0);
+    t.position.y = transform.position.y + (offset ? offset.y : 0);
+    t.rotation = transform.rotation;
+  }
 
-    /**
-     * @method setParent
-     * @description Sets the parent object of the collider
-     */
-    setParent(parent) {
-        this.parentObject = parent;
+  /**
+   * @method setFilter
+   * @description Sets the raw collision filter on this collider's
+   * fixture. Two fixtures collide only when each one's category bit is present
+   * in the other's mask. Subclasses must have created `this.collider`
+   * (the fixture) first.
+   * @param {Object} filter - { category, mask, group }
+   * @param {number} [filter.category=0x0001] - This fixture's category bits
+   * @param {number} [filter.mask=0xFFFF] - Bits this fixture collides with
+   * @param {number} [filter.group=0] - Group index (>0 always collide, <0 never)
+   * @returns {Collider} - this
+   */
+  setFilter({ category = 0x0001, mask = 0xffff, group = 0 } = {}) {
+    if (this.collider && typeof this.collider.setFilterData === "function") {
+      this.collider.setFilterData({
+        categoryBits: category,
+        maskBits: mask,
+        groupIndex: group,
+      });
+      /** @private */
+      this._filter = { category, mask, group };
     }
+    return this;
+  }
+
+  /**
+   * @method setCategory
+   * @description Sets which named layer this collider belongs to (its category
+   * bits), preserving the current mask/group. See {@link CollisionLayers}.
+   * @param {string|number} layer - Layer name or raw category bits
+   * @returns {Collider} - this
+   */
+  setCategory(layer) {
+    const category =
+      typeof layer === "number" ? layer : CollisionLayers.bit(layer);
+    const current = this._filter || {};
+    return this.setFilter({
+      category,
+      mask: current.mask ?? 0xffff,
+      group: current.group ?? 0,
+    });
+  }
+
+  /**
+   * @method setCollidesWith
+   * @description Sets which layers this collider can collide with (its mask),
+   * preserving the current category/group.
+   * @param {string|string[]|number} layers - Layer name(s) or raw mask bits
+   * @returns {Collider} - this
+   */
+  setCollidesWith(layers) {
+    const current = this._filter || {};
+    return this.setFilter({
+      category: current.category ?? 0x0001,
+      mask: CollisionLayers.mask(layers),
+      group: current.group ?? 0,
+    });
+  }
 
-    /**
-     * @method getParent
-     * @description Returns the parent object of the collider
-     */
-    getParent() {
-        return this.parentObject;
+  /**
+   * @method getFilter
+   * @description Returns the last applied filter, or null if none was set.
+   * @returns {{category:number, mask:number, group:number}|null}
+   */
+  getFilter() {
+    return this._filter || null;
+  }
+
+  /**
+   * @method _applyFilterSpec
+   * @description Applies a friendly filter spec from a constructor, accepting
+   * layer names or raw bits. Spec: { category, collidesWith, group }.
+   * @private
+   */
+  _applyFilterSpec(spec) {
+    if (!spec) return;
+    if (spec.category != null) this.setCategory(spec.category);
+    if (spec.collidesWith != null) this.setCollidesWith(spec.collidesWith);
+    if (spec.group != null) {
+      const f = this._filter || {};
+      this.setFilter({
+        category: f.category ?? 0x0001,
+        mask: f.mask ?? 0xffff,
+        group: spec.group,
+      });
     }
+  }
+
+  /**
+   * @method getRigidBody
+   * @description Returns the rigidbody of the collider
+   */
+  getRigidBody() {
+    return this.rigidbody;
+  }
+
+  /**
+   * @method getCollider
+   * @description Returns the collider
+   */
+  getCollider() {
+    return this.collider;
+  }
+
+  /**
+   * @method setParent
+   * @description Sets the parent object of the collider
+   */
+  setParent(parent) {
+    this.parentObject = parent;
+  }
+
+  /**
+   * @method getParent
+   * @description Returns the parent object of the collider
+   */
+  getParent() {
+    return this.parentObject;
+  }
 }
 
-export default Collider;
+export default Collider;

package/src/components/GameObject.js

@@ -4,6 +4,7 @@ import Transform from "../Transform.js";
 import RigidBody from "./RigidBody.js";
 import Collider from "./Collider.js";
 import Drawable from "../Drawable.js";
+import Behaviour from "./Behaviour.js";
 
 /**
  * @class GameObject
@@ -24,7 +25,35 @@ class GameObject {
     this.id = IDManager.generateUniqueID();
     this.isActive = false;
     this.transform = new Transform(position, rotation, scale);
-    this.opacity = 1.0; // 0..1 opacity multiplier for this GameObject
+    this.opacity = 1.0;
+
+    this.layer = 0;
+    this.screenSpace = false;
+  }
+
+  /**
+   * @method setLayer
+   * @description Sets the render layer. Objects are drawn by layer first, then
+   * by z within a layer.
+   * @param {number} layer - The layer index
+   * @returns {GameObject} - this
+   */
+  setLayer(layer) {
+    this.layer = layer;
+    return this;
+  }
+
+  /**
+   * @method setScreenSpace
+   * @description When true, the object ignores the camera (fixed on screen),
+   * useful for HUD/UI. Position is then in pixels from the viewport center.
+   * Note: not supported for InstancedTexture-based objects.
+   * @param {boolean} value
+   * @returns {GameObject} - this
+   */
+  setScreenSpace(value) {
+    this.screenSpace = value;
+    return this;
   }
 
   /**
@@ -55,11 +84,57 @@ class GameObject {
     if (component instanceof RigidBody) {
       component.destroy();
     }
+    if (component instanceof Behaviour) {
+      component.onDestroy();
+    }
     this.components = this.components.filter(
       (comp) => comp.id !== component.id
     );
   }
 
+  /**
+   * @method update
+   * @description Ticks the lifecycle of Behaviour components on this object.
+   * Only Behaviours are ticked here so component types with their own update
+   * signature (e.g. InstancedTexture) are left untouched.
+   * @param {number} deltaTime - Seconds since the previous frame (time-scaled)
+   */
+  update(deltaTime) {
+    for (const comp of this.components) {
+      if (comp instanceof Behaviour && comp.enabled) {
+        if (!comp._started) {
+          comp._started = true;
+          comp.start();
+        }
+        comp.update(deltaTime);
+      }
+    }
+  }
+
+  /**
+   * @method setParent
+   * @description Parents this object to another GameObject (or detaches with
+   * null). The object's transform then composes on top of the parent's, so
+   * moving/rotating/scaling the parent moves its children.
+   * @param {GameObject|null} parent - The parent GameObject, or null
+   * @returns {GameObject} - this
+   */
+  setParent(parent) {
+    this.transform.setParent(parent ? parent.transform : null);
+    return this;
+  }
+
+  /**
+   * @method addChild
+   * @description Parents another GameObject to this one.
+   * @param {GameObject} child - The child GameObject
+   * @returns {GameObject} - this
+   */
+  addChild(child) {
+    child.setParent(this);
+    return this;
+  }
+
   /**
    * @method setIsActive
    * @description Sets the active state of the game object
@@ -118,6 +193,56 @@ class GameObject {
     return null;
   }
 
+  /**
+   * @method syncPhysics
+   * @description Copies simulation state (position + rotation) from this
+   * object's dynamic rigidbody onto its transform, and mirrors it onto any
+   * visible collider debug shape. Called once per frame from the render loop so
+   * draw() stays read-only and physics isn't re-applied per camera. Also
+   * forwards to components that own their own physics-driven content (e.g.
+   * InstancedTexture).
+   */
+  syncPhysics() {
+    const rigidBody = this.getComponent(RigidBody);
+    if (rigidBody && rigidBody.getType() === "dynamic") {
+      rigidBody.syncTransform(this.transform);
+      const collider = rigidBody.getCollider() || this.getComponent(Collider);
+      if (collider && typeof collider.syncDebugShape === "function") {
+        collider.syncDebugShape(this.transform);
+      }
+    }
+    for (const comp of this.components) {
+      if (comp !== rigidBody && typeof comp.syncPhysics === "function") {
+        comp.syncPhysics();
+      }
+    }
+  }
+
+  /**
+   * @method destroy
+   * @description Permanently tears the object down: disposes every Drawable's
+   * GPU resources, destroys physics bodies, and runs Behaviour.onDestroy().
+   * Use it (or Scene.remove(obj, { dispose: true })) when an object will not
+   * be re-added: plain Scene.remove() keeps GPU resources alive for re-use.
+   * Safe to call twice.
+   */
+  destroy() {
+    if (this._destroyed) return;
+    /** @private */
+    this._destroyed = true;
+    this.isActive = false;
+    for (const comp of this.components) {
+      if (comp instanceof Drawable && typeof comp.dispose === "function") {
+        comp.dispose();
+      } else if (comp instanceof RigidBody) {
+        comp.destroy();
+      } else if (comp instanceof Behaviour) {
+        comp.onDestroy();
+      }
+    }
+    this.components = [];
+  }
+
   /**
    * @method draw
    * @description Draws the game object
@@ -127,31 +252,15 @@ class GameObject {
    */
   draw(globalViewMatrix, uniformLocation, currentTime) {
     const drawable = this.getComponent(Drawable);
-    const rigidBody = this.getComponent(RigidBody);
-    const collider = this.getComponent(Collider);
-    if (rigidBody && rigidBody.getType() === "dynamic") {
-      const updatedPos = rigidBody.getBody().getPosition();
-      const rigidBodyOffset = rigidBody.getOffset();
-      const physicsScale = rigidBody.getPhysics().getScale();
-
-      this.transform.position.x =
-        updatedPos.x * physicsScale - rigidBodyOffset.x;
-      this.transform.position.y =
-        updatedPos.y * physicsScale - rigidBodyOffset.y;
-
-      if (collider) {
-        collider.debugShape.gameObject.transform.position.x =
-        this.transform.position.x;
-        collider.debugShape.gameObject.transform.position.y =
-          this.transform.position.y;
-      }
-    }
     if (drawable) {
+      const worldTransform = this.transform.parent
+        ? this.transform.getWorldTransform()
+        : this.transform;
       drawable.draw(
         globalViewMatrix,
         uniformLocation,
         currentTime,
-        this.transform
+        worldTransform
       );
     }
   }

package/src/components/PolygonCollider.js

@@ -0,0 +1,55 @@
+import { PolygonShape } from "../physics/index.js";
+import Collider from "./Collider.js";
+
+/**
+ * @class PolygonCollider
+ * @extends Collider
+ * @description A convex-polygon fixture, for collision shapes a box or
+ * circle can't approximate, like ramps, wedges, or arbitrary tile outlines (see
+ * {@link ForgeLevel}). Points outside the convex hull of what you pass are
+ * dropped automatically; a concave shape needs more than one collider.
+ * @param {Rigidbody} rigidbody - The rigidbody to attach the collider to
+ * @param {Array<{x:number,y:number}>} points - Local-space points, in
+ *   physics units, in any order
+ * @param {number} density - The density of the collider
+ * @param {number} friction - The friction of the collider
+ * @param {number} restitution - The restitution of the collider
+ * @param {boolean} [isSensor=false] - Whether the collider is a sensor
+ * @param {GameObject} [parentObject=null] - The parent object of the collider
+ * @param {Object} [filter=null] - Collision filter spec, see {@link Collider#setFilter}
+ */
+class PolygonCollider extends Collider {
+  constructor(
+    rigidbody,
+    points,
+    density,
+    friction,
+    restitution,
+    isSensor = false,
+    parentObject = null,
+    filter = null
+  ) {
+    super(rigidbody, isSensor, parentObject);
+    this.collider = rigidbody.createFixture(new PolygonShape(points), {
+      density: density,
+      friction: friction,
+      restitution: restitution,
+      isSensor: isSensor,
+    });
+    this.points = points;
+    this.rigidbody.setCollider(this);
+    this.name = "PolygonCollider" + this.id;
+    this._applyFilterSpec(filter);
+  }
+
+  /**
+   * @method getPoints
+   * @description Returns the local-space points this collider was built from
+   * @returns {Array<{x:number,y:number}>}
+   */
+  getPoints() {
+    return this.points;
+  }
+}
+
+export default PolygonCollider;