emeraldengine 2.2.0 → 3.0.0

package/src/components/CircleCollider.js

@@ -22,7 +22,8 @@ class CircleCollider extends Collider {
     friction,
     restitution,
     isSensor = false,
-    parentObject = null
+    parentObject = null,
+    filter = null
   ) {
     super(rigidbody, isSensor, parentObject);
     this.collider = rigidbody
@@ -36,7 +37,21 @@ class CircleCollider extends Collider {
     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 +70,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,28 @@ 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);
+    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);
+  }
 }
 
-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,150 @@ 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.
+   * @param {Transform} transform - The source transform
+   */
+  syncDebugShape(transform) {
+    if (!this._debugShape) return;
+    const t = this._debugShape.gameObject.transform;
+    t.position.x = transform.position.x;
+    t.position.y = transform.position.y;
+    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 planck 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/RigidBody.js

@@ -37,6 +37,8 @@ class RigidBody {
     this.collider = null;
     this.id = IDManager.generateUniqueID();
     this.name = "RigidBody" + this.id;
+
+    this.body.setUserData(this);
   }
 
   /**
@@ -53,6 +55,42 @@ class RigidBody {
     );
   }
 
+  /**
+   * @method getWorldX
+   * @description The single source of truth for body(physics) -> world(pixel)
+   * conversion on X: undo the scale and the spawn offset.
+   * @returns {number} - The live world-space x of the body
+   * @private
+   */
+  getWorldX() {
+    return this.body.getPosition().x * this.physics.scale - this.offset.x;
+  }
+
+  /**
+   * @method getWorldY
+   * @description World-space y counterpart of getWorldX.
+   * @returns {number} - The live world-space y of the body
+   * @private
+   */
+  getWorldY() {
+    return this.body.getPosition().y * this.physics.scale - this.offset.y;
+  }
+
+  /**
+   * @method syncTransform
+   * @description Writes the body's live world position and angle into a
+   * Transform. This is the one place body state is copied onto a renderable, so
+   * position and rotation stay in lock-step. Static/kinematic bodies are not
+   * driven by the simulation, so only dynamic bodies write back.
+   * @param {Transform} transform - The transform to update in place
+   */
+  syncTransform(transform) {
+    if (this.type !== "dynamic") return;
+    transform.position.x = this.getWorldX();
+    transform.position.y = this.getWorldY();
+    transform.rotation = this.body.getAngle();
+  }
+
   /**
    * @method getOffset
    * @description Returns the offset of the rigidbody
@@ -82,12 +120,95 @@ class RigidBody {
     this.body.setAngle(rotation);
   }
 
+  /**
+   * @method setLinearVelocity
+   * @description Sets the body's linear velocity in world (pixel) units per
+   * second. Converts to physics units internally.
+   * @param {number} vx - Horizontal velocity (world units/sec)
+   * @param {number} vy - Vertical velocity (world units/sec)
+   */
+  setLinearVelocity(vx, vy) {
+    this.body.setLinearVelocity(
+      new planck.Vec2(vx / this.physics.scale, vy / this.physics.scale)
+    );
+  }
+
+  /**
+   * @method getLinearVelocity
+   * @description Returns the body's linear velocity in world (pixel) units/sec.
+   * @returns {{x:number, y:number}}
+   */
+  getLinearVelocity() {
+    const v = this.body.getLinearVelocity();
+    return { x: v.x * this.physics.scale, y: v.y * this.physics.scale };
+  }
+
+  /**
+   * @method applyImpulse
+   * @description Applies a linear impulse (world units) at the body's center.
+   * @param {number} ix
+   * @param {number} iy
+   */
+  applyImpulse(ix, iy) {
+    this.body.applyLinearImpulse(
+      new planck.Vec2(ix / this.physics.scale, iy / this.physics.scale),
+      this.body.getWorldCenter(),
+      true
+    );
+  }
+
+  /**
+   * @method setAwake
+   * @description Wakes or sleeps the body.
+   * @param {boolean} awake
+   */
+  setAwake(awake) {
+    this.body.setAwake(awake);
+  }
+
+  /**
+   * @method setContinuous
+   * @description Enables continuous collision detection (CCD) for this body by
+   * marking it a "bullet". Fast-moving bodies (e.g. a dash, a projectile, a
+   * player falling at high speed) otherwise sweep so far in a single fixed step
+   * that they tunnel straight through thin static geometry; with CCD on, planck
+   * solves the swept path against static bodies so the body stops at the wall
+   * instead of teleporting past it. Costs more per step, so reserve it for the
+   * handful of bodies that actually move fast.
+   * @param {boolean} [enabled=true]
+   * @returns {RigidBody} - this
+   */
+  setContinuous(enabled = true) {
+    this.body.setBullet(!!enabled);
+    return this;
+  }
+
+  /**
+   * @method isContinuous
+   * @description Whether CCD (bullet mode) is enabled for this body.
+   * @returns {boolean}
+   */
+  isContinuous() {
+    return this.body.isBullet();
+  }
+
   /**
    * @method getPosition
-   * @description Returns the position of the rigidbody
-   * @returns {Vector2} - The position of the rigidbody
+   * @description Returns the live world-space position of the body (kept in sync
+   * with the simulation), not the spawn position. Use getInitialPosition() for
+   * the position the body was created at.
+   * @returns {Vector2} - The current world-space position of the rigidbody
    */
   getPosition() {
+    return new Vector2(this.getWorldX(), this.getWorldY());
+  }
+
+  /**
+   * @method getInitialPosition
+   * @description Returns the world-space position the body was created at.
+   * @returns {Vector2} - The spawn position of the rigidbody
+   */
+  getInitialPosition() {
     return this.position;
   }