emeraldengine 2.2.1 → 3.0.0

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

@@ -0,0 +1,259 @@
+export default AudioManager;
+/**
+ * @class AudioManager
+ * @description Manages audio for the game with per-sound volume, looping,
+ * overlapping one-shot playback for sound effects, named mix buses
+ * (master / music / sfx and any custom bus) and volume fades / crossfades.
+ *
+ * Final playback volume for a sound is
+ * `masterVolume * busVolume(sound.bus) * sound.volume`, so an options menu can
+ * expose independent Music / SFX sliders that route through the buses.
+ *
+ * Fades are advanced by `update(dt)`. When `autoTick` is true (the default) and
+ * `requestAnimationFrame` exists, the manager drives its own fades and you do
+ * NOT need to call `update`. Pass `{ autoTick: false }` to advance fades
+ * manually (e.g. from your game loop or in tests).
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.autoTick=true] - Self-drive fades via requestAnimationFrame
+ */
+declare class AudioManager {
+    constructor(options?: {});
+    sounds: Map<any, any>;
+    masterVolume: number;
+    buses: Map<string, number>;
+    defaultBus: string;
+    listener: {
+        x: number;
+        y: number;
+    };
+    refDistance: number;
+    maxDistance: number;
+    /** @private */
+    private _audioCtx;
+    /** @private */
+    private _fades;
+    autoTick: boolean;
+    /** @private */
+    private _tickId;
+    /** @private */
+    private _lastTick;
+    /**
+     * @method getBusVolume
+     * @description Returns the 0..1 volume of a named bus (1 if it doesn't exist).
+     * @param {string} bus - The bus name (e.g. "music", "sfx")
+     * @returns {number}
+     */
+    getBusVolume(bus: string): number;
+    /**
+     * @method setBusVolume
+     * @description Sets the volume (0..1) of a named bus, creating it if needed,
+     * and applies it immediately to any currently-playing tracked sounds on it.
+     * @param {string} bus - The bus name
+     * @param {number} volume - The volume (clamped to 0..1)
+     */
+    setBusVolume(bus: string, volume: number): void;
+    /**
+     * @method setSoundBus
+     * @description Routes a registered sound through a named bus.
+     * @param {string} name - The registered sound name
+     * @param {string} bus - The bus name
+     */
+    setSoundBus(name: string, bus: string): void;
+    /**
+     * @method _busVolumeFor
+     * @description Combined master * bus multiplier for a sound (before fade/per-sound volume).
+     * @private
+     */
+    private _busVolumeFor;
+    /**
+     * @method _effectiveVolume
+     * @description Final 0..1 volume for a tracked sound element.
+     * @private
+     */
+    private _effectiveVolume;
+    /**
+     * @method _applyLiveVolumes
+     * @description Re-applies the effective volume to the primary element of
+     * tracked sounds (optionally filtered to one bus). Overlapping one-shots are
+     * fire-and-forget and not retargeted.
+     * @private
+     */
+    private _applyLiveVolumes;
+    /**
+     * @method setListener
+     * @description Sets the world-space listener position (usually the camera or
+     * player) used by playSpatial.
+     * @param {number} x
+     * @param {number} y
+     */
+    setListener(x: number, y: number): void;
+    /**
+     * @method setSpatialRange
+     * @description Configures the distance attenuation model for playSpatial.
+     * @param {number} refDistance - Distance within which volume is full
+     * @param {number} maxDistance - Distance at/after which the sound is silent
+     */
+    setSpatialRange(refDistance: number, maxDistance: number): void;
+    /**
+     * @method computeSpatial
+     * @description Pure helper: returns { volume, pan } for a source at `position`
+     * relative to the current listener and distance model. `volume` is 0..1 (before
+     * master/per-sound multipliers), `pan` is -1 (left) .. 1 (right). Exposed for
+     * testing and custom routing.
+     * @param {{x:number,y:number}} position
+     * @returns {{volume:number, pan:number, distance:number}}
+     */
+    computeSpatial(position: {
+        x: number;
+        y: number;
+    }): {
+        volume: number;
+        pan: number;
+        distance: number;
+    };
+    /**
+     * @method playSpatial
+     * @description Plays a one-shot, overlapping copy of a sound positioned in the
+     * world: volume falls off with distance from the listener and the sound pans
+     * left/right. Uses Web Audio for true stereo panning when available, falling
+     * back to volume-only otherwise.
+     * @param {string} name - The registered sound name
+     * @param {{x:number,y:number}} position - World-space source position
+     * @returns {boolean} - Whether playback started
+     */
+    playSpatial(name: string, position: {
+        x: number;
+        y: number;
+    }): boolean;
+    /** @private */
+    private _getAudioContext;
+    /**
+     * @method add
+     * @description Adds an audio file to the manager
+     * @param {string} path - The path to the audio file
+     * @param {string} name - The name of the audio file
+     * @param {Object} [options] - { volume = 1, loop = false, bus = "sfx" }
+     */
+    add(path: string, name: string, options?: any): boolean;
+    /**
+     * @method remove
+     * @description Removes an audio file from the manager
+     * @param {string} name - The name of the audio file
+     */
+    remove(name: string): boolean;
+    /**
+     * @method setMasterVolume
+     * @description Sets the master volume applied to all sounds (0..1)
+     * @param {number} volume - The master volume
+     */
+    setMasterVolume(volume: number): void;
+    /**
+     * @method setVolume
+     * @description Sets the per-sound volume (0..1)
+     * @param {string} name - The name of the audio file
+     * @param {number} volume - The volume
+     */
+    setVolume(name: string, volume: number): void;
+    /**
+     * @method setLoop
+     * @description Sets whether a sound loops
+     * @param {string} name - The name of the audio file
+     * @param {boolean} loop - Whether to loop
+     */
+    setLoop(name: string, loop: boolean): void;
+    /**
+     * @method play
+     * @description Plays an audio file from the start
+     * @param {string} name - The name of the audio file
+     */
+    play(name: string): Promise<boolean>;
+    /**
+     * @method playOverlap
+     * @description Plays a one-shot copy of the sound that can overlap with other
+     * instances of the same sound (ideal for rapid sound effects). The cloned
+     * node is not tracked or interruptible.
+     * @param {string} name - The name of the audio file
+     */
+    playOverlap(name: string): boolean;
+    /**
+     * @method stop
+     * @description Stops an audio file
+     * @param {string} name - The name of the audio file
+     */
+    stop(name: string): Promise<boolean>;
+    /**
+     * @method stopAll
+     * @description Stops all audio files
+     */
+    stopAll(): Promise<void>;
+    /**
+     * @method playExclusive
+     * @description Plays an audio file after stopping all other audio files
+     * @param {string} name - The name of the audio file
+     */
+    playExclusive(name: string): Promise<boolean>;
+    /**
+     * @method fadeTo
+     * @description Smoothly fades a sound's volume multiplier to a target (0..1)
+     * over `duration` seconds. Starting playback first (e.g. `play(name)`) and
+     * fading from 0 gives a fade-in; fading to 0 then stopping gives a fade-out.
+     * @param {string} name - The registered sound name
+     * @param {number} target - Target multiplier (0..1)
+     * @param {number} duration - Fade time in seconds (<=0 applies instantly)
+     * @param {Function} [onDone] - Called when the fade completes
+     * @returns {boolean} - Whether the sound exists
+     */
+    fadeTo(name: string, target: number, duration: number, onDone?: Function): boolean;
+    /**
+     * @method fadeIn
+     * @description Convenience: sets the fade multiplier to 0, starts playback and
+     * fades up to full over `duration` seconds.
+     * @param {string} name - The registered sound name
+     * @param {number} duration - Fade time in seconds
+     */
+    fadeIn(name: string, duration: number): boolean;
+    /**
+     * @method fadeOut
+     * @description Fades a sound down to silence over `duration` seconds, then
+     * stops it (and resets its fade multiplier to 1 for next time).
+     * @param {string} name - The registered sound name
+     * @param {number} duration - Fade time in seconds
+     */
+    fadeOut(name: string, duration: number): boolean;
+    /**
+     * @method crossfade
+     * @description Fades `fromName` out while fading `toName` in over `duration`
+     * seconds (ideal for switching music tracks). Starts `toName` playing.
+     * @param {string} fromName - Track to fade out (may be null)
+     * @param {string} toName - Track to fade in
+     * @param {number} duration - Fade time in seconds
+     */
+    crossfade(fromName: string, toName: string, duration: number): void;
+    /**
+     * @method _removeFadesFor
+     * @description Cancels any in-flight fades for a sound name.
+     * @private
+     */
+    private _removeFadesFor;
+    /**
+     * @method update
+     * @description Advances active volume fades by `dt` seconds. Call this from
+     * your loop when the manager was created with `{ autoTick: false }`; otherwise
+     * the manager advances fades itself.
+     * @param {number} dt - Elapsed seconds since the last update
+     */
+    update(dt: number): void;
+    /**
+     * @method _maybeStartTicker
+     * @description Lazily starts the self-driven RAF ticker (browser + autoTick).
+     * @private
+     */
+    private _maybeStartTicker;
+    /**
+     * @method getSound
+     * @description Returns an audio file from the manager
+     * @param {string} name - The name of the audio file
+     */
+    getSound(name: string): any;
+}

package/dist/types/{managers → src/managers}/CameraManager.d.ts

@@ -1,11 +1,9 @@
-import { Vector2 } from "../Physics";
+export default CameraManager;
 /**
  * @class CameraManager
  * @description Manages the camera for the game
  */
 declare class CameraManager {
-    static camera: any;
-    static lastPosition: Vector2 | null;
     /**
      * @method setLastPosition
      * @description Sets the last position of the camera
@@ -17,19 +15,21 @@ declare class CameraManager {
      * @description Returns the last position of the camera
      * @returns {Vector2} - The last position of the camera
      */
-    static getLastPosition(): Vector2 | null;
+    static getLastPosition(): Vector2;
     /**
      * @method setCamera
      * @description Sets the camera for the game
      * @param {Camera} camera - The camera to set
      */
-    static setCamera(camera: any): void;
+    static setCamera(camera: Camera): void;
     /**
      * @method getCamera
      * @description Returns the camera for the game
      * @returns {Camera} - The camera for the game
      */
-    static getCamera(): any | null;
+    static getCamera(): Camera;
+}
+declare namespace CameraManager {
+    let camera: any;
+    let lastPosition: any;
 }
-export default CameraManager;
-//# sourceMappingURL=CameraManager.d.ts.map

package/dist/types/{managers → src/managers}/EventManager.d.ts

@@ -1,6 +1,4 @@
-import Scene from "../Scene";
-import GameObject from "../components/GameObject";
-import Instance from "../Instance";
+export default EventManager;
 /**
  * @class EventManager
  * @description Manages the events for the game
@@ -9,38 +7,33 @@ import Instance from "../Instance";
  * @param {Camera} camera - The camera
  */
 declare class EventManager {
-    scene: Scene;
+    constructor(canvas: any, scene: any, camera: any);
+    scene: any;
     camera: any;
-    canvas: HTMLCanvasElement;
-    keyDownListeners: Map<string, Set<Function>>;
-    keyUpListeners: Map<string, Set<Function>>;
-    clickListeners: Map<string, Set<Function>>;
-    canvasWidth: number;
-    canvasHeight: number;
-    hoverListeners: Map<string, {
-        enter: Set<Function>;
-        leave: Set<Function>;
-    }>;
-    lastHoveredObject: GameObject | null;
-    lastHoveredInstance: Instance | null;
-    pressedKeys: Map<string, boolean>;
+    canvas: any;
+    keyDownListeners: Map<any, any>;
+    keyUpListeners: Map<any, any>;
+    clickListeners: Map<any, any>;
+    hoverListeners: Map<any, any>;
+    lastHoveredObject: any;
+    lastHoveredInstance: any;
+    pressedKeys: Map<any, any>;
     mousePosition: {
         x: number;
         y: number;
     };
+    boundHandleMouseMove: any;
+    boundHandleKeyDown: any;
+    boundHandleKeyUp: any;
+    boundHandleClick: any;
+    boundHandleMouseDown: any;
+    boundHandleMouseUp: any;
     isDragging: boolean;
     dragStartX: number;
     dragStartY: number;
-    initialCameraX: number;
-    initialCameraY: number;
+    initialCameraX: any;
+    initialCameraY: any;
     cameraWasMoved: boolean;
-    boundHandleMouseMove: (event: MouseEvent) => void;
-    boundHandleKeyDown: (event: KeyboardEvent) => void;
-    boundHandleKeyUp: (event: KeyboardEvent) => void;
-    boundHandleClick: (event: MouseEvent) => void;
-    boundHandleMouseDown: (event: MouseEvent) => void;
-    boundHandleMouseUp: (event: MouseEvent) => void;
-    constructor(canvas: HTMLCanvasElement, scene: Scene, camera: any);
     /**
      * @method addKeyDown
      * @description Adds a key down event listener
@@ -95,6 +88,31 @@ declare class EventManager {
      * @param {function} func - The function to call when the object is clicked
      */
     addClickEvent(object: GameObject, func: Function): void;
+    /**
+     * @method screenToWorld
+     * @description Converts screen (client) coordinates to world coordinates,
+     * accounting for camera position, zoom, and CSS/backing pixel ratio.
+     * @param {number} clientX - The clientX of the pointer
+     * @param {number} clientY - The clientY of the pointer
+     * @returns {{x: number, y: number}} - The world-space coordinates
+     */
+    screenToWorld(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * @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.
+     * @param {number} worldX - The world-space x coordinate
+     * @param {number} worldY - The world-space y coordinate
+     * @returns {{object: GameObject, instance: Instance|null}|null}
+     */
+    getTopObjectAt(worldX: number, worldY: number): {
+        object: GameObject;
+        instance: Instance | null;
+    } | null;
     /**
      * @method handleClick
      * @description Handles a click event
@@ -156,10 +174,7 @@ declare class EventManager {
      * @description Returns the mouse position
      * @returns {Object} - The mouse position
      */
-    getMousePosition(): {
-        x: number;
-        y: number;
-    };
+    getMousePosition(): any;
     /**
      * @method wasCameraMoved
      * @description Checks if the camera was moved
@@ -183,5 +198,4 @@ declare class EventManager {
      */
     clean(): void;
 }
-export default EventManager;
-//# sourceMappingURL=EventManager.d.ts.map
+import Scene from "../Scene.js";

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

@@ -0,0 +1,84 @@
+export default GLManager;
+/**
+ * @class GLManager
+ * @description Manages the WebGL context for the game
+ */
+declare class GLManager {
+    /**
+     * @method setGL
+     * @description Sets the WebGL context
+     * @param {WebGLRenderingContext} gl - The WebGL context
+     */
+    static setGL(gl: WebGLRenderingContext): void;
+    /**
+     * @method setProgramInfo
+     * @description Sets the program info
+     * @param {Object} programInfo - The program info
+     */
+    static setProgramInfo(programInfo: any): void;
+    /**
+     * @method setCanvas
+     * @description Sets the canvas
+     * @param {HTMLCanvasElement} canvas - The canvas
+     */
+    static setCanvas(canvas: HTMLCanvasElement): void;
+    /**
+     * @method getGL
+     * @description Returns the WebGL context
+     * @returns {WebGLRenderingContext} - The WebGL context
+     */
+    static getGL(): WebGLRenderingContext;
+    /**
+     * @method getProgramInfo
+     * @description Returns the program info
+     * @returns {Object} - The program info
+     */
+    static getProgramInfo(): any;
+    /**
+     * @method getCanvas
+     * @description Returns the canvas
+     * @returns {HTMLCanvasElement} - The canvas
+     */
+    static getCanvas(): HTMLCanvasElement;
+    /**
+     * @method registerRestorable
+     * @description Registers an object holding GL resources (buffers, textures,
+     * programs) for re-creation after a WebGL context loss. The object must
+     * implement `_restoreGL()`. Drawables register themselves automatically and
+     * unregister on dispose().
+     * @param {Object} obj - An object with a _restoreGL() method
+     */
+    static registerRestorable(obj: any): void;
+    /**
+     * @method unregisterRestorable
+     * @description Removes an object from the context-restore registry.
+     */
+    static unregisterRestorable(obj: any): void;
+    /**
+     * @method restoreAll
+     * @description Calls _restoreGL() on every registered object. Invoked by
+     * Emerald after the context is restored and the default shaders/textures
+     * have been rebuilt.
+     */
+    static restoreAll(): void;
+    /**
+     * @method setProjection
+     * @description Stores the current camera's projection matrix so custom
+     * Materials (which use their own shader program) can upload it.
+     * @param {Float32Array} matrix - The projection matrix
+     */
+    static setProjection(matrix: Float32Array): void;
+    /**
+     * @method getProjection
+     * @description Returns the last projection matrix set by the renderer.
+     * @returns {Float32Array}
+     */
+    static getProjection(): Float32Array;
+}
+declare namespace GLManager {
+    let gl: any;
+    let programInfo: any;
+    let canvas: any;
+    let projection: any;
+    let restorables: Set<any>;
+}

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

@@ -0,0 +1,37 @@
+export default GLState;
+/**
+ * @class GLState
+ * @description Tiny redundant-uniform filter. The renderer sets the same handful
+ * of per-object uniforms (useTexture, useInstances, useLighting, color, opacity)
+ * for every object every frame; most calls repeat the previous value. These
+ * helpers skip the GL call when the value is unchanged. Keyed by uniform
+ * location, which is program-specific, so the cache is safe across objects.
+ */
+declare class GLState {
+    /**
+     * @method reset
+     * @description Clears the cache. Called at the start of each frame so the
+     * first object always re-establishes state.
+     */
+    static reset(): void;
+    /**
+     * @method uniform1i
+     * @description Cached gl.uniform1i (accepts booleans, coerced like WebGL does).
+     */
+    static uniform1i(gl: any, location: any, value: any): void;
+    /**
+     * @method uniform1f
+     * @description Cached gl.uniform1f.
+     */
+    static uniform1f(gl: any, location: any, value: any): void;
+    /**
+     * @method uniform4fv
+     * @description Cached gl.uniform4fv (compares the four components).
+     */
+    static uniform4fv(gl: any, location: any, value: any): void;
+}
+declare namespace GLState {
+    let ints: Map<any, any>;
+    let floats: Map<any, any>;
+    let vec4s: Map<any, any>;
+}

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

@@ -0,0 +1,31 @@
+export default IDManager;
+/**
+ * @class IDManager
+ * @description Manages the IDs for the game
+ */
+declare class IDManager {
+    /**
+     * @method generateID
+     * @description Generates a random ID, preferring the collision-resistant
+     * crypto.randomUUID when available and falling back to a random string.
+     * @returns {string} - The random ID
+     */
+    static generateID(): string;
+    /**
+     * @method generateUniqueID
+     * @description Generates a unique ID
+     * @returns {string} - The unique ID
+     */
+    static generateUniqueID(): string;
+    /**
+     * @method release
+     * @description Releases a previously-generated ID so the global registry
+     * doesn't grow without bound. Call this when an object/instance is destroyed
+     * (e.g. particles removed from an InstancedTexture).
+     * @param {string} id - The ID to release
+     */
+    static release(id: string): void;
+}
+declare namespace IDManager {
+    let existingIDs: Set<any>;
+}