emeraldengine 3.0.0 → 3.1.0

package/src/components/CircleColliderDebug.js

@@ -14,11 +14,12 @@ class CircleColliderDebug {
     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(
-        this.rigidbody.getBody().getPosition().x * this.scale,
-        this.rigidbody.getBody().getPosition().y * this.scale,
+        body.getPosition().x * this.scale,
+        body.getPosition().y * this.scale,
         100
       ),
       this.rigidbody.getAngle(),

package/src/components/Collider.js

@@ -23,19 +23,29 @@ class 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;
-    t.position.x = transform.position.x;
-    t.position.y = transform.position.y;
+    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 setFilter
-   * @description Sets the raw planck collision filter on this collider's
+   * @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.

package/src/components/GameObject.js

@@ -45,7 +45,7 @@ class GameObject {
 
   /**
    * @method setScreenSpace
-   * @description When true, the object ignores the camera (fixed on screen) —
+   * @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
@@ -223,7 +223,7 @@ class GameObject {
    * @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.
+   * be re-added: plain Scene.remove() keeps GPU resources alive for re-use.
    * Safe to call twice.
    */
   destroy() {

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;

package/src/components/RigidBody.js

@@ -1,10 +1,16 @@
-import * as planck from "planck";
+import { Vec2 } from "../physics/index.js";
 import IDManager from "../managers/IDManager.js";
 import { Vector2 } from "../Physics.js";
 import Collider from "./Collider.js";
 
 /**
  * @class RigidBody
+ * @description The game-facing physics body: everything you can do to a body
+ * (move it, push it, spin it, sleep it, query its mass) is a method on this
+ * class directly, in world/pixel units. There is no separate lower-level
+ * body object you need to fetch first. `getBody()` still returns the raw,
+ * physics-unit {@link Body} underneath for the rare case you need it (writing
+ * a custom joint, say), but nothing in ordinary use requires it.
  * @param {Physics} physics - The physics engine
  * @param {string | "static" | "dynamic" | "kinematic"} type - The type of rigidbody
  * @param {Vector2} position - The position of the rigidbody
@@ -26,7 +32,7 @@ class RigidBody {
     this.type = type;
     this.body = physics.world.createBody({
       type: type,
-      position: new planck.Vec2(
+      position: new Vec2(
         (position.x + offset.x) / physics.scale,
         (position.y + offset.y) / physics.scale
       ),
@@ -37,6 +43,8 @@ class RigidBody {
     this.collider = null;
     this.id = IDManager.generateUniqueID();
     this.name = "RigidBody" + this.id;
+    /** Freely usable by your own code; see {@link RigidBody#getUserData}. */
+    this.userData = null;
 
     this.body.setUserData(this);
   }
@@ -48,13 +56,41 @@ class RigidBody {
    */
   updatePosition(position) {
     this.body.setPosition(
-      new planck.Vec2(
+      new Vec2(
         (position.x + this.offset.x) / this.physics.scale,
         (position.y + this.offset.y) / this.physics.scale
       )
     );
   }
 
+  /**
+   * @method setPosition
+   * @description Alias of {@link RigidBody#updatePosition}, named to match
+   * `setRotation`/`setTransform`.
+   * @param {Vector2} position - The new position, in world (pixel) units
+   */
+  setPosition(position) {
+    this.updatePosition(position);
+  }
+
+  /**
+   * @method setTransform
+   * @description Teleports the body to a new position and angle in one move
+   * (no velocity implied), and wakes it so contacts at the new spot are seen
+   * on the very next step.
+   * @param {Vector2} position - World (pixel) units
+   * @param {number} angle - Radians
+   */
+  setTransform(position, angle) {
+    this.body.setTransform(
+      new Vec2(
+        (position.x + this.offset.x) / this.physics.scale,
+        (position.y + this.offset.y) / this.physics.scale
+      ),
+      angle
+    );
+  }
+
   /**
    * @method getWorldX
    * @description The single source of truth for body(physics) -> world(pixel)
@@ -111,6 +147,29 @@ class RigidBody {
     }
   }
 
+  /**
+   * @method createFixture
+   * @description Attaches a shape directly, bypassing the Collider component
+   * classes ({@link BoxCollider}, {@link CircleCollider}, {@link PolygonCollider})
+   * that normally build one for you. `shape` is a physics-unit shape (e.g. from
+   * `Box()`/`Circle()`/`new PolygonShape()`), not pixels.
+   * @param {Shape} shape
+   * @param {Object|number} [def] - `{ density, friction, restitution, isSensor, ... }`
+   * @returns {Fixture}
+   */
+  createFixture(shape, def = {}) {
+    return this.body.createFixture(shape, def);
+  }
+
+  /**
+   * @method destroyFixture
+   * @description Removes a fixture created with {@link RigidBody#createFixture}.
+   * @param {Fixture} fixture
+   */
+  destroyFixture(fixture) {
+    this.body.destroyFixture(fixture);
+  }
+
   /**
    * @method setRotation
    * @description Sets the rotation of the rigidbody
@@ -129,7 +188,7 @@ class RigidBody {
    */
   setLinearVelocity(vx, vy) {
     this.body.setLinearVelocity(
-      new planck.Vec2(vx / this.physics.scale, vy / this.physics.scale)
+      new Vec2(vx / this.physics.scale, vy / this.physics.scale)
     );
   }
 
@@ -143,20 +202,115 @@ class RigidBody {
     return { x: v.x * this.physics.scale, y: v.y * this.physics.scale };
   }
 
+  /**
+   * @method getLinearVelocityFromWorldPoint
+   * @description The velocity (world units/sec) of the material point of this
+   * body currently at `worldPoint`: linear velocity plus the contribution
+   * from spin. Useful for e.g. where a spinning platform's edge is moving.
+   * @param {Object} worldPoint - World (pixel) units
+   * @returns {Vector2}
+   */
+  getLinearVelocityFromWorldPoint(worldPoint) {
+    const scale = this.physics.scale;
+    const v = this.body.getLinearVelocityFromWorldPoint(
+      new Vec2(worldPoint.x / scale, worldPoint.y / scale)
+    );
+    return new Vector2(v.x * scale, v.y * scale);
+  }
+
+  /**
+   * @method setAngularVelocity
+   * @description Sets the body's spin, in radians per second.
+   * @param {number} omega
+   */
+  setAngularVelocity(omega) {
+    this.body.setAngularVelocity(omega);
+  }
+
+  /**
+   * @method getAngularVelocity
+   * @description Returns the body's spin, in radians per second.
+   * @returns {number}
+   */
+  getAngularVelocity() {
+    return this.body.getAngularVelocity();
+  }
+
   /**
    * @method applyImpulse
-   * @description Applies a linear impulse (world units) at the body's center.
+   * @description Applies an instantaneous change in momentum (world units).
+   * This is what a jump or a knockback should use, since (unlike a force) it
+   * takes effect immediately rather than accumulating over the step.
    * @param {number} ix
    * @param {number} iy
+   * @param {Object} [point] - World (pixel) point to apply it at; defaults to
+   *   the center of mass (no torque)
+   * @param {boolean} [wake=true]
    */
-  applyImpulse(ix, iy) {
+  applyImpulse(ix, iy, point = null, wake = true) {
+    const scale = this.physics.scale;
     this.body.applyLinearImpulse(
-      new planck.Vec2(ix / this.physics.scale, iy / this.physics.scale),
-      this.body.getWorldCenter(),
-      true
+      new Vec2(ix / scale, iy / scale),
+      point
+        ? new Vec2(point.x / scale, point.y / scale)
+        : this.body.getWorldCenter(),
+      wake
+    );
+  }
+
+  /**
+   * @method applyAngularImpulse
+   * @description Applies an instantaneous change in angular momentum.
+   * @param {number} impulse
+   * @param {boolean} [wake=true]
+   */
+  applyAngularImpulse(impulse, wake = true) {
+    this.body.applyAngularImpulse(impulse, wake);
+  }
+
+  /**
+   * @method applyForce
+   * @description Applies a force (world units) at a world point. Forces
+   * accumulate and are cleared at the end of every step, so this belongs in
+   * your update loop, unlike an impulse.
+   * @param {number} fx
+   * @param {number} fy
+   * @param {Object} [point] - World (pixel) point; defaults to the center of
+   *   mass (no torque)
+   * @param {boolean} [wake=true]
+   */
+  applyForce(fx, fy, point = null, wake = true) {
+    const scale = this.physics.scale;
+    this.body.applyForce(
+      new Vec2(fx / scale, fy / scale),
+      point ? new Vec2(point.x / scale, point.y / scale) : null,
+      wake
     );
   }
 
+  /**
+   * @method applyForceToCenter
+   * @description Applies a force (world units) at the center of mass: no
+   * torque, unlike {@link RigidBody#applyForce} with a point.
+   * @param {number} fx
+   * @param {number} fy
+   * @param {boolean} [wake=true]
+   */
+  applyForceToCenter(fx, fy, wake = true) {
+    const scale = this.physics.scale;
+    this.body.applyForceToCenter(new Vec2(fx / scale, fy / scale), wake);
+  }
+
+  /**
+   * @method applyTorque
+   * @description Applies a torque about the center of mass.
+   * @param {number} torque
+   * @param {boolean} [wake=true]
+   */
+  applyTorque(torque, wake = true) {
+    this.body.applyTorque(torque, wake);
+  }
+
   /**
    * @method setAwake
    * @description Wakes or sleeps the body.
@@ -166,13 +320,74 @@ class RigidBody {
     this.body.setAwake(awake);
   }
 
+  /**
+   * @method isAwake
+   * @description Whether the body is currently simulated.
+   * @returns {boolean}
+   */
+  isAwake() {
+    return this.body.isAwake();
+  }
+
+  /**
+   * @method setSleepingAllowed
+   * @description Allows or forbids this body from ever sleeping.
+   * @param {boolean} flag
+   */
+  setSleepingAllowed(flag) {
+    this.body.setSleepingAllowed(flag);
+  }
+
+  /**
+   * @method isSleepingAllowed
+   * @returns {boolean}
+   */
+  isSleepingAllowed() {
+    return this.body.isSleepingAllowed();
+  }
+
+  /**
+   * @method setActive
+   * @description Adds or removes the body from collision detection without
+   * destroying it.
+   * @param {boolean} flag
+   */
+  setActive(flag) {
+    this.body.setActive(flag);
+  }
+
+  /**
+   * @method isActive
+   * @returns {boolean}
+   */
+  isActive() {
+    return this.body.isActive();
+  }
+
+  /**
+   * @method setFixedRotation
+   * @description Locks or unlocks the body's rotation at runtime.
+   * @param {boolean} flag
+   */
+  setFixedRotation(flag) {
+    this.body.setFixedRotation(flag);
+  }
+
+  /**
+   * @method isFixedRotation
+   * @returns {boolean}
+   */
+  isFixedRotation() {
+    return this.body.isFixedRotation();
+  }
+
   /**
    * @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
+   * that they tunnel straight through thin static geometry; with CCD on, the
+   * engine sweeps the body against static geometry so it 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]
@@ -192,6 +407,202 @@ class RigidBody {
     return this.body.isBullet();
   }
 
+  /**
+   * @method setLinearDamping
+   * @description Sets the drag applied to linear motion each step.
+   * @param {number} damping
+   */
+  setLinearDamping(damping) {
+    this.body.setLinearDamping(damping);
+  }
+
+  /**
+   * @method getLinearDamping
+   * @returns {number}
+   */
+  getLinearDamping() {
+    return this.body.getLinearDamping();
+  }
+
+  /**
+   * @method setAngularDamping
+   * @description Sets the drag applied to rotation each step.
+   * @param {number} damping
+   */
+  setAngularDamping(damping) {
+    this.body.setAngularDamping(damping);
+  }
+
+  /**
+   * @method getAngularDamping
+   * @returns {number}
+   */
+  getAngularDamping() {
+    return this.body.getAngularDamping();
+  }
+
+  /**
+   * @method setGravityScale
+   * @description Scales how strongly gravity pulls on this body (0 disables
+   * it, 2 makes it twice as heavy-feeling).
+   * @param {number} scale
+   */
+  setGravityScale(scale) {
+    this.body.setGravityScale(scale);
+  }
+
+  /**
+   * @method getGravityScale
+   * @returns {number}
+   */
+  getGravityScale() {
+    return this.body.getGravityScale();
+  }
+
+  /**
+   * @method getMass
+   * @description Returns the body's mass, in physics units (derived from its
+   * fixtures' shapes and densities, unaffected by the pixel scale).
+   * @returns {number}
+   */
+  getMass() {
+    return this.body.getMass();
+  }
+
+  /**
+   * @method getInertia
+   * @description Returns the body's rotational inertia about its center of
+   * mass, in physics units.
+   * @returns {number}
+   */
+  getInertia() {
+    return this.body.getInertia();
+  }
+
+  /**
+   * @method resetMassData
+   * @description Re-derives mass/center/inertia from the body's current
+   * fixtures. Call this after changing a fixture's density at runtime.
+   */
+  resetMassData() {
+    this.body.resetMassData();
+  }
+
+  /**
+   * @method setMassData
+   * @description Overrides the computed mass properties directly.
+   * @param {Object} massData - `{ mass, center, I }`; `center` is a world
+   *   (pixel) offset from the body's origin
+   */
+  setMassData(massData) {
+    const scale = this.physics.scale;
+    const center = massData.center || { x: 0, y: 0 };
+    this.body.setMassData({
+      mass: massData.mass,
+      center: new Vec2(center.x / scale, center.y / scale),
+      I: massData.I,
+    });
+  }
+
+  /**
+   * @method getWorldPoint
+   * @description Converts a point local to this body into world (pixel) space.
+   * @param {Object} localPoint - World-unit offset from the body's origin
+   * @returns {Vector2}
+   */
+  getWorldPoint(localPoint) {
+    const scale = this.physics.scale;
+    const p = this.body.getWorldPoint(
+      new Vec2(localPoint.x / scale, localPoint.y / scale)
+    );
+    return new Vector2(p.x * scale, p.y * scale);
+  }
+
+  /**
+   * @method getLocalPoint
+   * @description Converts a world (pixel) point into this body's local frame.
+   * @param {Object} worldPoint - World (pixel) units
+   * @returns {Vector2}
+   */
+  getLocalPoint(worldPoint) {
+    const scale = this.physics.scale;
+    const p = this.body.getLocalPoint(
+      new Vec2(worldPoint.x / scale, worldPoint.y / scale)
+    );
+    return new Vector2(p.x * scale, p.y * scale);
+  }
+
+  /**
+   * @method getWorldVector
+   * @description Rotates a local direction (not a point, unaffected by the
+   * body's position) into world space.
+   * @param {Object} localVector
+   * @returns {Vector2}
+   */
+  getWorldVector(localVector) {
+    const scale = this.physics.scale;
+    const v = this.body.getWorldVector(
+      new Vec2(localVector.x / scale, localVector.y / scale)
+    );
+    return new Vector2(v.x * scale, v.y * scale);
+  }
+
+  /**
+   * @method getLocalVector
+   * @description Rotates a world direction into this body's local frame.
+   * @param {Object} worldVector
+   * @returns {Vector2}
+   */
+  getLocalVector(worldVector) {
+    const scale = this.physics.scale;
+    const v = this.body.getLocalVector(
+      new Vec2(worldVector.x / scale, worldVector.y / scale)
+    );
+    return new Vector2(v.x * scale, v.y * scale);
+  }
+
+  /**
+   * @method getContactList
+   * @description Returns the raw physics contacts this body currently takes
+   * part in. Each contact's `fixtureA`/`fixtureB` point at physics-unit
+   * fixtures/bodies, not RigidBody wrappers. Walk `fixture.body.getUserData()`
+   * to get back to the owning RigidBody.
+   * @returns {Array<Contact>}
+   */
+  getContactList() {
+    return this.body.getContactList();
+  }
+
+  /**
+   * @method getWorld
+   * @description Returns the raw physics {@link World} this body lives in.
+   * @returns {World}
+   */
+  getWorld() {
+    return this.body.getWorld();
+  }
+
+  /**
+   * @method getUserData
+   * @description Returns whatever you last passed to
+   * {@link RigidBody#setUserData}. This is separate from the underlying
+   * physics body's own userData slot, which the engine itself uses internally
+   * to route collisions back to this RigidBody, so setting it here can never
+   * break that.
+   * @returns {*}
+   */
+  getUserData() {
+    return this.userData;
+  }
+
+  /**
+   * @method setUserData
+   * @param {*} data
+   */
+  setUserData(data) {
+    this.userData = data;
+  }
+
   /**
    * @method getPosition
    * @description Returns the live world-space position of the body (kept in sync
@@ -232,8 +643,11 @@ class RigidBody {
 
   /**
    * @method getBody
-   * @description Returns the body of the rigidbody
-   * @returns {planck.Body} - The body of the rigidbody
+   * @description Returns the underlying, physics-unit {@link Body}. Nothing in
+   * ordinary use needs this: every common operation is a method on RigidBody
+   * itself, in world/pixel units, but it's here for advanced cases (writing a
+   * custom joint or solver hook) that need the raw physics object.
+   * @returns {Body} - The body of the rigidbody
    */
   getBody() {
     return this.body;
@@ -263,7 +677,7 @@ class RigidBody {
    */
   detachCollider(collider) {
     if (collider && collider.getCollider()) {
-      this.body.destroyFixture(collider.getCollider());
+      this.destroyFixture(collider.getCollider());
       this.collider = null;
     }
   }
@@ -285,6 +699,19 @@ class RigidBody {
   getType() {
     return this.type;
   }
+
+  /**
+   * @method setType
+   * @description Changes the body type at runtime (e.g. turning a kinematic
+   * moving platform into a dynamic one when it breaks apart). Resets
+   * velocities and re-derives mass; existing contacts are dropped so they
+   * rebuild against the new type.
+   * @param {string | "static" | "dynamic" | "kinematic"} type
+   */
+  setType(type) {
+    this.type = type;
+    this.body.setType(type);
+  }
 }
 
 export default RigidBody;

package/src/importers/Aseprite.js

@@ -3,7 +3,7 @@
  * @description Imports sprite-sheet metadata exported from Aseprite
  * (File ▸ Export Sprite Sheet, with "JSON Data" on) and turns its frame tags
  * into engine animation clips. Works with both the Hash and Array JSON layouts.
- * Pure parsing — pass it the already-parsed JSON object.
+ * Pure parsing: pass it the already-parsed JSON object.
  *
  * Assumes the sheet is a uniform grid in frame order (the common case), so the
  * frame indices line up with the engine's Texture/Animator frame numbering.
@@ -86,7 +86,7 @@ class Aseprite {
    * @method toClips
    * @description Builds clip descriptors from the sheet's frame tags. Each clip
    * is `{ name, frames, speed }` where `frames` are frame indices and `speed`
-   * is the average frame duration (ms) — the per-clip speed the Animator uses.
+   * is the average frame duration (ms), the per-clip speed the Animator uses.
    * If the sheet has no tags, a single "default" clip spanning all frames is
    * returned.
    * @param {Object} sheet - Parsed Aseprite JSON