emeraldengine 3.0.0 → 3.1.0

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

@@ -5,10 +5,10 @@ export default InputManager;
  * gamepad support (analog sticks/triggers, semantic button names, rumble,
  * connect events, and per-controller mapping), with rebindable named actions.
  * Call `update()` once per frame so `justPressed`/`justReleased` edge queries
- * work for every device — including the gamepad.
+ * work for every device, including the gamepad.
  *
  * Gamepad tokens (usable anywhere a key token is, including in mapAction and
- * justPressed) — `<i>` is the pad index:
+ * justPressed); `<i>` is the pad index:
  *   "pad:<i>:south" / "pad:<i>:a"      - face buttons (also east/b, west/x, north/y)
  *   "pad:<i>:l1" / "pad:<i>:r2" ...    - shoulders / triggers
  *   "pad:<i>:start" / "pad:<i>:select" - center buttons
@@ -21,6 +21,11 @@ export default InputManager;
  * Names resolve through the active mapping, so "pad:0:south" is the bottom face
  * button regardless of whether the pad reports Xbox or PlayStation ordering.
  *
+ * Typing these by hand means remembering the exact spelling of every button
+ * name above; {@link Gamepad} builds the same strings from named constants
+ * instead (`Gamepad.get(0).key(Gamepad.SOUTH)` === "pad:0:south"), which most
+ * editors will autocomplete the way an enum's members would.
+ *
  * @example
  * const input = new InputManager();
  * input.mapAction("jump", ["Space", " ", "pad:0:south"]);
@@ -65,6 +70,15 @@ declare class InputManager {
     private _disconnectHandlers;
     /** @private */
     private _connected;
+    /**
+     * Which device last produced real input: "keyboard", "mouse",
+     * "gamepad", "touch", or null before anything has happened yet. See
+     * {@link getLastActiveDevice}.
+     * @private
+     */
+    private _lastActiveDevice;
+    /** Pending {@link identifyButton} calls, resolved from `update()`. @private */
+    private _buttonWaiters;
     /** @private */
     private _onKeyDown;
     /** @private */
@@ -251,6 +265,27 @@ declare class InputManager {
      * @returns {boolean}
      */
     isGamepadConnected(padIndex?: number): boolean;
+    /**
+     * @method getLastActiveDevice
+     * @description Which device the player most recently *actually used*,
+     * not just "is a gamepad plugged in" (see `isGamepadConnected`, which stays
+     * true all game long once one is), but "did they just press a key, click,
+     * touch, or move a gamepad button/stick". A pad being connected doesn't
+     * mean it's what's driving the game right now; this is the signal for
+     * swapping on-screen prompts between keyboard and gamepad button icons as
+     * the player actually switches between them mid-session.
+     *
+     * Only counts deliberate input: keydown, mousedown, and touch, not
+     * incidental mouse movement, so idly nudging the mouse while playing on a
+     * pad won't flip prompts back to keyboard/mouse.
+     *
+     * @example
+     * // once per frame, after input.update():
+     * hud.setPromptStyle(input.getLastActiveDevice() === "gamepad" ? "pad" : "keyboard");
+     *
+     * @returns {"keyboard"|"mouse"|"gamepad"|"touch"|null} - null before any input at all
+     */
+    getLastActiveDevice(): "keyboard" | "mouse" | "gamepad" | "touch" | null;
     /**
      * @method getPressedButtons
      * @description Diagnostic: raw indices of all currently pressed buttons on a
@@ -259,6 +294,55 @@ declare class InputManager {
      * @returns {number[]}
      */
     getPressedButtons(padIndex?: number): number[];
+    /**
+     * @method identifyButton
+     * @description Resolves with the raw index of the next *new* button press
+     * on a pad: the reliable way to support a controller whose layout isn't
+     * already covered by the standard/registered mapping tables (a Steam
+     * Controller running outside Steam Input, an old flight stick, anything
+     * with a scrambled button order), instead of guessing indices: ask for one
+     * physical press and record wherever it actually lands on that specific
+     * device. Keep calling `update()` as normal while waiting; the promise
+     * resolves on the frame a button transitions from up to down. A button
+     * already held when this is called doesn't count; only a fresh press does.
+     *
+     * @example
+     * console.log("Press the button you want for Jump…");
+     * const index = await input.identifyButton(0);
+     * InputManager.registerGamepadMapping(input.getGamepadInfo(0).id, {
+     *   buttons: { south: index },
+     * });
+     *
+     * @param {number} [padIndex=0]
+     * @returns {Promise<number>} - Never resolves if no new button is ever pressed
+     */
+    identifyButton(padIndex?: number): Promise<number>;
+    /**
+     * @method calibrateGamepad
+     * @description Walks a list of semantic button names one at a time, asking
+     * for a physical press for each (see {@link identifyButton}), and resolves
+     * with a `{name: rawIndex}` map ready to hand straight to
+     * `InputManager.registerGamepadMapping`, a complete fix for an oddball
+     * controller in a few seconds, without knowing anything about its layout
+     * in advance.
+     *
+     * @example
+     * const mapping = await input.calibrateGamepad(
+     *   0,
+     *   ["south", "east", "west", "north", "l1", "r1", "start"],
+     *   (name, i, total) => showPrompt(`(${i + 1}/${total}) Press the button for "${name}"`)
+     * );
+     * InputManager.registerGamepadMapping(input.getGamepadInfo(0).id, { buttons: mapping });
+     *
+     * @param {number} padIndex
+     * @param {string[]} names - Semantic names to calibrate, e.g. ["south", "east", "start"]
+     * @param {(name: string, index: number, total: number) => void} [onPrompt] -
+     *   Called right before waiting for each name, so you can show "press ___" UI
+     * @returns {Promise<Object.<string, number>>} - { [name]: rawButtonIndex }
+     */
+    calibrateGamepad(padIndex: number, names: string[], onPrompt?: (name: string, index: number, total: number) => void): Promise<{
+        [x: string]: number;
+    }>;
     /**
      * @method _decodeHat
      * @description Some non-standard pads report the d-pad as an 8-way "hat" on a
@@ -282,6 +366,13 @@ declare class InputManager {
      * per frame after reading input.
      */
     update(): void;
+    /**
+     * @method _resolveButtonWaiters
+     * @description Resolves any {@link identifyButton} calls whose pad just
+     * saw a button go from up to down.
+     * @private
+     */
+    private _resolveButtonWaiters;
     /**
      * @method destroy
      * @description Removes all event listeners.

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

@@ -3,7 +3,7 @@ export default NetworkManager;
  * @class NetworkManager
  * @description A thin, optional multiplayer layer over Colyseus. `colyseus.js`
  * is an optional peer dependency and is imported dynamically, so the engine has
- * no hard dependency on it — games that don't use networking never load it.
+ * no hard dependency on it, so games that don't use networking never load it.
  *
  * It wraps connection/room lifecycle, exposes a small event API
  * (onStateChange / onMessage / onAdd / onRemove / onLeave), and bundles an
@@ -74,7 +74,7 @@ declare class NetworkManager {
     send(type: any, payload: any): this;
     /**
      * @method now
-     * @description Seconds since this manager was created — a convenient clock for
+     * @description Seconds since this manager was created, a convenient clock for
      * feeding the interpolator.
      * @returns {number}
      */

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

@@ -4,7 +4,7 @@ export default RenderStats;
  * @description Frame-level render counters, incremented by every draw site in
  * the engine (Drawable, InstancedTexture, SpriteBatch, post-processing) and
  * reset at the start of each drawScene. Read the previous completed frame via
- * `RenderStats.frame` or `emerald.getRenderStats()` — DebugOverlay shows it
+ * `RenderStats.frame` or `emerald.getRenderStats()`. DebugOverlay shows it
  * automatically.
  *
  * - drawCalls:    GPU draw commands issued (the batching win shows up here)

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

@@ -42,7 +42,7 @@ declare class TextureManager {
      * @method restoreAll
      * @description Re-uploads every cached texture after a WebGL context loss.
      * The image cache survives the loss, so this is upload-only (no network).
-     * Reference counts are untouched — they track logical ownership by
+     * Reference counts are untouched: they track logical ownership by
      * drawables, which still exist.
      */
     static restoreAll(): void;

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

@@ -0,0 +1,92 @@
+export default AABB;
+/**
+ * @class AABB
+ * @description An axis-aligned bounding box in physics space. Used by the
+ * broadphase to reject pairs long before any real collision maths runs.
+ */
+declare class AABB {
+    /**
+     * @method testOverlap
+     * @description True when two boxes overlap.
+     * @param {AABB} a
+     * @param {AABB} b
+     * @returns {boolean}
+     */
+    static testOverlap(a: AABB, b: AABB): boolean;
+    constructor(lowerX?: number, lowerY?: number, upperX?: number, upperY?: number);
+    lowerBound: Vec2;
+    upperBound: Vec2;
+    /**
+     * @method set
+     * @description Sets all four bounds in place.
+     * @param {number} lx
+     * @param {number} ly
+     * @param {number} ux
+     * @param {number} uy
+     * @returns {AABB} - this
+     */
+    set(lx: number, ly: number, ux: number, uy: number): AABB;
+    /**
+     * @method copy
+     * @description Copies another AABB.
+     * @param {AABB} other
+     * @returns {AABB} - this
+     */
+    copy(other: AABB): AABB;
+    /**
+     * @method getCenter
+     * @description Returns the box center.
+     * @returns {Vec2}
+     */
+    getCenter(): Vec2;
+    /**
+     * @method getExtents
+     * @description Returns the box half-extents.
+     * @returns {Vec2}
+     */
+    getExtents(): Vec2;
+    /**
+     * @method getPerimeter
+     * @description Perimeter of the box, the cost function the AABB tree
+     * minimizes when choosing where to insert a leaf.
+     * @returns {number}
+     */
+    getPerimeter(): number;
+    /**
+     * @method combine
+     * @description Sets this box to the union of two others.
+     * @param {AABB} a
+     * @param {AABB} b
+     * @returns {AABB} - this
+     */
+    combine(a: AABB, b: AABB): AABB;
+    /**
+     * @method extend
+     * @description Grows the box by `amount` on every side.
+     * @param {number} amount
+     * @returns {AABB} - this
+     */
+    extend(amount: number): AABB;
+    /**
+     * @method contains
+     * @description True when `other` lies entirely inside this box.
+     * @param {AABB} other
+     * @returns {boolean}
+     */
+    contains(other: AABB): boolean;
+    /**
+     * @method containsPoint
+     * @description True when a point lies inside this box.
+     * @param {Object} p - `{ x, y }`
+     * @returns {boolean}
+     */
+    containsPoint(p: any): boolean;
+    /**
+     * @method rayCast
+     * @description Slab test of a ray against this box.
+     * @param {Object} input - `{ p1, p2, maxFraction }`
+     * @returns {boolean} - True if the ray hits the box within maxFraction
+     */
+    rayCast(input: any): boolean;
+}
+import { Vec2 } from "./Math2D.js";

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

@@ -0,0 +1,435 @@
+/**
+ * @class Body
+ * @description A rigid body: a position, an orientation, and the velocity and
+ * mass that go with them. Collision geometry lives on its fixtures, added with
+ * {@link Body#createFixture}. Bodies are created through
+ * {@link World#createBody}, never with `new`.
+ *
+ * Everything here is in physics units (meters, radians, seconds). The engine's
+ * {@link RigidBody} component is the pixel-space wrapper around this class.
+ *
+ * @param {World} world - The owning world
+ * @param {Object} [def] - `{ type, position, angle, linearVelocity,
+ *   angularVelocity, linearDamping, angularDamping, fixedRotation, bullet,
+ *   allowSleep, awake, active, gravityScale, userData }`
+ */
+export class Body {
+    constructor(world: any, def?: {});
+    world: any;
+    type: any;
+    xf: Transform2;
+    sweep: Sweep;
+    linearVelocity: Vec2;
+    angularVelocity: any;
+    force: Vec2;
+    torque: number;
+    linearDamping: any;
+    angularDamping: any;
+    gravityScale: any;
+    mass: number;
+    invMass: number;
+    I: number;
+    invI: number;
+    fixedRotation: boolean;
+    bullet: boolean;
+    allowSleep: boolean;
+    awake: boolean;
+    active: boolean;
+    sleepTime: number;
+    userData: any;
+    /** Head of this body's fixture list. @private */
+    private fixtureList;
+    /** @private */
+    private fixtureCount;
+    /** Contacts this body currently takes part in. @private */
+    private contacts;
+    /** Joints this body currently takes part in. @private */
+    private joints;
+    /** @private */
+    private prev;
+    /** @private */
+    private next;
+    /** Scratch flag used while building solver islands. @private */
+    private islandFlag;
+    /** Index into the current island's body array. @private */
+    private islandIndex;
+    /**
+     * @method createFixture
+     * @description Attaches a shape to this body. The second argument may be a
+     * plain density number or a definition object.
+     * @param {Shape} shape - A CircleShape or PolygonShape
+     * @param {Object|number} [def] - `{ density, friction, restitution, isSensor,
+     *   filterCategoryBits, filterMaskBits, filterGroupIndex, userData }`
+     * @returns {Fixture} - The new fixture
+     */
+    createFixture(shape: Shape, def?: any | number): Fixture;
+    /**
+     * @method destroyFixture
+     * @description Removes a fixture and every contact it was part of.
+     * @param {Fixture} fixture
+     */
+    destroyFixture(fixture: Fixture): void;
+    /**
+     * @method getFixtureList
+     * @description Returns the first fixture; walk the rest with
+     * {@link Fixture#getNext}.
+     * @returns {Fixture|null}
+     */
+    getFixtureList(): Fixture | null;
+    /**
+     * @method getNext
+     * @description Returns the next body in the world's list.
+     * @returns {Body|null}
+     */
+    getNext(): Body | null;
+    /**
+     * @method setUserData
+     * @description Attaches arbitrary data to the body. The engine stores the
+     * owning {@link RigidBody} here so contacts can be traced back to game
+     * objects.
+     * @param {*} data
+     */
+    setUserData(data: any): void;
+    /**
+     * @method getUserData
+     * @description Returns the attached data.
+     * @returns {*}
+     */
+    getUserData(): any;
+    /**
+     * @method getWorld
+     * @description Returns the owning world.
+     * @returns {World}
+     */
+    getWorld(): World;
+    /**
+     * @method getType
+     * @description Returns "static", "kinematic" or "dynamic".
+     * @returns {string}
+     */
+    getType(): string;
+    /**
+     * @method setType
+     * @description Changes the body type at runtime, resetting velocities and
+     * re-deriving mass. Existing contacts are dropped so they rebuild against the
+     * new type.
+     * @param {string} type - "static", "kinematic" or "dynamic"
+     */
+    setType(type: string): void;
+    /**
+     * @method setTransform
+     * @description Teleports the body: sets position and angle directly, without
+     * any velocity implied by the move.
+     *
+     * A teleport wakes the body. Contacts are only re-evaluated for bodies that
+     * are awake, so a sleeping body dropped into a new spot would otherwise sit
+     * there without noticing what it now overlaps: respawning a player onto a
+     * pickup, for instance, would silently miss it.
+     *
+     * @param {Object} position - `{ x, y }` in physics units
+     * @param {number} angle - Radians
+     */
+    setTransform(position: any, angle: number): void;
+    /**
+     * @method setPosition
+     * @description Moves the body, keeping its angle.
+     * @param {Object} position - `{ x, y }` in physics units
+     */
+    setPosition(position: any): void;
+    /**
+     * @method setAngle
+     * @description Rotates the body, keeping its position.
+     * @param {number} angle - Radians
+     */
+    setAngle(angle: number): void;
+    /**
+     * @method getTransform
+     * @description Returns the body's transform (live reference).
+     * @returns {Transform2}
+     */
+    getTransform(): Transform2;
+    /**
+     * @method getPosition
+     * @description Returns the body origin in world space (live reference).
+     * @returns {Vec2}
+     */
+    getPosition(): Vec2;
+    /**
+     * @method getAngle
+     * @description Returns the body's angle in radians.
+     * @returns {number}
+     */
+    getAngle(): number;
+    /**
+     * @method getWorldCenter
+     * @description Returns the center of mass in world space.
+     * @returns {Vec2}
+     */
+    getWorldCenter(): Vec2;
+    /**
+     * @method getLocalCenter
+     * @description Returns the center of mass in the body's frame.
+     * @returns {Vec2}
+     */
+    getLocalCenter(): Vec2;
+    /**
+     * @method getWorldPoint
+     * @description Converts a local point to world space.
+     * @param {Object} localPoint
+     * @returns {Vec2}
+     */
+    getWorldPoint(localPoint: any): Vec2;
+    /**
+     * @method getLocalPoint
+     * @description Converts a world point to the body's frame.
+     * @param {Object} worldPoint
+     * @returns {Vec2}
+     */
+    getLocalPoint(worldPoint: any): Vec2;
+    /**
+     * @method getWorldVector
+     * @description Rotates a local direction into world space.
+     * @param {Object} localVector
+     * @returns {Vec2}
+     */
+    getWorldVector(localVector: any): Vec2;
+    /**
+     * @method getLocalVector
+     * @description Rotates a world direction into the body's frame.
+     * @param {Object} worldVector
+     * @returns {Vec2}
+     */
+    getLocalVector(worldVector: any): Vec2;
+    /**
+     * @method setLinearVelocity
+     * @description Sets the velocity of the center of mass.
+     * @param {Object} velocity - `{ x, y }` in physics units per second
+     */
+    setLinearVelocity(velocity: any): void;
+    /**
+     * @method getLinearVelocity
+     * @description Returns the velocity of the center of mass (live reference).
+     * @returns {Vec2}
+     */
+    getLinearVelocity(): Vec2;
+    /**
+     * @method getLinearVelocityFromWorldPoint
+     * @description Velocity of the material point of this body that currently
+     * coincides with a world point (linear plus the spin contribution).
+     * @param {Object} worldPoint
+     * @returns {Vec2}
+     */
+    getLinearVelocityFromWorldPoint(worldPoint: any): Vec2;
+    /**
+     * @method setAngularVelocity
+     * @description Sets the spin in radians per second.
+     * @param {number} omega
+     */
+    setAngularVelocity(omega: number): void;
+    /**
+     * @method getAngularVelocity
+     * @description Returns the spin in radians per second.
+     * @returns {number}
+     */
+    getAngularVelocity(): number;
+    /**
+     * @method applyForce
+     * @description Applies a force at a world point. Forces are cleared at the
+     * end of every step, so this belongs in your update loop.
+     * @param {Object} force
+     * @param {Object} [point] - Defaults to the center of mass
+     * @param {boolean} [wake=true]
+     */
+    applyForce(force: any, point?: any, wake?: boolean): void;
+    /**
+     * @method applyForceToCenter
+     * @description Applies a force at the center of mass (no torque).
+     * @param {Object} force
+     * @param {boolean} [wake=true]
+     */
+    applyForceToCenter(force: any, 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 applyLinearImpulse
+     * @description Applies an instantaneous change in momentum at a world point.
+     * Unlike a force, an impulse takes effect immediately: this is what a jump
+     * or a knockback should use.
+     * @param {Object} impulse
+     * @param {Object} [point] - Defaults to the center of mass
+     * @param {boolean} [wake=true]
+     */
+    applyLinearImpulse(impulse: any, 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 getMass
+     * @description Returns the body's mass.
+     * @returns {number}
+     */
+    getMass(): number;
+    /**
+     * @method getInertia
+     * @description Returns the rotational inertia about the center of mass.
+     * @returns {number}
+     */
+    getInertia(): number;
+    /**
+     * @method resetMassData
+     * @description Recomputes mass, center of mass and inertia from the
+     * fixtures' densities. Called automatically when fixtures change.
+     */
+    resetMassData(): void;
+    /**
+     * @method setMassData
+     * @description Overrides the computed mass properties.
+     * @param {Object} massData - `{ mass, center, I }`
+     */
+    setMassData(massData: any): void;
+    /**
+     * @method setAwake
+     * @description Wakes the body or puts it to sleep. A sleeping body is skipped
+     * by the solver until something touches it, which is what keeps a settled
+     * pile of crates free.
+     * @param {boolean} flag
+     */
+    setAwake(flag: 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
+     * @description Whether this body may sleep.
+     * @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
+     * @description Whether the body takes part in collision detection.
+     * @returns {boolean}
+     */
+    isActive(): boolean;
+    /**
+     * @method setFixedRotation
+     * @description Locks or unlocks the body's rotation. Locking is the usual
+     * choice for player characters, which should never topple over.
+     * @param {boolean} flag
+     */
+    setFixedRotation(flag: boolean): void;
+    /**
+     * @method isFixedRotation
+     * @description Whether rotation is locked.
+     * @returns {boolean}
+     */
+    isFixedRotation(): boolean;
+    /**
+     * @method setBullet
+     * @description Turns continuous collision detection on for this body, so it
+     * is swept against static geometry instead of teleporting between steps.
+     * @param {boolean} flag
+     */
+    setBullet(flag: boolean): void;
+    /**
+     * @method isBullet
+     * @description Whether continuous collision detection is enabled.
+     * @returns {boolean}
+     */
+    isBullet(): boolean;
+    /**
+     * @method setLinearDamping
+     * @description Sets the drag applied to linear motion each step.
+     * @param {number} damping
+     */
+    setLinearDamping(damping: number): void;
+    /**
+     * @method getLinearDamping
+     * @description Returns the linear damping.
+     * @returns {number}
+     */
+    getLinearDamping(): number;
+    /**
+     * @method setAngularDamping
+     * @description Sets the drag applied to rotation each step.
+     * @param {number} damping
+     */
+    setAngularDamping(damping: number): void;
+    /**
+     * @method getAngularDamping
+     * @description Returns the angular damping.
+     * @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
+     * @description Returns the gravity multiplier.
+     * @returns {number}
+     */
+    getGravityScale(): number;
+    /**
+     * @method getContactList
+     * @description Returns the contacts this body is part of.
+     * @returns {Array<Contact>}
+     */
+    getContactList(): Array<Contact>;
+    /**
+     * @method synchronizeTransform
+     * @description Rebuilds the body transform from the sweep's current state.
+     * @private
+     */
+    private synchronizeTransform;
+    /**
+     * @method synchronizeFixtures
+     * @description Updates the broadphase proxies to span where the body was at
+     * the start of the step and where it is now.
+     * @param {Transform2} [xf1] - Optional explicit "before" transform
+     * @private
+     */
+    private synchronizeFixtures;
+    /**
+     * @method advance
+     * @description Moves the body to a fraction of its sweep, used by continuous
+     * collision detection when an impact is found mid-step.
+     * @param {number} alpha
+     * @private
+     */
+    private advance;
+}
+import { BodyType } from "./BodyType.js";
+import { Transform2 } from "./Math2D.js";
+import { Sweep } from "./Math2D.js";
+import { Vec2 } from "./Math2D.js";
+import { Fixture } from "./Fixture.js";
+export { BodyType };