emeraldengine 3.0.0 → 3.1.0

package/dist/types/src/physics/TimeOfImpact.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @function timeOfImpact
+ * @description Finds the first fraction of a step at which two moving shapes
+ * touch, by conservative advancement: measure the gap, work out the fastest the
+ * shapes could possibly close it, and skip ahead by exactly that much time,
+ * never further. Repeating this converges on the impact without ever stepping
+ * past it, which is what stops a fast body from tunnelling through a wall.
+ *
+ * @param {Object} input - `{ proxyA, proxyB, sweepA, sweepB, tMax }`
+ * @returns {{state: string, t: number}} - The outcome and the impact fraction
+ */
+export function timeOfImpact(input: any): {
+    state: string;
+    t: number;
+};
+export type TOIState = TOIState;
+export namespace TOIState {
+    let SEPARATED: string;
+    let TOUCHING: string;
+    let OVERLAPPED: string;
+    let FAILED: string;
+}

package/dist/types/src/physics/World.d.ts

@@ -0,0 +1,274 @@
+export default World;
+/**
+ * @class World
+ * @description The physics world: it owns the bodies, finds which ones touch,
+ * and advances them all by one time step. This is Emerald's own rigid-body
+ * engine: broadphase, narrowphase, an impulse solver and continuous collision
+ * detection, with no external physics dependency.
+ *
+ * Games normally reach it through {@link Physics}, which adds the pixel/meter
+ * conversion, a fixed-timestep accumulator and collision routing to
+ * {@link Behaviour} components.
+ *
+ * @param {Object} [def] - `{ gravity, allowSleep, warmStarting,
+ *   continuousPhysics, velocityThreshold, velocityIterations,
+ *   positionIterations }`
+ */
+declare class World {
+    constructor(def?: {});
+    gravity: Vec2;
+    broadPhase: BroadPhase;
+    contactManager: ContactManager;
+    /** Head of the body list; walk it with {@link Body#getNext}. @private */
+    private bodyList;
+    bodyCount: number;
+    /** Head of the joint list. @private */
+    private jointList;
+    jointCount: number;
+    allowSleep: boolean;
+    warmStarting: boolean;
+    continuousPhysics: boolean;
+    autoClearForces: boolean;
+    velocityThreshold: any;
+    velocityIterations: any;
+    positionIterations: any;
+    /** Optional `(fixtureA, fixtureB) => boolean` veto on new contacts. */
+    contactFilter: any;
+    /** @private */
+    private newContacts;
+    /** @private */
+    private locked;
+    /** @private */
+    private island;
+    /** @private */
+    private listeners;
+    /** @private */
+    private _toiProxyA;
+    /** @private */
+    private _toiProxyB;
+    /** What the last time-of-impact search hit. @private */
+    private _toiHitBody;
+    /**
+     * @method on
+     * @description Subscribes to a world event. Supported events:
+     * `begin-contact`, `end-contact`, `pre-solve`, `post-solve`, `remove-body`
+     * and `remove-fixture`.
+     * @param {string} name - Event name
+     * @param {Function} listener - Called with the contact (or body/fixture)
+     * @returns {World} - this
+     */
+    on(name: string, listener: Function): World;
+    /**
+     * @method off
+     * @description Unsubscribes a listener.
+     * @param {string} name
+     * @param {Function} listener
+     * @returns {World} - this
+     */
+    off(name: string, listener: Function): World;
+    /**
+     * @method dispatch
+     * @description Fires a world event. Listener errors are contained so one bad
+     * callback can't halt the simulation mid-step.
+     * @param {string} name
+     * @param {...*} args
+     */
+    dispatch(name: string, ...args: any[]): void;
+    /**
+     * @method createBody
+     * @description Creates a body in this world.
+     * @param {Object} [def] - See {@link Body}
+     * @returns {Body}
+     */
+    createBody(def?: any): Body;
+    /**
+     * @method destroyBody
+     * @description Removes a body, its fixtures and all its contacts.
+     * @param {Body} body
+     */
+    destroyBody(body: Body): void;
+    /**
+     * @method getBodyList
+     * @description Returns the first body; walk the rest with
+     * {@link Body#getNext}.
+     * @returns {Body|null}
+     */
+    getBodyList(): Body | null;
+    /**
+     * @method getBodyCount
+     * @description Number of bodies in the world.
+     * @returns {number}
+     */
+    getBodyCount(): number;
+    /**
+     * @method createJoint
+     * @description Creates a constraint between two bodies, a
+     * {@link DistanceJoint} or a {@link RevoluteJoint}, chosen by `def.type`
+     * (see {@link JointType}). Wakes both bodies, since a joint pulling on a
+     * sleeping body needs it simulating again immediately.
+     * @param {Object} def - `{ type, bodyA, bodyB, ... }`, forwarded to the
+     *   chosen joint's constructor
+     * @returns {Joint}
+     */
+    createJoint(def: any): Joint;
+    /**
+     * @method destroyJoint
+     * @description Removes a joint. Safe to call as part of destroying one of
+     * its bodies (see {@link World#destroyBody}).
+     * @param {Joint} joint
+     */
+    destroyJoint(joint: Joint): void;
+    /**
+     * @method getJointList
+     * @description Returns the first joint; walk the rest with `joint.next`.
+     * @returns {Joint|null}
+     */
+    getJointList(): Joint | null;
+    /**
+     * @method getJointCount
+     * @returns {number}
+     */
+    getJointCount(): number;
+    /**
+     * @method getContactList
+     * @description Returns every live contact (touching or merely close enough
+     * for their bounding boxes to overlap).
+     * @returns {Array<Contact>}
+     */
+    getContactList(): Array<Contact>;
+    /**
+     * @method getContactCount
+     * @description Number of live contacts.
+     * @returns {number}
+     */
+    getContactCount(): number;
+    /**
+     * @method setGravity
+     * @description Sets world gravity in physics units per second squared.
+     * @param {Object} gravity - `{ x, y }`
+     */
+    setGravity(gravity: any): void;
+    /**
+     * @method getGravity
+     * @description Returns world gravity.
+     * @returns {Vec2}
+     */
+    getGravity(): Vec2;
+    /**
+     * @method isLocked
+     * @description True while a step is in progress, when the body/fixture graph
+     * must not be modified.
+     * @returns {boolean}
+     */
+    isLocked(): boolean;
+    /**
+     * @method setAllowSleeping
+     * @description Enables or disables sleeping world-wide.
+     * @param {boolean} flag
+     */
+    setAllowSleeping(flag: boolean): void;
+    /**
+     * @method step
+     * @description Advances the simulation by `dt` seconds: refresh contacts,
+     * solve the islands, then sweep any continuous (bullet) bodies.
+     * @param {number} dt - Time step in seconds
+     * @param {number} [velocityIterations] - Solver velocity iterations
+     * @param {number} [positionIterations] - Solver position iterations
+     */
+    step(dt: number, velocityIterations?: number, positionIterations?: number): void;
+    /**
+     * @method solve
+     * @description Groups the awake bodies into islands of things that touch and
+     * solves each island on its own.
+     * @param {Object} step
+     * @private
+     */
+    private solve;
+    /**
+     * @method solveContinuous
+     * @description Sweeps every bullet body against the static and kinematic
+     * geometry it passed through this step, and rewinds it to the first impact.
+     * Without this, a body moving further than its own size in one step would
+     * simply appear on the far side of a thin wall.
+     * @private
+     */
+    private solveContinuous;
+    /**
+     * @method _absorbImpactVelocity
+     * @description Takes the excess approach speed out of a body that a rewind
+     * stopped short of a *moving* obstacle, leaving it travelling with whatever
+     * it landed on.
+     *
+     * The rewind puts the body where the two first touched, but the obstacle
+     * carries on to the end of the step, so the body is left hovering by up to
+     * one step of the obstacle's travel, too far apart for the discrete solver
+     * to see a contact next step. Keeping the body's original velocity as well
+     * means it arrives even faster the following step, is rewound again, and
+     * never lands: a rider on a descending platform would fall for ever without
+     * ever standing on it. Dropping the approach speed to the obstacle's own
+     * closes that gap within a step or two, which is where the discrete solver
+     * takes over and the two stay in contact.
+     *
+     * Static obstacles are left alone: they do not run away from the body, so
+     * the overlap the rewind aims for survives into the next step and the
+     * discrete solver already handles them.
+     *
+     * @param {Body} body - The body that was rewound
+     * @param {number} dx - How far it swept this step, before the rewind
+     * @param {number} dy
+     * @private
+     */
+    private _absorbImpactVelocity;
+    /**
+     * @method _findTimeOfImpact
+     * @description Earliest fraction of this step at which `body` first touches
+     * non-dynamic geometry, or null when it hits nothing. The body that was hit
+     * is left in `_toiHitBody`.
+     * @param {Body} body
+     * @returns {number|null}
+     * @private
+     */
+    private _findTimeOfImpact;
+    /**
+     * @method clearForces
+     * @description Zeroes the accumulated forces and torques on every body.
+     * Called automatically at the end of each step.
+     */
+    clearForces(): void;
+    /**
+     * @method rayCast
+     * @description Casts a ray from `p1` to `p2`, calling
+     * `callback(fixture, point, normal, fraction)` for every fixture hit.
+     *
+     * The callback controls what happens next, exactly like a filter: return the
+     * `fraction` to clip the ray there and keep looking for closer hits (the
+     * usual "closest hit" behaviour), `0` to stop immediately, `1` to keep the
+     * full ray and collect every hit, or `-1` to ignore this fixture entirely.
+     *
+     * @param {Object} p1 - Ray start `{ x, y }` in physics units
+     * @param {Object} p2 - Ray end `{ x, y }` in physics units
+     * @param {Function} callback
+     */
+    rayCast(p1: any, p2: any, callback: Function): void;
+    /**
+     * @method queryAABB
+     * @description Calls `callback(fixture)` for every fixture whose bounding box
+     * overlaps `aabb`. Returning false from the callback ends the query.
+     * @param {AABB} aabb
+     * @param {Function} callback
+     */
+    queryAABB(aabb: AABB, callback: Function): void;
+    /**
+     * @method queryPoint
+     * @description Calls `callback(fixture)` for every fixture containing a
+     * world-space point.
+     * @param {Object} point - `{ x, y }` in physics units
+     * @param {Function} callback
+     */
+    queryPoint(point: any, callback: Function): void;
+}
+import { Vec2 } from "./Math2D.js";
+import { BroadPhase } from "./BroadPhase.js";
+import { ContactManager } from "./Contact.js";
+import { Body } from "./Body.js";
+import AABB from "./AABB.js";

package/dist/types/src/physics/index.d.ts

@@ -0,0 +1,34 @@
+import World from "./World.js";
+import { Body } from "./Body.js";
+import { BodyType } from "./Body.js";
+import { Fixture } from "./Fixture.js";
+import { Contact } from "./Contact.js";
+import { ContactManager } from "./Contact.js";
+import { shouldCollide } from "./Contact.js";
+import { Shape } from "./Shapes.js";
+import { ShapeType } from "./Shapes.js";
+import { CircleShape } from "./Shapes.js";
+import { PolygonShape } from "./Shapes.js";
+import { Box } from "./Shapes.js";
+import { Circle } from "./Shapes.js";
+import { Vec2 } from "./Math2D.js";
+import { Rot } from "./Math2D.js";
+import { Transform2 } from "./Math2D.js";
+import { Sweep } from "./Math2D.js";
+import AABB from "./AABB.js";
+import Settings from "./Settings.js";
+import { Manifold } from "./Collision.js";
+import { ManifoldType } from "./Collision.js";
+import { WorldManifold } from "./Collision.js";
+import { DistanceProxy } from "./Distance.js";
+import { distance } from "./Distance.js";
+import { testOverlap } from "./Distance.js";
+import { timeOfImpact } from "./TimeOfImpact.js";
+import { TOIState } from "./TimeOfImpact.js";
+import { BroadPhase } from "./BroadPhase.js";
+import { DynamicTree } from "./BroadPhase.js";
+import { Joint } from "./Joint.js";
+import { JointType } from "./Joint.js";
+import DistanceJoint from "./DistanceJoint.js";
+import RevoluteJoint from "./RevoluteJoint.js";
+export { World, Body, BodyType, Fixture, Contact, ContactManager, shouldCollide, Shape, ShapeType, CircleShape, PolygonShape, Box, Circle, Vec2, Rot, Transform2, Sweep, AABB, Settings, Manifold, ManifoldType, WorldManifold, DistanceProxy, distance, testOverlap, timeOfImpact, TOIState, BroadPhase, DynamicTree, Joint, JointType, DistanceJoint, RevoluteJoint };

package/index.js

@@ -36,6 +36,7 @@ import ParticleEmitter from "./src/ParticleEmitter.js";
 import CollisionLayers from "./src/CollisionLayers.js";
 import TiledMap from "./src/importers/TiledMap.js";
 import Aseprite from "./src/importers/Aseprite.js";
+import ForgeLevel from "./src/importers/ForgeLevel.js";
 import RenderTarget from "./src/RenderTarget.js";
 import RenderStats from "./src/managers/RenderStats.js";
 import PostProcessor, { PostEffect } from "./src/PostProcessor.js";
@@ -43,6 +44,7 @@ import PostEffects, { BloomEffect } from "./src/PostEffects.js";
 import Material from "./src/Material.js";
 import UI from "./src/UI.js";
 import InputManager from "./src/managers/InputManager.js";
+import Gamepad from "./src/managers/Gamepad.js";
 import Particle from "./src/particlesystem/Particle.js";
 import Particles from "./src/particlesystem/Particles.js";
 import ParticleSettings from "./src/particlesystem/ParticleSettings.js";
@@ -59,6 +61,7 @@ import BoxCollider from "./src/components/BoxCollider.js";
 import BoxColliderDebug from "./src/components/BoxColliderDebug.js";
 import CircleCollider from "./src/components/CircleCollider.js";
 import CircleColliderDebug from "./src/components/CircleColliderDebug.js";
+import PolygonCollider from "./src/components/PolygonCollider.js";
 import Collider from "./src/components/Collider.js";
 import GameObject from "./src/components/GameObject.js";
 import RigidBody from "./src/components/RigidBody.js";
@@ -107,6 +110,7 @@ export {
   CollisionLayers,
   TiledMap,
   Aseprite,
+  ForgeLevel,
   RenderTarget,
   RenderStats,
   PostProcessor,
@@ -116,6 +120,7 @@ export {
   Material,
   UI,
   InputManager,
+  Gamepad,
   Particle,
   Particles,
   ParticleSettings,
@@ -132,6 +137,7 @@ export {
   BoxColliderDebug,
   CircleCollider,
   CircleColliderDebug,
+  PolygonCollider,
   Collider,
   GameObject,
   RigidBody,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emeraldengine",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "2D graphics library for Web",
   "type": "module",
   "main": "index.js",
@@ -37,8 +37,7 @@
     "physics"
   ],
   "dependencies": {
-    "gl-matrix": "^3.4.3",
-    "planck": "^1.4.2"
+    "gl-matrix": "^3.4.3"
   },
   "peerDependencies": {
     "colyseus.js": "^0.16.16"

package/src/Animator.js

@@ -5,7 +5,7 @@ import Drawable from "./Drawable.js";
  * @class Animator
  * @description A component that manages named animation clips for a Texture (or
  * any Drawable) on the same GameObject. Register clips once, then switch between
- * them by name — handy for character states like idle/run/jump.
+ * them by name, handy for character states like idle/run/jump.
  *
  * @example
  * const anim = new Animator();

package/src/CollisionLayers.js

@@ -1,13 +1,13 @@
 /**
  * @class CollisionLayers
  * @description A small registry that maps human-readable layer names to the
- * category bits planck uses for collision filtering, so games can say
+ * category bits the physics engine uses for collision filtering, so games can
  * "players collide with ground and enemies, but not with each other" without
  * juggling raw bitmasks.
  *
  * Two fixtures collide only if each one's category is in the other's mask, so
  * filtering is symmetric by construction. Up to 16 distinct layers are
- * supported (planck filter bits are 16-bit).
+ * supported (filter bits are 16-bit).
  *
  * @example
  * CollisionLayers.define("ground", "player", "enemy", "pickup");
@@ -44,7 +44,7 @@ class CollisionLayers {
     if (CollisionLayers._bits.has(name)) return CollisionLayers._bits.get(name);
     if (CollisionLayers._next > 15) {
       throw new Error(
-        "[CollisionLayers] Exceeded 16 collision layers (planck filter limit)."
+        "[CollisionLayers] Exceeded 16 collision layers (filter bit limit)."
       );
     }
     const bit = 1 << CollisionLayers._next++;

package/src/Color.js

@@ -13,6 +13,14 @@ class Color {
     this.b = b;
     this.a = a;
   }
+
+  static fromHex(hex) {
+    const value = hex.startsWith("#") ? hex.slice(1) : hex;
+    const r = parseInt(value.slice(0, 2), 16);
+    const g = parseInt(value.slice(2, 4), 16);
+    const b = parseInt(value.slice(4, 6), 16);
+    return new Color(r, g, b, 255);
+  }
 }
 
 export default Color;

package/src/Drawable.js

@@ -370,7 +370,7 @@ class Drawable {
    * @description Frees this drawable's GPU resources: its vertex/texcoord
    * buffers and its reference on the shared texture (the GL texture itself is
    * deleted when the last drawable using it is disposed). Call it when the
-   * owning object is permanently removed — GameObject.destroy() and
+   * owning object is permanently removed. GameObject.destroy() and
    * Scene.remove(obj, { dispose: true }) do it for you. Safe to call twice.
    */
   dispose() {

package/src/Emerald.js

@@ -215,7 +215,7 @@ class Emerald {
       e.preventDefault();
       this._contextLost = true;
       console.warn(
-        "[Emerald] > WebGL context lost — rendering paused until restore."
+        "[Emerald] > WebGL context lost, rendering paused until restore."
       );
       for (const h of this._contextLostHandlers) h();
     };

package/src/EmeraldDB.js

@@ -1,6 +1,6 @@
 /**
  * @class EmeraldDB
- * @description Async game-save storage on IndexedDB — the big-world companion
+ * @description Async game-save storage on IndexedDB, the big-world companion
  * to `Storage` (localStorage). Same versioned-envelope semantics (`{v,t,data}`
  * with a `.bak` backup and forward migration), but with no ~5MB quota and no
  * JSON round-trip: values are structured-cloned, so large nested world state
@@ -115,7 +115,7 @@ class EmeraldDB {
 
   /**
    * @method set
-   * @description Stores a value under a key (structured clone — objects, Maps,
+   * @description Stores a value under a key (structured clone: objects, Maps,
    * Sets, typed arrays all survive).
    * @param {string} key
    * @param {*} value

package/src/InstancedTexture.js

@@ -93,6 +93,8 @@ class InstancedTexture extends Drawable {
     this.static = false;
     /** @private */
     this._matricesDirty = true;
+    /** The animation every instance starts with; set by playAnimation/playAnimationOnce. @private */
+    this._defaultAnimation = null;
   }
 
   /**
@@ -127,6 +129,11 @@ class InstancedTexture extends Drawable {
     if (this.instances.length < this.instanceCount) {
       this.instances.push(instance);
       instance.setParent(this);
+      if (this._defaultAnimation) {
+        const { frames, speed, once } = this._defaultAnimation;
+        if (once) instance.playAnimationOnce(frames, speed);
+        else instance.playAnimation(frames, speed);
+      }
       this._matricesDirty = true;
     } else {
       console.warn("Max instance count reached.");
@@ -962,31 +969,72 @@ class InstancedTexture extends Drawable {
 
   /**
    * @method playAnimation
-   * @description Plays an animation
+   * @description Plays the same looping animation, in lockstep, on every
+   * instance: the current ones immediately, and any added later via
+   * {@link InstancedTexture#addInstance}. For giving individual instances
+   * their own independent animation instead, use
+   * {@link InstancedTexture#animateInstance}.
    * @param {Array} frames - The frames to play
-   * @param {number} speed - The speed of the animation
+   * @param {number} [speed=1000] - Milliseconds per frame
    */
   playAnimation(frames, speed = 1000) {
-    console.warn("playAnimation is not implemented for InstancedTexture");
+    if (!frames || frames.length === 0) {
+      console.error(
+        "[InstancedTexture] playAnimation: frames cannot be empty!"
+      );
+      return;
+    }
+    this._defaultAnimation = { frames, speed, once: false };
+    for (const instance of this.instances)
+      instance.playAnimation(frames, speed);
   }
 
   /**
    * @method playAnimationOnce
-   * @description Plays an animation once
+   * @description Plays the same animation once, in lockstep, on every
+   * instance, then holds each on its last frame: the current instances
+   * immediately, and any added later via {@link InstancedTexture#addInstance}.
    * @param {Array} frames - The frames to play
-   * @param {number} speed - The speed of the animation
+   * @param {number} [speed=1000] - Milliseconds per frame
    */
   playAnimationOnce(frames, speed = 1000) {
-    console.warn("playAnimationOnce is not implemented for InstancedTexture");
+    if (!frames || frames.length === 0) {
+      console.error(
+        "[InstancedTexture] playAnimationOnce: frames cannot be empty!"
+      );
+      return;
+    }
+    this._defaultAnimation = { frames, speed, once: true };
+    for (const instance of this.instances) {
+      instance.playAnimationOnce(frames, speed);
+    }
+  }
+
+  /**
+   * @method stopAnimation
+   * @description Stops the shared animation started by playAnimation/
+   * playAnimationOnce on every current instance, and clears it so instances
+   * added afterwards no longer start playing it either. Instances animated
+   * individually via {@link InstancedTexture#animateInstance} are unaffected
+   * unless you stop them the same way, through {@link InstancedTexture#stopInstanceAnimation}.
+   * @param {boolean} [revertToOriginal=false] - Whether to reset each
+   *   instance back to the frame it had before playAnimation was called
+   */
+  stopAnimation(revertToOriginal = false) {
+    this._defaultAnimation = null;
+    for (const instance of this.instances) {
+      instance.stopAnimation(revertToOriginal);
+    }
   }
 
   /**
    * @method getAnimation
-   * @description Gets the animation
-   * @returns {Array} - The animation
+   * @description Returns the frames of the shared animation set by
+   * playAnimation/playAnimationOnce, or an empty array if none is playing.
+   * @returns {Array} - The animation frames
    */
   getAnimation() {
-    console.warn("getAnimation is not implemented for InstancedTexture");
+    return this._defaultAnimation ? this._defaultAnimation.frames : [];
   }
 }
 

package/src/Material.js

@@ -31,7 +31,7 @@ const MATERIAL_VERTEX_HEADER = `
  * @description A custom shader for a Drawable. By default it reuses the engine's
  * standard vertex shader (so transforms, the camera, and instancing keep
  * working) and only overrides the fragment program. Pass `options.vertex` to
- * also supply a custom VERTEX program — the escape hatch for effects the fixed
+ * also supply a custom VERTEX program: the escape hatch for effects the fixed
  * pipeline can't express (perspective tilt, vertex waves, billboarding, ...).
  *
  * The fragment shader always has: `vTexCoord`, `vFragPos`, `vInstanceColor`,
@@ -40,7 +40,7 @@ const MATERIAL_VERTEX_HEADER = `
  * `uTime`, and must write `vTexCoord` + `gl_Position`.
  *
  * Declare extra uniforms and set them via `set(name, value)`. A uniform value
- * may be a number, an array (vec2/3/4), or a FUNCTION — the function is called
+ * may be a number, an array (vec2/3/4), or a FUNCTION: the function is called
  * each draw and receives the Drawable currently rendering, so a single shared
  * Material can read PER-OBJECT state (e.g. each card's own tilt angle).
  *

package/src/MathUtils.js

@@ -2,7 +2,8 @@
  * @class MathUtils
  * @description Common math helpers for games: interpolation, clamping, angle
  * conversion, random ranges, and lightweight 2D vector operations that work on
- * any `{ x, y }` object (including planck Vec2 and Emerald Vector2).
+ * any `{ x, y }` object (including the physics engine's Vec2 and Emerald
+ * Vector2).
  */
 class MathUtils {
   /**

package/src/ParticleEmitter.js

@@ -10,7 +10,7 @@ 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 /
+ * 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).