emeraldengine 2.2.1 → 3.1.0

package/dist/types/src/Coroutine.d.ts

@@ -0,0 +1,111 @@
+export default Coroutine;
+/**
+ * @class Coroutine
+ * @description Generator-based sequencing for time-based logic, layered on top of
+ * the same per-frame delta the rest of the engine uses. Write a generator that
+ * `yield`s instructions, and the runner advances it each frame:
+ *
+ *   - `yield seconds` (a number)        -> wait that many seconds
+ *   - `yield Coroutine.waitFrames(n)`   -> wait n frames
+ *   - `yield Coroutine.waitUntil(fn)`   -> wait until fn() is truthy
+ *   - `yield Coroutine.waitWhile(fn)`   -> wait while fn() is truthy
+ *   - `yield somePromise`               -> wait for the promise to resolve
+ *   - `yield anotherCoroutine`          -> wait for a nested coroutine to finish
+ *   - `yield Coroutine.tween(...)`      -> drive a value over time, then continue
+ *
+ * Coroutines are driven by `Coroutine.update(dt)` (called automatically from
+ * `Emerald.drawScene`, so they honor pause/slow-mo via Time.timeScale).
+ *
+ * @example
+ * Coroutine.start(function* () {
+ *   door.open();
+ *   yield 1.5;                       // wait 1.5s
+ *   yield Coroutine.waitUntil(() => player.isReady);
+ *   boss.spawn();
+ * });
+ */
+declare class Coroutine {
+    /**
+     * @method start
+     * @description Starts a coroutine from a generator function (or an existing
+     * generator/iterator). Returns a handle with `cancel()` and `done`.
+     * @param {GeneratorFunction|Generator} gen - The generator (function) to run
+     * @param {...*} args - Arguments forwarded to the generator function
+     * @returns {Object} - A handle: { cancel(), done, isRunning() }
+     */
+    static start(gen: GeneratorFunction | Generator, ...args: any[]): any;
+    /**
+     * @method waitFrames
+     * @description Yieldable that waits a number of frames.
+     * @param {number} count - Frames to wait
+     */
+    static waitFrames(count: number): {
+        __coroutine: string;
+        count: number;
+    };
+    /**
+     * @method waitUntil
+     * @description Yieldable that blocks until the predicate returns truthy.
+     * @param {Function} predicate
+     */
+    static waitUntil(predicate: Function): {
+        __coroutine: string;
+        predicate: Function;
+    };
+    /**
+     * @method waitWhile
+     * @description Yieldable that blocks while the predicate returns truthy.
+     * @param {Function} predicate
+     */
+    static waitWhile(predicate: Function): {
+        __coroutine: string;
+        predicate: () => boolean;
+    };
+    /**
+     * @method tween
+     * @description Yieldable that interpolates from `from` to `to` over `duration`
+     * seconds, calling `onUpdate(value)` each frame, then resumes the coroutine.
+     * @param {number} from
+     * @param {number} to
+     * @param {number} duration - Seconds
+     * @param {Function} onUpdate - Receives the current value each step
+     * @param {Function} [easing] - Optional easing t -> t
+     */
+    static tween(from: number, to: number, duration: number, onUpdate: Function, easing?: Function): {
+        __coroutine: string;
+        from: number;
+        to: number;
+        duration: number;
+        onUpdate: Function;
+        easing: Function;
+        elapsed: number;
+    };
+    /**
+     * @method update
+     * @description Advances all running coroutines by dt seconds. Driven by
+     * Emerald.drawScene.
+     * @param {number} dt - Seconds since the last frame (time-scaled)
+     */
+    static update(dt: number): void;
+    /**
+     * @method clearAll
+     * @description Cancels and removes every running coroutine.
+     */
+    static clearAll(): void;
+    /**
+     * @method count
+     * @returns {number} - Number of currently running coroutines
+     */
+    static count(): number;
+    /** @private */
+    private static _finish;
+    /** @private */
+    private static _step;
+    /** @private */
+    private static _advance;
+    /** @private */
+    private static _interpret;
+}
+declare namespace Coroutine {
+    let _routines: any[];
+}

package/dist/types/src/DebugOverlay.d.ts

@@ -0,0 +1,86 @@
+export default DebugOverlay;
+/**
+ * @class DebugOverlay
+ * @description A DOM panel that profiles the running game: FPS, frame-time stats
+ * with a live sparkline graph, object/camera counts, the primary camera's
+ * position/zoom, JS heap usage (where available), and any extra metrics you
+ * push. It can also toggle physics collider debug shapes on a scene.
+ *
+ * Call `update(emerald, scene)` each frame; toggle visibility with `setVisible`.
+ *
+ * @example
+ * const debug = new DebugOverlay();
+ * // each frame, after drawScene:
+ * debug.update(emerald, scene);
+ * debug.setMetric("draws", spriteBatch.drawCalls);
+ * debug.showColliders(scene, true); // visualize physics colliders
+ */
+declare class DebugOverlay {
+    constructor(options?: {});
+    element: HTMLDivElement;
+    /** @private */
+    private _graph;
+    /** @private */
+    private _gctx;
+    /** @private */
+    private _text;
+    /** @private */
+    private _last;
+    /** @private */
+    private _frames;
+    /** @private */
+    private _accum;
+    fps: number;
+    /** @private */
+    private _frameTimes;
+    /** @private */
+    private _maxSamples;
+    /** @private */
+    private _dtMs;
+    /** @private */
+    private _minMs;
+    /** @private */
+    private _maxMs;
+    /** @private */
+    private _avgMs;
+    /** @private */
+    private _metrics;
+    /** @private */
+    private _colliderScene;
+    /** @private */
+    private _collidersShown;
+    /**
+     * @method setMetric
+     * @description Adds/updates a custom metric line shown in the panel.
+     * @param {string} key
+     * @param {*} value
+     */
+    setMetric(key: string, value: any): void;
+    /**
+     * @method update
+     * @description Updates the overlay. Pass the engine and current scene.
+     * @param {Emerald} emerald
+     * @param {Scene} scene
+     */
+    update(emerald: Emerald, scene: Scene): void;
+    /** @private */
+    private _drawGraph;
+    /**
+     * @method showColliders
+     * @description Toggles physics collider debug shapes for every RigidBody in a
+     * scene's objects (uses the lazy debug shapes on each collider).
+     * @param {Scene} scene
+     * @param {boolean} show
+     */
+    showColliders(scene: Scene, show: boolean): void;
+    /**
+     * @method setVisible
+     * @param {boolean} visible
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * @method destroy
+     * @description Removes the overlay from the DOM.
+     */
+    destroy(): void;
+}

package/dist/types/src/Drawable.d.ts

@@ -0,0 +1,271 @@
+export default Drawable;
+/**
+ * @class Drawable
+ * @description A class that represents a drawable object
+ * @param {WebGLRenderingContext} gl - The WebGL rendering context
+ * @param {Object} programInfo - The program information
+ * @param {WebGLBuffer} verticesBuffer - The vertices buffer
+ * @param {WebGLBuffer} texCoordBuffer - The texture coordinate buffer
+ * @param {Array} vertices - The vertices of the object
+ * @param {boolean} useTexture - Whether to use a texture
+ * @param {string} texturePath - The path to the texture
+ * @param {number} frameWidth - The width of the frame
+ * @param {number} frameHeight - The height of the frame
+ * @param {number} framesPerRow - The number of frames per row
+ * @param {number} totalFrames - The total number of frames
+ * @param {number} animationSpeed - The speed of the animation
+ * @param {boolean} autoplay - Whether to autoplay the animation
+ * @param {boolean} pixelart - Whether to use pixel art
+ * @param {boolean} useLighting - Whether to use lighting
+ */
+declare class Drawable {
+    constructor(gl: any, programInfo: any, verticesBuffer: any, texCoordBuffer: any, vertices: any, useTexture: any, texturePath: any, frameWidth?: number, frameHeight?: number, framesPerRow?: number, totalFrames?: number, animationSpeed?: number, autoplay?: boolean, pixelart?: boolean, useLighting?: boolean);
+    gl: any;
+    programInfo: any;
+    id: string;
+    verticesBuffer: any;
+    texCoordBuffer: any;
+    vertices: any;
+    color: vec4;
+    texturePath: any;
+    texture: WebGLTexture;
+    useTexture: any;
+    pixelart: boolean;
+    /** @private */
+    private _disposed;
+    /** @private */
+    private _texRetained;
+    frameWidth: number;
+    frameHeight: number;
+    framesPerRow: number;
+    totalFrames: number;
+    currentFrame: number;
+    animationSpeed: number;
+    lastFrameTime: number;
+    textureWidth: number;
+    textureHeight: number;
+    isPlaying: boolean;
+    playOnce: boolean;
+    originalTexture: WebGLTexture;
+    mirrored: boolean;
+    flippedY: boolean;
+    /** @private */
+    private _pivotX;
+    /** @private */
+    private _pivotY;
+    /** @private */
+    private _hasPivot;
+    animationType: string;
+    currentAnimationArray: any[];
+    currentAnimationIndex: number;
+    shouldRevertAfterPlayingOnce: boolean;
+    revertAnimation: any[];
+    parentObject: any;
+    isActive: boolean;
+    isWireframe: boolean;
+    callbackFunction: () => void;
+    useLighting: boolean;
+    /** @private */
+    private _objectTransformMatrix;
+    /** @private */
+    private _finalTransformMatrix;
+    /** @private */
+    private _lastTexFrame;
+    /** @private */
+    private _lastMirrored;
+    /** @private */
+    private _lastFlippedY;
+    /** @private */
+    private _lastTextureWidth;
+    /** @private */
+    private _wireframeBuffer;
+    blendMode: string;
+    /** @private */
+    private _region;
+    /** @private */
+    private _lastRegion;
+    material: any;
+    /**
+     * @method _restoreGL
+     * @description Rebuilds this drawable's GPU resources after a WebGL
+     * context loss: vertex/texcoord buffers from their kept CPU copies, and a
+     * fresh texture pointer from the (re-uploaded) TextureManager cache.
+     * Called by GLManager.restoreAll(); not meant for manual use.
+     * @private
+     */
+    private _restoreGL;
+    /**
+     * @method setMaterial
+     * @description Assigns a custom Material (fragment shader) to this drawable,
+     * or pass null to revert to the standard shader.
+     * @param {Material|null} material
+     */
+    setMaterial(material: Material | null): void;
+    /**
+     * @method setBlendMode
+     * @description Sets the blend mode ("normal", "additive", "multiply").
+     * @param {string} mode - The blend mode
+     */
+    setBlendMode(mode: string): void;
+    /**
+     * @method setRegion
+     * @description Sets a normalized UV sub-rect (for atlas frames). Values are
+     * 0..1 with top-left origin. Pass nothing to clear.
+     */
+    setRegion(left: any, top: any, right: any, bottom: any): void;
+    /**
+     * @method setFlipX
+     * @description Horizontally mirrors the sprite (e.g. to face left/right)
+     * without touching the GameObject's scale.
+     * @param {boolean} flip
+     */
+    setFlipX(flip: boolean): void;
+    /**
+     * @method setFlipY
+     * @description Vertically mirrors the sprite.
+     * @param {boolean} flip
+     */
+    setFlipY(flip: boolean): void;
+    /**
+     * @method getFlipX
+     * @returns {boolean}
+     */
+    getFlipX(): boolean;
+    /**
+     * @method getFlipY
+     * @returns {boolean}
+     */
+    getFlipY(): boolean;
+    /**
+     * @method setPivot
+     * @description Sets the sprite's origin in normalized local space, where
+     * (0,0) is the center (default), x runs -1 (left) .. 1 (right) and y runs
+     * -1 (bottom) .. 1 (top). The chosen point is what sits on the GameObject's
+     * position and acts as the rotation/scale center. Call with no args to reset
+     * to centered.
+     * @param {number} [x=0]
+     * @param {number} [y=0]
+     */
+    setPivot(x?: number, y?: number): void;
+    /**
+     * @method setAnchor
+     * @description Convenience wrapper around setPivot using 0..1 anchor
+     * coordinates with a top-left origin (CSS-style): (0.5,0.5) = center,
+     * (0.5,1) = bottom-center, (0,0) = top-left.
+     * @param {number} [ax=0.5]
+     * @param {number} [ay=0.5]
+     */
+    setAnchor(ax?: number, ay?: number): void;
+    /** @private */
+    private _applyBlend;
+    /** @private */
+    private _restoreBlend;
+    /**
+     * @method setIsWireframe
+     * @description Sets the wireframe mode
+     * @param {boolean} bool - Whether to enable wireframe mode
+     */
+    setIsWireframe(bool: boolean): void;
+    /**
+     * @method setUseLighting
+     * @description Sets the lighting mode
+     * @param {boolean} useLighting - Whether to enable lighting reaction
+     */
+    setUseLighting(useLighting: boolean): void;
+    /**
+     * @method setIsActive
+     * @description Sets the active state
+     * @param {boolean} bool - Whether to enable the active state
+     */
+    setIsActive(bool: boolean): void;
+    /**
+     * @method setParent
+     * @description Sets the parent object
+     * @param {Object} parent - The parent object
+     */
+    setParent(parent: any): void;
+    /**
+     * @method getParent
+     * @description Gets the parent object
+     * @returns {Object} - The parent object
+     */
+    getParent(): any;
+    /**
+     * @method setColor
+     * @description Sets the color of the object
+     * @param {Color} color - The color to set
+     */
+    setColor(color: Color): void;
+    /**
+     * @method initTexture
+     * @description Initializes the texture
+     */
+    initTexture(): Promise<void>;
+    /**
+     * @method dispose
+     * @description Frees this drawable's GPU resources: its vertex/texcoord
+     * buffers and its reference on the shared texture (the GL texture itself is
+     * deleted when the last drawable using it is disposed). Call it when the
+     * owning object is permanently removed. GameObject.destroy() and
+     * Scene.remove(obj, { dispose: true }) do it for you. Safe to call twice.
+     */
+    dispose(): void;
+    /**
+     * @method updateAnimation
+     * @description Updates the animation
+     * @param {number} currentTime - The current time
+     */
+    updateAnimation(currentTime: number): void;
+    /**
+     * @method getAnimation
+     * @description Gets the animation
+     * @returns {Array} - The animation
+     */
+    getAnimation(): any[];
+    /**
+     * @method playAnimation
+     * @description Plays an animation
+     * @param {Array} animation - The animation to play
+     * @param {number} animationSpeed - The speed of the animation
+     */
+    playAnimation(animation: any[], animationSpeed?: number): void;
+    /**
+     * @method setFrame
+     * @description Sets the frame
+     * @param {number} frame - The frame to set
+     */
+    setFrame(frame: number): void;
+    /**
+     * @method playAnimationOnce
+     * @description Plays an animation once
+     * @param {Array} animation - The animation to play
+     * @param {Array} defaultAnimation - The default animation
+     * @param {number} animationSpeed - The speed of the animation
+     * @param {function} callbackFunction - The callback function
+     */
+    playAnimationOnce(animation: any[], defaultAnimation?: any[], animationSpeed?: number, callbackFunction?: Function): void;
+    /**
+     * @method stopAnimation
+     * @description Stops the animation
+     */
+    stopAnimation(): void;
+    /**
+     * @method draw
+     * @description Draws the object
+     * @param {mat4} globalViewMatrix - The global view matrix
+     * @param {WebGLUniformLocation} uniformLocation - The uniform location
+     * @param {number} currentTime - The current time
+     * @param {Object} objectTransform - The object transform
+     */
+    draw(globalViewMatrix: mat4, uniformLocation: WebGLUniformLocation, currentTime: number, objectTransform: any): void;
+    /**
+     * @method loadImage
+     * @description Loads an image
+     * @param {string} path - The path to the image
+     * @returns {Promise} - The promise
+     */
+    loadImage(path: string): Promise<any>;
+}
+import { vec4 } from "gl-matrix";
+import Color from "./Color.js";
+import { mat4 } from "gl-matrix";

package/dist/types/src/Easing.d.ts

@@ -0,0 +1,22 @@
+export default Easing;
+declare namespace Easing {
+    function linear(t: any): any;
+    function inQuad(t: any): number;
+    function outQuad(t: any): number;
+    function inOutQuad(t: any): number;
+    function inCubic(t: any): number;
+    function outCubic(t: any): number;
+    function inOutCubic(t: any): number;
+    function inQuart(t: any): number;
+    function outQuart(t: any): number;
+    function inOutQuart(t: any): number;
+    function inSine(t: any): number;
+    function outSine(t: any): number;
+    function inOutSine(t: any): number;
+    function inExpo(t: any): number;
+    function outExpo(t: any): number;
+    function inBack(t: any): number;
+    function outBack(t: any): number;
+    function outElastic(t: any): number;
+    function outBounce(t: any): number;
+}