emeraldengine 2.2.1 → 3.1.0

package/dist/types/{lights → src/lights}/DirectionalLight.d.ts

@@ -1,5 +1,4 @@
-import Color from "../Color";
-import { Vector2 } from "../Physics";
+export default DirectionalLight;
 /**
  * @class DirectionalLight
  * @param {Vector2} position - The position of the light
@@ -9,12 +8,12 @@ import { Vector2 } from "../Physics";
  * @param {number} width - The width of the light
  */
 declare class DirectionalLight {
-    position: Vector2;
+    constructor(position: any, direction: any, color: any, intensity: any, width: any);
+    position: any;
     direction: Vector2;
-    color: Color;
-    intensity: number;
-    width: number;
-    constructor(position: Vector2, direction: Vector2, color: Color, intensity: number, width: number);
+    color: any;
+    intensity: any;
+    width: any;
     /**
      * Calculate the light intensity at a given point
      * @param {Vector2} point - The point to calculate intensity for
@@ -22,5 +21,4 @@ declare class DirectionalLight {
      */
     getIntensityAtPoint(point: Vector2): number;
 }
-export default DirectionalLight;
-//# sourceMappingURL=DirectionalLight.d.ts.map
+import { Vector2 } from "../Physics.js";

package/dist/types/{lights → src/lights}/PointLight.d.ts

@@ -1,5 +1,4 @@
-import Color from "../Color";
-import { Vector2 } from "../Physics";
+export default PointLight;
 /**
  * @class PointLight
  * @param {Vector2} position - The position of the light
@@ -8,11 +7,9 @@ import { Vector2 } from "../Physics";
  * @param {number} radius - The radius of the light
  */
 declare class PointLight {
-    position: Vector2;
-    color: Color;
-    intensity: number;
-    radius: number;
-    constructor(position: Vector2, color: Color, intensity: number, radius: number);
+    constructor(position: any, color: any, intensity: any, radius: any);
+    position: any;
+    color: any;
+    intensity: any;
+    radius: any;
 }
-export default PointLight;
-//# sourceMappingURL=PointLight.d.ts.map

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

@@ -0,0 +1,116 @@
+export default AssetManager;
+/**
+ * @class AssetManager
+ * @description A general async loader for everything a game needs at startup:
+ * images/textures, audio, JSON, text, and web fonts. It deduplicates by key,
+ * reports aggregate progress (so you can drive a loading bar), and stores the
+ * resolved assets for synchronous lookup afterwards via `get(key)`.
+ *
+ * Textures are routed through TextureManager so the GL upload cache is shared
+ * with the rest of the engine.
+ *
+ * @example
+ * const assets = new AssetManager();
+ * assets.image("player", "player.png", { pixelart: true });
+ * assets.audio("jump", "jump.wav");
+ * assets.json("level1", "levels/1.json");
+ * assets.font("Press Start 2P", "fonts/press-start.woff2");
+ * assets.onProgress((loaded, total) => bar.set(loaded / total));
+ * await assets.load();
+ * const img = assets.get("player");      // HTMLImageElement
+ * const data = assets.get("level1");     // parsed JSON
+ */
+declare class AssetManager {
+    /** @private */
+    private static _loadAudio;
+    /** @private */
+    private static _loadFont;
+    /** @private */
+    private _queue;
+    assets: Map<any, any>;
+    /** @private */
+    private _paths;
+    /** @private */
+    private _progressHandlers;
+    /** @private */
+    private _loaded;
+    /** @private */
+    private _total;
+    /**
+     * @method image
+     * @description Queues an image/texture. The GL texture is created lazily by
+     * the renderer; `get(key)` returns the HTMLImageElement.
+     */
+    image(key: any, path: any, options?: {}): this;
+    /**
+     * @method audio
+     * @description Queues an audio file (returns an HTMLAudioElement on get()).
+     */
+    audio(key: any, path: any): this;
+    /**
+     * @method json
+     * @description Queues a JSON file (parsed on get()).
+     */
+    json(key: any, path: any): this;
+    /**
+     * @method text
+     * @description Queues a plain-text file.
+     */
+    text(key: any, path: any): this;
+    /**
+     * @method font
+     * @description Queues a web font. `key` is the font-family name you will use
+     * in CSS/canvas; `path` is the font file URL.
+     */
+    font(key: any, path: any, descriptors?: {}): this;
+    /**
+     * @method onProgress
+     * @description Registers a callback invoked as (loaded, total) after each
+     * asset resolves.
+     */
+    onProgress(handler: any): this;
+    /**
+     * @method progress
+     * @returns {number} - Fraction loaded in [0, 1] (1 when nothing is queued).
+     */
+    progress(): number;
+    /**
+     * @method load
+     * @description Loads every queued asset, resolving when all are done. Failed
+     * assets reject the returned promise unless `continueOnError` is true, in
+     * which case they resolve to null and loading continues.
+     * @param {Object} [options] - { continueOnError = false }
+     * @returns {Promise<Map>} - The resolved assets map
+     */
+    load(options?: any): Promise<Map<any, any>>;
+    /** @private */
+    private _loadOne;
+    /**
+     * @method get
+     * @description Returns a previously loaded asset by key.
+     */
+    get(key: any): any;
+    /**
+     * @method has
+     * @returns {boolean} - Whether an asset has been loaded for the key.
+     */
+    has(key: any): boolean;
+    /**
+     * @method getTexture
+     * @description Convenience: returns the cached GL texture for an image asset
+     * that was queued with `image()`. Resolves once the upload completes.
+     * @param {string} key - The image asset key
+     * @returns {Promise<{texture: WebGLTexture, width: number, height: number}>}
+     */
+    getTexture(key: string): Promise<{
+        texture: WebGLTexture;
+        width: number;
+        height: number;
+    }>;
+    /**
+     * @method clear
+     * @description Forgets all loaded assets (does not free GL textures; use
+     * TextureManager.clear for that).
+     */
+    clear(): void;
+}

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>;
+}