emeraldengine 2.2.1 → 3.0.0

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

@@ -0,0 +1,290 @@
+export default InputManager;
+/**
+ * @class InputManager
+ * @description Unified, pollable input: keyboard, mouse, touch, and full
+ * 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.
+ *
+ * Gamepad tokens (usable anywhere a key token is, including in mapAction and
+ * 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
+ *   "pad:<i>:dpadLeft" ...             - d-pad (works via buttons or a hat axis)
+ *   "pad:<i>:<n>"                      - raw button index (mapping-independent)
+ *   "pad:<i>:axis<n>+" / "axis<n>-"    - analog axis past the deadzone
+ *   "pad:<i>:leftStickUp" / "Down" / "Left" / "Right" - stick as a d-pad
+ *   "pad:<i>:rightStickUp" ...         - (threshold: stickPressThreshold)
+ *   "gamepad:<n>"                      - legacy: raw button <n> on pad 0
+ * 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.
+ *
+ * @example
+ * const input = new InputManager();
+ * input.mapAction("jump", ["Space", " ", "pad:0:south"]);
+ * input.mapAction("left", ["a", "ArrowLeft", "pad:0:dpadLeft"]);
+ * input.onGamepadConnected((info) => console.log("pad:", info.id, info.mapping));
+ * // in the loop:
+ * if (input.justPressed("jump")) { player.jump(); input.rumble(0, { duration: 120 }); }
+ * const { x } = input.getGamepadStick("left");   // analog, deadzoned
+ * input.update();
+ */
+declare class InputManager {
+    /**
+     * @method registerGamepadMapping
+     * @description Registers a custom button/axis mapping for controllers whose
+     * `mapping` is not "standard" (so their raw button indices differ). Match by
+     * a substring of `gamepad.id` (case-insensitive), a RegExp, or a predicate.
+     * @param {string|RegExp|Function} match - id matcher
+     * @param {Object} mapping - { buttons:{name:index}, axes:{name:index} };
+     *   merged over the standard table, so you only specify what differs.
+     */
+    static registerGamepadMapping(match: string | RegExp | Function, mapping?: any): void;
+    constructor(options?: {});
+    target: any;
+    actions: Map<any, any>;
+    down: Set<any>;
+    prevDown: Set<any>;
+    mouse: {
+        x: number;
+        y: number;
+        buttons: Set<any>;
+    };
+    touches: any[];
+    gamepads: any[];
+    gamepadDeadzone: any;
+    gamepadCurve: any;
+    stickPressThreshold: any;
+    /** @private */
+    private _gamepadTokens;
+    /** @private */
+    private _connectHandlers;
+    /** @private */
+    private _disconnectHandlers;
+    /** @private */
+    private _connected;
+    /** @private */
+    private _onKeyDown;
+    /** @private */
+    private _onKeyUp;
+    /** @private */
+    private _onMouseDown;
+    /** @private */
+    private _onMouseUp;
+    /** @private */
+    private _onMouseMove;
+    /** @private */
+    private _onTouch;
+    /** @private */
+    private _onGamepadConnected;
+    /** @private */
+    private _onGamepadDisconnected;
+    /** @private */
+    private _normKey;
+    /**
+     * @method mapAction
+     * @description Binds an action name to one or more input tokens (keys,
+     * "mouse:0", or any gamepad token above).
+     * @param {string} name - Action name
+     * @param {string[]} tokens - Input tokens
+     * @returns {InputManager} - this
+     */
+    mapAction(name: string, tokens: string[]): InputManager;
+    /** @private */
+    private _tokensFor;
+    /** @private */
+    private _tokenDown;
+    /**
+     * @method isDown
+     * @description Whether the action (or raw token) is currently held.
+     */
+    isDown(actionOrToken: any): any;
+    /**
+     * @method justPressed
+     * @description Whether the action became pressed this frame.
+     */
+    justPressed(actionOrToken: any): any;
+    /**
+     * @method justReleased
+     * @description Whether the action was released this frame.
+     */
+    justReleased(actionOrToken: any): any;
+    /**
+     * @method getAxis
+     * @description Returns -1/0/+1 based on two opposing actions.
+     */
+    getAxis(negative: any, positive: any): number;
+    /**
+     * @method getGamepad
+     * @description Returns the polled gamepad at an index (or null).
+     */
+    getGamepad(index?: number): any;
+    /**
+     * @method setGamepadDeadzone
+     * @description Sets the analog deadzone (0..1) for axes and trigger buttons.
+     * @returns {InputManager} - this
+     */
+    setGamepadDeadzone(dz: any): InputManager;
+    /**
+     * @method setGamepadCurve
+     * @description Sets the response-curve exponent applied to deadzoned analog
+     * values: 1 = linear (default), >1 = softer near center for fine aiming.
+     * @returns {InputManager} - this
+     */
+    setGamepadCurve(exp: any): InputManager;
+    /**
+     * @method _rescaleAxis
+     * @description Deadzone + rescale + curve for a single axis value. Unlike a
+     * hard cutoff, the output ramps smoothly from 0 at the deadzone edge to ±1
+     * at full deflection (no jump, and the full range stays reachable).
+     * @private
+     */
+    private _rescaleAxis;
+    /**
+     * @method _buttonMapFor
+     * @description Resolves the button-name → index table for a gamepad: a
+     * registered custom mapping (matched by id) wins; otherwise the standard
+     * table is used (also as the best-effort fallback for unknown non-standard
+     * pads).
+     * @private
+     */
+    private _buttonMapFor;
+    /**
+     * @method getGamepadAxis
+     * @description Returns a deadzoned analog axis value (-1..1). The value is
+     * RESCALED past the deadzone (0 at the edge, ±1 at full deflection) and runs
+     * through the response curve, so there is no jump at the threshold. Standard
+     * mapping: axis 0/1 = left stick X/Y, 2/3 = right stick X/Y.
+     * @param {number} axisIndex
+     * @param {number} [padIndex=0]
+     * @returns {number}
+     */
+    getGamepadAxis(axisIndex: number, padIndex?: number): number;
+    /**
+     * @method getGamepadStick
+     * @description Returns the left or right stick with a RADIAL deadzone: the
+     * deadzone applies to the stick's distance from center (not per axis), so
+     * diagonals aren't clipped square and direction is preserved exactly. The
+     * magnitude is rescaled to use the full 0..1 range and shaped by the
+     * response curve.
+     * @param {"left"|"right"} [side="left"]
+     * @param {number} [padIndex=0]
+     * @param {Object} [opts] - { deadzone, curve, invertY } overrides. invertY
+     *   flips the browser's y-down convention so up = +1.
+     * @returns {{x:number, y:number, magnitude:number, angle:number}}
+     */
+    getGamepadStick(side?: "left" | "right", padIndex?: number, opts?: any): {
+        x: number;
+        y: number;
+        magnitude: number;
+        angle: number;
+    };
+    /**
+     * @method _axisMapFor
+     * @description Axis-name table for a pad (custom/built-in mapping wins for
+     * non-standard pads, else the standard table).
+     * @private
+     */
+    private _axisMapFor;
+    /**
+     * @method getGamepadButton
+     * @description Looks up a button by semantic name (e.g. "south", "a", "r1",
+     * "start", "dpadLeft") or raw index through the pad's active mapping.
+     * @param {string|number} name
+     * @param {number} [padIndex=0]
+     * @returns {{pressed:boolean, value:number, index:number}}
+     */
+    getGamepadButton(name: string | number, padIndex?: number): {
+        pressed: boolean;
+        value: number;
+        index: number;
+    };
+    /**
+     * @method getGamepadTrigger
+     * @description Returns the analog value (0..1) of a trigger.
+     * @param {"left"|"right"} [side="left"]
+     * @param {number} [padIndex=0]
+     * @returns {number}
+     */
+    getGamepadTrigger(side?: "left" | "right", padIndex?: number): number;
+    /**
+     * @method rumble
+     * @description Plays a vibration effect on a pad (where supported).
+     * @param {number} [padIndex=0]
+     * @param {Object} [opts] - { duration=200, strong=1, weak=1 }
+     * @returns {Promise|undefined}
+     */
+    rumble(padIndex?: number, opts?: any): Promise<any> | undefined;
+    /**
+     * @method onGamepadConnected
+     * @description Registers a callback fired when a pad connects (also called for
+     * pads already connected at registration time). Receives an info object.
+     * @param {Function} cb
+     * @returns {InputManager} - this
+     */
+    onGamepadConnected(cb: Function): InputManager;
+    /**
+     * @method onGamepadDisconnected
+     * @description Registers a callback fired when a pad disconnects.
+     * @returns {InputManager} - this
+     */
+    onGamepadDisconnected(cb: any): InputManager;
+    /** @private */
+    private _infoFromPad;
+    /**
+     * @method getGamepadInfo
+     * @description Diagnostic info for a connected pad (id, mapping, counts).
+     * @param {number} [padIndex=0]
+     * @returns {Object|null}
+     */
+    getGamepadInfo(padIndex?: number): any | null;
+    /**
+     * @method getConnectedGamepads
+     * @description Info for every currently polled pad.
+     * @returns {Object[]}
+     */
+    getConnectedGamepads(): any[];
+    /**
+     * @method isGamepadConnected
+     * @returns {boolean}
+     */
+    isGamepadConnected(padIndex?: number): boolean;
+    /**
+     * @method getPressedButtons
+     * @description Diagnostic: raw indices of all currently pressed buttons on a
+     * pad. Handy for discovering an unknown controller's layout.
+     * @param {number} [padIndex=0]
+     * @returns {number[]}
+     */
+    getPressedButtons(padIndex?: number): number[];
+    /**
+     * @method _decodeHat
+     * @description Some non-standard pads report the d-pad as an 8-way "hat" on a
+     * single axis instead of buttons 12-15. When a pad is non-standard and exposes
+     * an extra (odd) trailing axis, decode it into d-pad direction tokens.
+     * @private
+     */
+    private _decodeHat;
+    /**
+     * @method _collectGamepadTokens
+     * @description Rebuilds the active gamepad token set (raw indices, semantic
+     * names via the pad's mapping, d-pad, and axis directions) for every connected
+     * pad, so gamepad input flows through the same down/justPressed machinery as
+     * the keyboard.
+     * @private
+     */
+    private _collectGamepadTokens;
+    /**
+     * @method update
+     * @description Polls gamepads and advances edge-detection state. Call once
+     * per frame after reading input.
+     */
+    update(): void;
+    /**
+     * @method destroy
+     * @description Removes all event listeners.
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,93 @@
+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.
+ *
+ * It wraps connection/room lifecycle, exposes a small event API
+ * (onStateChange / onMessage / onAdd / onRemove / onLeave), and bundles an
+ * {@link Interpolator} so remote entities can be rendered smoothly.
+ *
+ * @example
+ * const net = new NetworkManager();
+ * await net.connect("wss://my-server");
+ * const room = await net.join("arena", { name: "P1" });
+ * net.onMessage("hit", (msg) => applyHit(msg));
+ * net.onStateChange((state) => {
+ *   for (const [id, p] of state.players) net.interpolator.push(id, p, net.now());
+ * });
+ * // each frame:
+ * const pos = net.interpolator.sample(remoteId, net.now());
+ */
+declare class NetworkManager {
+    /** @private */
+    private static _now;
+    constructor(options?: {});
+    client: import("colyseus.js").Client;
+    room: import("colyseus.js").Room<any>;
+    interpolator: Interpolator;
+    /** @private */
+    private _messageHandlers;
+    /** @private */
+    private _stateHandlers;
+    /** @private */
+    private _leaveHandlers;
+    /** @private */
+    private _startTime;
+    /**
+     * @method connect
+     * @description Dynamically imports colyseus.js and creates a Client.
+     * @param {string} endpoint - The server endpoint (e.g. "wss://host:2567")
+     * @returns {Promise<NetworkManager>} - this
+     */
+    connect(endpoint: string): Promise<NetworkManager>;
+    /**
+     * @method join
+     * @description Joins (or creates) a room by name and wires up the event hooks.
+     * @param {string} roomName - The room name
+     * @param {Object} [options] - Join options forwarded to the server
+     * @returns {Promise<Object>} - The joined room
+     */
+    join(roomName: string, options?: any): Promise<any>;
+    /** @private */
+    private _wireRoom;
+    /**
+     * @method onStateChange
+     * @description Registers a handler for full room-state updates.
+     */
+    onStateChange(handler: any): this;
+    /**
+     * @method onMessage
+     * @description Registers a handler for a server message type.
+     */
+    onMessage(type: any, handler: any): this;
+    /**
+     * @method onLeave
+     * @description Registers a handler invoked when the room is left.
+     */
+    onLeave(handler: any): this;
+    /**
+     * @method send
+     * @description Sends a typed message to the server.
+     */
+    send(type: any, payload: any): this;
+    /**
+     * @method now
+     * @description Seconds since this manager was created — a convenient clock for
+     * feeding the interpolator.
+     * @returns {number}
+     */
+    now(): number;
+    /**
+     * @method leave
+     * @description Leaves the current room.
+     */
+    leave(): Promise<void>;
+    /**
+     * @method sessionId
+     * @returns {string|null} - This client's session id, if joined.
+     */
+    get sessionId(): string | null;
+}
+import Interpolator from "../Interpolator.js";

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

@@ -0,0 +1,34 @@
+export default RenderStats;
+/**
+ * @class 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
+ * automatically.
+ *
+ * - drawCalls:    GPU draw commands issued (the batching win shows up here)
+ * - quads:        sprites/shapes drawn, counting every instance in a batch
+ * - textureBinds: texture switches (high numbers = poor batching order)
+ */
+declare class RenderStats {
+    /**
+     * @method beginFrame
+     * @description Snapshots the counters gathered since the previous call into
+     * `frame` and zeroes the accumulators. Called by Emerald.drawScene.
+     */
+    static beginFrame(): void;
+}
+declare namespace RenderStats {
+    let drawCalls: number;
+    let quads: number;
+    let textureBinds: number;
+    namespace frame {
+        let drawCalls_1: number;
+        export { drawCalls_1 as drawCalls };
+        let quads_1: number;
+        export { quads_1 as quads };
+        let textureBinds_1: number;
+        export { textureBinds_1 as textureBinds };
+    }
+}

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

@@ -0,0 +1,44 @@
+export default SceneManager;
+/**
+ * @class SceneManager
+ * @description Manages the scene for the game
+ */
+declare class SceneManager {
+    /**
+     * @method setScene
+     * @description Sets the scene
+     * @param {Scene} scene - The scene to set
+     */
+    static setScene(scene: Scene): void;
+    /**
+     * @method getScene
+     * @description Returns the scene
+     * @returns {Scene} - The scene
+     */
+    static getScene(): Scene;
+    /**
+     * @method transitionTo
+     * @description Switches the active scene, optionally behind a ScreenEffects
+     * fade. With `screenEffects` provided the screen fades out, the scene is
+     * swapped (and your optional `onSwap` runs) while covered, then fades back in.
+     * Without it the swap happens immediately.
+     *
+     * @param {Scene} scene - The scene to make active
+     * @param {Object} [options]
+     * @param {ScreenEffects} [options.screenEffects] - Effects layer to fade with
+     * @param {Function} [options.onSwap] - `(scene) => void|Promise`, run during
+     *   the covered swap (e.g. (re)build the new scene's contents)
+     * @param {number} [options.duration] - Fade duration (seconds)
+     * @param {Color} [options.color] - Fade color
+     * @returns {Promise<Scene>} - Resolves with the new scene
+     */
+    static transitionTo(scene: Scene, options?: {
+        screenEffects?: ScreenEffects;
+        onSwap?: Function;
+        duration?: number;
+        color?: Color;
+    }): Promise<Scene>;
+}
+declare namespace SceneManager {
+    let scene: any;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * @class ShaderManager
+ * @description Manages the shaders for the game
+ */
+export class ShaderManager {
+    constructor(gl: any);
+    gl: any;
+    shaders: Map<any, any>;
+    activeShader: any;
+    /**
+     * @method createShader
+     * @description Creates a shader
+     * @param {string} name - The name of the shader
+     * @param {string} vertexSource - The vertex shader source
+     * @param {string} fragmentSource - The fragment shader source
+     */
+    createShader(name: string, vertexSource: string, fragmentSource: string): {
+        program: any;
+        attribLocations: any;
+        uniformLocations: any;
+    };
+    /**
+     * @method compileShader
+     * @description Compiles a shader
+     * @param {string} source - The shader source
+     * @param {number} type - The type of shader
+     */
+    compileShader(source: string, type: number): any;
+    /**
+     * @method useShader
+     * @description Uses a shader
+     * @param {string} name - The name of the shader
+     */
+    useShader(name: string): any;
+    /**
+     * @method getActiveShader
+     * @description Returns the active shader
+     * @returns {Object} - The active shader
+     */
+    getActiveShader(): any;
+    /**
+     * @method getAttributeLocations
+     * @description Returns the attribute locations for a shader program
+     * @param {WebGLProgram} program - The shader program
+     * @returns {Object} - The attribute locations
+     */
+    getAttributeLocations(program: WebGLProgram): any;
+    /**
+     * @method getUniformLocations
+     * @description Returns the uniform locations for a shader program
+     * @param {WebGLProgram} program - The shader program
+     * @returns {Object} - The uniform locations
+     */
+    getUniformLocations(program: WebGLProgram): any;
+}

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

@@ -0,0 +1,102 @@
+export default TextureManager;
+/**
+ * @class TextureManager
+ * @description Caches loaded images and GL textures so that many drawables
+ * sharing the same texture path download and upload the image only once.
+ *
+ * Textures are immutable after upload in this engine, so the same GL texture
+ * object can safely be bound by any number of objects. The GL-texture cache is
+ * keyed by path *and* filter mode, because pixel-art (NEAREST) and smooth
+ * (LINEAR) sampling require separate texture objects.
+ */
+declare class TextureManager {
+    /**
+     * @method loadImage
+     * @description Loads (and caches) an HTMLImageElement for a given path.
+     * Concurrent requests for the same path share a single in-flight load.
+     * @param {string} path - The path (or data URL) of the image
+     * @returns {Promise<HTMLImageElement>} - The loaded image
+     */
+    static loadImage(path: string): Promise<HTMLImageElement>;
+    /**
+     * @method getTexture
+     * @description Returns a cached GL texture for the given path, creating and
+     * uploading it on first request. Subsequent calls reuse the same texture.
+     * @param {string} path - The path (or data URL) of the texture
+     * @param {boolean} pixelart - Whether to sample with NEAREST (pixel art) filtering
+     * @returns {Promise<{texture: WebGLTexture, width: number, height: number}>}
+     */
+    static getTexture(path: string, pixelart?: boolean): Promise<{
+        texture: WebGLTexture;
+        width: number;
+        height: number;
+    }>;
+    /**
+     * @method _upload
+     * @description Loads the image (via the shared image cache) and uploads it
+     * as a GL texture with the requested filtering.
+     * @private
+     */
+    private static _upload;
+    /**
+     * @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
+     * drawables, which still exist.
+     */
+    static restoreAll(): void;
+    /**
+     * @method preload
+     * @description Eagerly loads a list of texture paths so they are ready (and
+     * cached) before the first frame that needs them.
+     * @param {string[]} paths - The texture paths to preload
+     * @param {boolean} pixelart - Whether to use pixel-art filtering
+     * @returns {Promise<void>}
+     */
+    static preload(paths: string[], pixelart?: boolean): Promise<void>;
+    /**
+     * @method has
+     * @description Checks whether a GL texture is already cached for a path
+     * @param {string} path - The texture path
+     * @param {boolean} pixelart - Whether the pixel-art variant is meant
+     * @returns {boolean}
+     */
+    static has(path: string, pixelart?: boolean): boolean;
+    /**
+     * @method retain
+     * @description Increments the reference count for a cached texture. Every
+     * Drawable that resolves a texture through getTexture() retains it; when the
+     * last user releases it, the GL texture is freed. Call retain/release in
+     * pairs (Drawable.dispose does the release for you).
+     * @param {string} path - The texture path
+     * @param {boolean} pixelart - Whether the pixel-art variant is meant
+     */
+    static retain(path: string, pixelart?: boolean): void;
+    /**
+     * @method release
+     * @description Decrements a texture's reference count; when it reaches zero
+     * the GL texture is deleted and dropped from the cache (the CPU-side image
+     * cache is kept so a later reload is cheap).
+     * @param {string} path - The texture path
+     * @param {boolean} pixelart - Whether the pixel-art variant is meant
+     */
+    static release(path: string, pixelart?: boolean): void;
+    /**
+     * @method refCount
+     * @description Current reference count for a texture (0 if uncached).
+     * @returns {number}
+     */
+    static refCount(path: any, pixelart?: boolean): number;
+    /**
+     * @method clear
+     * @description Deletes all cached GL textures and clears the image cache.
+     * Useful when tearing down a context or freeing memory between levels.
+     */
+    static clear(): void;
+}
+declare namespace TextureManager {
+    let images: Map<any, any>;
+    let textures: Map<any, any>;
+    let refs: Map<any, any>;
+}

package/dist/types/src/particlesystem/Particle.d.ts

@@ -0,0 +1,64 @@
+export default Particle;
+/**
+ * @class Particle
+ * @description Represents a particle in the particle system
+ * @param {InstancedTexture} instancedTexture - The instanced texture
+ * @param {Vector3} position - The position of the particle
+ * @param {number} rotation - The rotation of the particle
+ * @param {Vector2} scale - The scale of the particle
+ * @param {ParticleSettings} settings - The settings for the particle
+ */
+declare class Particle {
+    /** @private */
+    private static _normColor;
+    constructor(instancedTexture: any, position: any, rotation: any, scale: any, settings: any, velocity: any);
+    /**
+     * @method reset
+     * @description (Re)initializes the particle. Used by the pool so particle
+     * objects can be reused without allocating. `velocity` overrides
+     * settings.velocity when provided (avoids a ParticleSettings allocation per
+     * particle).
+     */
+    reset(instancedTexture: any, position: any, rotation: any, scale: any, settings: any, velocity: any): void;
+    settings: any;
+    lifetime: any;
+    age: number;
+    velocity: {
+        x: any;
+        y: any;
+    };
+    gravity: {
+        x: any;
+        y: any;
+    };
+    instance: Instance;
+    /** @private */
+    private _baseScaleX;
+    /** @private */
+    private _baseScaleY;
+    /** @private */
+    private _colFrom;
+    /** @private */
+    private _colTo;
+    instancedTexture: any;
+    /** @private */
+    private _applyOverLife;
+    /**
+     * @method update
+     * @description Updates the particle
+     * @param {number} dt - The delta time
+     */
+    update(dt: number): void;
+    /**
+     * @method isAlive
+     * @description Checks if the particle is alive
+     * @returns {boolean} - True if the particle is alive
+     */
+    isAlive(): boolean;
+    /**
+     * @method destroy
+     * @description Destroys the particle
+     */
+    destroy(): void;
+}
+import Instance from "../Instance.js";