emeraldengine 3.0.0 → 3.1.0

package/dist/types/src/components/RigidBody.d.ts

@@ -1,6 +1,12 @@
 export default RigidBody;
 /**
  * @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
@@ -19,12 +25,30 @@ declare class RigidBody {
     collider: Collider;
     id: string;
     name: string;
+    /** Freely usable by your own code; see {@link RigidBody#getUserData}. */
+    userData: any;
     /**
      * @method updatePosition
      * @description Updates the position of the rigidbody
      * @param {Vector2} position - The new position
      */
     updatePosition(position: Vector2): void;
+    /**
+     * @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: Vector2): void;
+    /**
+     * @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: Vector2, angle: number): void;
     /**
      * @method getWorldX
      * @description The single source of truth for body(physics) -> world(pixel)
@@ -61,6 +85,23 @@ declare class RigidBody {
      * @param {Collider} collider - The collider to set
      */
     setCollider(collider: Collider): void;
+    /**
+     * @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: Shape, def?: any | number): Fixture;
+    /**
+     * @method destroyFixture
+     * @description Removes a fixture created with {@link RigidBody#createFixture}.
+     * @param {Fixture} fixture
+     */
+    destroyFixture(fixture: Fixture): void;
     /**
      * @method setRotation
      * @description Sets the rotation of the rigidbody
@@ -84,26 +125,127 @@ declare class RigidBody {
         x: number;
         y: number;
     };
+    /**
+     * @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: any): Vector2;
+    /**
+     * @method setAngularVelocity
+     * @description Sets the body's spin, in radians per second.
+     * @param {number} omega
+     */
+    setAngularVelocity(omega: number): void;
+    /**
+     * @method getAngularVelocity
+     * @description Returns the body's spin, in radians per second.
+     * @returns {number}
+     */
+    getAngularVelocity(): number;
     /**
      * @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: number, iy: number, point?: any, wake?: boolean): void;
+    /**
+     * @method applyAngularImpulse
+     * @description Applies an instantaneous change in angular momentum.
+     * @param {number} impulse
+     * @param {boolean} [wake=true]
+     */
+    applyAngularImpulse(impulse: number, wake?: boolean): void;
+    /**
+     * @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: number, fy: number, point?: any, wake?: boolean): void;
+    /**
+     * @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]
      */
-    applyImpulse(ix: number, iy: number): void;
+    applyForceToCenter(fx: number, fy: number, wake?: boolean): void;
+    /**
+     * @method applyTorque
+     * @description Applies a torque about the center of mass.
+     * @param {number} torque
+     * @param {boolean} [wake=true]
+     */
+    applyTorque(torque: number, wake?: boolean): void;
     /**
      * @method setAwake
      * @description Wakes or sleeps the body.
      * @param {boolean} awake
      */
     setAwake(awake: boolean): void;
+    /**
+     * @method isAwake
+     * @description Whether the body is currently simulated.
+     * @returns {boolean}
+     */
+    isAwake(): boolean;
+    /**
+     * @method setSleepingAllowed
+     * @description Allows or forbids this body from ever sleeping.
+     * @param {boolean} flag
+     */
+    setSleepingAllowed(flag: boolean): void;
+    /**
+     * @method isSleepingAllowed
+     * @returns {boolean}
+     */
+    isSleepingAllowed(): boolean;
+    /**
+     * @method setActive
+     * @description Adds or removes the body from collision detection without
+     * destroying it.
+     * @param {boolean} flag
+     */
+    setActive(flag: boolean): void;
+    /**
+     * @method isActive
+     * @returns {boolean}
+     */
+    isActive(): boolean;
+    /**
+     * @method setFixedRotation
+     * @description Locks or unlocks the body's rotation at runtime.
+     * @param {boolean} flag
+     */
+    setFixedRotation(flag: boolean): void;
+    /**
+     * @method isFixedRotation
+     * @returns {boolean}
+     */
+    isFixedRotation(): boolean;
     /**
      * @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]
@@ -116,6 +258,126 @@ declare class RigidBody {
      * @returns {boolean}
      */
     isContinuous(): boolean;
+    /**
+     * @method setLinearDamping
+     * @description Sets the drag applied to linear motion each step.
+     * @param {number} damping
+     */
+    setLinearDamping(damping: number): void;
+    /**
+     * @method getLinearDamping
+     * @returns {number}
+     */
+    getLinearDamping(): number;
+    /**
+     * @method setAngularDamping
+     * @description Sets the drag applied to rotation each step.
+     * @param {number} damping
+     */
+    setAngularDamping(damping: number): void;
+    /**
+     * @method getAngularDamping
+     * @returns {number}
+     */
+    getAngularDamping(): number;
+    /**
+     * @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: number): void;
+    /**
+     * @method getGravityScale
+     * @returns {number}
+     */
+    getGravityScale(): number;
+    /**
+     * @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(): number;
+    /**
+     * @method getInertia
+     * @description Returns the body's rotational inertia about its center of
+     * mass, in physics units.
+     * @returns {number}
+     */
+    getInertia(): number;
+    /**
+     * @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(): void;
+    /**
+     * @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: any): void;
+    /**
+     * @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: any): Vector2;
+    /**
+     * @method getLocalPoint
+     * @description Converts a world (pixel) point into this body's local frame.
+     * @param {Object} worldPoint - World (pixel) units
+     * @returns {Vector2}
+     */
+    getLocalPoint(worldPoint: any): Vector2;
+    /**
+     * @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: any): Vector2;
+    /**
+     * @method getLocalVector
+     * @description Rotates a world direction into this body's local frame.
+     * @param {Object} worldVector
+     * @returns {Vector2}
+     */
+    getLocalVector(worldVector: any): Vector2;
+    /**
+     * @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(): Array<Contact>;
+    /**
+     * @method getWorld
+     * @description Returns the raw physics {@link World} this body lives in.
+     * @returns {World}
+     */
+    getWorld(): World;
+    /**
+     * @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(): any;
+    /**
+     * @method setUserData
+     * @param {*} data
+     */
+    setUserData(data: any): void;
     /**
      * @method getPosition
      * @description Returns the live world-space position of the body (kept in sync
@@ -144,10 +406,13 @@ declare class RigidBody {
     getCollider(): Collider;
     /**
      * @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(): planck.Body;
+    getBody(): Body;
     /**
      * @method getPhysics
      * @description Returns the physics engine of the rigidbody
@@ -177,7 +442,15 @@ declare class RigidBody {
      * @returns {string | "static" | "dynamic" | "kinematic"} - The type of the rigidbody
      */
     getType(): string | "static" | "dynamic" | "kinematic";
+    /**
+     * @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: string | "static" | "dynamic" | "kinematic"): void;
 }
 import { Vector2 } from "../Physics.js";
 import Collider from "./Collider.js";
-import * as planck from "planck";

package/dist/types/src/importers/Aseprite.d.ts

@@ -4,7 +4,7 @@ export default Aseprite;
  * @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.
@@ -54,7 +54,7 @@ declare 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

package/dist/types/src/importers/ForgeLevel.d.ts

@@ -0,0 +1,97 @@
+export default ForgeLevel;
+declare class ForgeLevel {
+    /**
+     * @method load
+     * @description Builds renderable and collidable objects from a Forge export.
+     * @param {Object} data - The parsed `level.json`
+     * @param {Object} options
+     * @param {Scene} options.scene - Scene to add the layer objects to
+     * @param {Physics} [options.physics] - Physics engine; omit to skip colliders
+     * @param {Object} [options.filter] - Collision filter spec for the colliders
+     * @param {Object} [options.ownerObject] - Owner reported by collision events
+     * @param {boolean} [options.pixelart=true] - NEAREST filtering for the atlas
+     * @param {string} [options.layerOrder="top-first"] - Whether `layers[0]` is
+     *   the topmost layer ("top-first") or the bottommost ("bottom-first")
+     * @returns {Object} - `{ tileSize, cols, rows, width, height, background,
+     *   bounds, layers, colliders, objects, entityTypes, toWorld }`
+     */
+    static load(data: any, options?: {
+        scene: Scene;
+        physics?: Physics;
+        filter?: any;
+        ownerObject?: any;
+        pixelart?: boolean;
+        layerOrder?: string;
+    }): any;
+    /**
+     * @method _readObjects
+     * @description Converts one object layer's entries from grid cells to world
+     * space. An object's `x`/`y` is its top-left cell and `w`/`h` its size in
+     * cells, so a 1x1 object resolves to that cell's centre.
+     * @returns {Array<Object>} - `{ type, name, x, y, width, height, props, layer, cell }`
+     * @private
+     */
+    private static _readObjects;
+    /**
+     * @method _buildTileLayer
+     * @description Turns one tile layer into an InstancedTexture per tileset it
+     * references (a texture switch is a new draw call, so tiles are grouped by
+     * the atlas they come from).
+     * @returns {Array<Object>} - `{ gameObject, instanced, tileset, layer, count }`
+     * @private
+     */
+    private static _buildTileLayer;
+    /**
+     * @method tileTexCoords
+     * @description UV quad for one tile of an atlas, in the corner order
+     * `Drawable.getFrameTexCoords` uses: (R,B) (L,B) (R,T) (L,T). Coordinates are
+     * inset by half a texel so neighbouring tiles never bleed into each other,
+     * and the v axis is flipped because GL samples from the bottom up.
+     * @param {Object} tileset - A Forge tileset entry
+     * @param {number} index - Tile index within the tileset
+     * @param {boolean} [flipH=false]
+     * @param {boolean} [flipV=false]
+     * @returns {number[]} - 8 UV floats
+     */
+    static tileTexCoords(tileset: any, index: number, flipH?: boolean, flipV?: boolean): number[];
+    /**
+     * @method _tilesetFor
+     * @description Finds the tileset that owns a gid (the one with the largest
+     * firstgid not greater than it).
+     * @private
+     */
+    private static _tilesetFor;
+    /**
+     * @method _buildColliders
+     * @description Creates static bodies for solid tiles. Full-tile colliders are
+     * merged into horizontal runs, since BoxCollider is cheaper than a polygon
+     * with the same 4 corners. A tile whose collider shape isn't the full tile
+     * gets its own {@link PolygonCollider} built from that shape's actual
+     * points, in world space, not a bounding-box stand-in.
+     * @returns {Array<RigidBody>}
+     * @private
+     */
+    private static _buildColliders;
+    /**
+     * @method _staticBox
+     * @description Creates one static body with a box collider, in world pixels.
+     * @private
+     */
+    private static _staticBox;
+    /**
+     * @method _staticPolygon
+     * @description Creates one static body with a polygon collider built from a
+     * tile's own collider shape. The body sits at the shape's bounding-box
+     * centre; the polygon's points are converted from Forge's normalised,
+     * top-down tile space into local physics units around that centre.
+     * @private
+     */
+    private static _staticPolygon;
+    /**
+     * @method _boundsOf
+     * @description Normalised bounding box of a collider polygon.
+     * @returns {{x:number, y:number, w:number, h:number}}
+     * @private
+     */
+    private static _boundsOf;
+}

package/dist/types/src/importers/TiledMap.d.ts

@@ -6,7 +6,7 @@ export const GID_MASK: 536870911;
  * @description Imports orthogonal maps exported from the Tiled editor
  * (https://www.mapeditor.org) in JSON format into the engine's Tilemap, plus
  * helpers to pull object layers (spawn points, triggers, etc.) out as plain
- * data. Pure parsing — pass it the already-parsed JSON object (load it with
+ * data. Pure parsing: pass it the already-parsed JSON object (load it with
  * AssetManager.json or fetch).
  *
  * @example

package/dist/types/src/managers/EventManager.d.ts

@@ -104,7 +104,7 @@ declare class EventManager {
      * @method getTopObjectAt
      * @description Returns the topmost active object under a world-space point
      * along with the instance hit (if the object is an InstancedTexture). Topmost
-     * means highest z, with later scene order breaking ties — matching draw order.
+     * means highest z, with later scene order breaking ties, matching draw order.
      * @param {number} worldX - The world-space x coordinate
      * @param {number} worldY - The world-space y coordinate
      * @returns {{object: GameObject, instance: Instance|null}|null}

package/dist/types/src/managers/Gamepad.d.ts

@@ -0,0 +1,102 @@
+export default Gamepad;
+/**
+ * @class Gamepad
+ * @description An autocomplete-friendly way to build the raw gamepad token
+ * strings InputManager already understands ("pad:0:south", etc.). It does
+ * not read input itself, and it is unrelated to the browser's own native
+ * `Gamepad` interface (the objects `navigator.getGamepads()` returns). It
+ * exists purely so you don't have to remember button-name spelling: every
+ * button/stick-direction name InputManager's standard mapping recognizes is
+ * a static constant here, so typing `Gamepad.` in an editor lists them the
+ * way an enum's members would.
+ *
+ * `Gamepad.get(index).key(name)` produces exactly the same string as writing
+ * the token by hand, so the two are fully interchangeable anywhere
+ * InputManager takes one: `mapAction`, `isDown`, `justPressed`,
+ * `justReleased`.
+ *
+ * @example
+ * import { Gamepad, InputManager } from "./index.js";
+ *
+ * const input = new InputManager();
+ * const pad = Gamepad.get(0); // the first controller
+ *
+ * input.mapAction("jump", [pad.key(Gamepad.SOUTH)]);
+ * input.mapAction("left", [pad.key(Gamepad.DPAD_LEFT), pad.key(Gamepad.LEFT_STICK_LEFT)]);
+ *
+ * // in the loop:
+ * if (input.justPressed("jump")) player.jump();
+ */
+declare class Gamepad {
+    /**
+     * @method get
+     * @description Returns the (cached) handle for a pad index: 0 for the
+     * first controller, 1 for the second, and so on.
+     * @param {number} [index=0]
+     * @returns {Gamepad}
+     */
+    static get(index?: number): Gamepad;
+    /**
+     * @private Use `Gamepad.get(index)` rather than constructing directly, so
+     * every caller asking for the same pad index shares one instance.
+     */
+    private constructor();
+    index: any;
+    /**
+     * @method key
+     * @description A face/shoulder/centre/d-pad/stick-as-button token for this
+     * pad. Pass one of the `Gamepad.*` constants (`Gamepad.SOUTH`,
+     * `Gamepad.DPAD_UP`, …). InputManager's standard mapping also accepts a
+     * few vendor aliases these don't cover (e.g. "a", "cross" for `SOUTH`) if
+     * you'd rather think in Xbox/PlayStation terms; those still work as plain
+     * strings, `key()` just doesn't need to name them since `SOUTH` already
+     * reads the same on every pad.
+     * @param {string} name - One of the `Gamepad.*` button constants
+     * @returns {string}
+     */
+    key(name: string): string;
+    /**
+     * @method button
+     * @description A raw button index, mapping-independent: an escape hatch
+     * for a pad whose layout the standard/custom mapping tables don't cover.
+     * @param {number} n
+     * @returns {string}
+     */
+    button(n: number): string;
+    /**
+     * @method axis
+     * @description A raw analog axis past the deadzone, in one direction.
+     * @param {number} n - Axis index (0/1 = left stick X/Y, 2/3 = right stick X/Y on a standard pad)
+     * @param {"+"|"-"} [sign="+"]
+     * @returns {string}
+     */
+    axis(n: number, sign?: "+" | "-"): string;
+}
+declare namespace Gamepad {
+    let _instances: Map<any, any>;
+    let SOUTH: string;
+    let EAST: string;
+    let WEST: string;
+    let NORTH: string;
+    let L1: string;
+    let R1: string;
+    let L2: string;
+    let R2: string;
+    let SELECT: string;
+    let START: string;
+    let HOME: string;
+    let L3: string;
+    let R3: string;
+    let DPAD_UP: string;
+    let DPAD_DOWN: string;
+    let DPAD_LEFT: string;
+    let DPAD_RIGHT: string;
+    let LEFT_STICK_UP: string;
+    let LEFT_STICK_DOWN: string;
+    let LEFT_STICK_LEFT: string;
+    let LEFT_STICK_RIGHT: string;
+    let RIGHT_STICK_UP: string;
+    let RIGHT_STICK_DOWN: string;
+    let RIGHT_STICK_LEFT: string;
+    let RIGHT_STICK_RIGHT: string;
+}