emeraldengine 2.2.1 → 3.1.0

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

@@ -0,0 +1,91 @@
+export default Tilemap;
+/**
+ * @class Tilemap
+ * @description Builds a grid of tiles from a 2D array of frame indices, rendered
+ * as a single instanced draw call. Use -1 (or null) for empty cells. The tiles
+ * live on `tilemap.gameObject`, which you add to the scene.
+ *
+ * @example
+ * const map = new Tilemap("level", "tiles.png", {
+ *   tileSize: 32, frameWidth: 16, frameHeight: 16, framesPerRow: 4, totalFrames: 16,
+ * });
+ * map.setMap([
+ *   [0, 0, 0, 0],
+ *   [1, -1, -1, 1],
+ *   [2, 2, 2, 2],
+ * ]);
+ * scene.add(map.gameObject);
+ */
+declare class Tilemap {
+    /**
+     * @method computeAutoTile
+     * @description Pure helper that converts a 2D solidity grid into a 2D frame
+     * index grid using 4-bit edge bitmasking. For each solid cell the neighbor
+     * mask is built as up|right|down|left (bits 1,2,4,8); empty cells become -1.
+     * Provide `frames` (a length-16 lookup from mask -> frame index) to match your
+     * tilesheet layout; otherwise the mask itself is used as the frame index, and
+     * `base` is added to every solid frame.
+     *
+     * @param {Array<Array<boolean|number>>} grid - Truthy = solid
+     * @param {Object} [options] - { frames, base = 0, edgesSolid = true }
+     * @returns {number[][]} - Frame indices (-1 for empty)
+     */
+    static computeAutoTile(grid: Array<Array<boolean | number>>, options?: any): number[][];
+    /**
+     * @param {string} name - Name for the underlying GameObject
+     * @param {string} texturePath - Path to the tile sheet
+     * @param {Object} [options] - tileSize, frameWidth, frameHeight, framesPerRow, totalFrames, pixelart
+     */
+    constructor(name: string, texturePath: string, options?: any);
+    name: string;
+    tileSize: any;
+    /** @private */
+    private _config;
+    gameObject: GameObject;
+    texture: InstancedTexture;
+    /** @private */
+    private _map;
+    /** @private */
+    private _layout;
+    /** @private */
+    private _colliders;
+    /**
+     * @method setMap
+     * @description Builds (or rebuilds) the tile instances from a 2D array.
+     * @param {number[][]} map - Rows of frame indices (-1/null = empty)
+     * @param {Object} [options] - { originX = 0, originY = 0, flipY = true }
+     * @returns {Tilemap} - this
+     */
+    setMap(map: number[][], options?: any): Tilemap;
+    /**
+     * @method buildColliders
+     * @description Generates static physics colliders from the current map. Solid
+     * cells are merged greedily into horizontal runs, so a row of N tiles becomes
+     * one box collider instead of N, far fewer bodies for the physics engine.
+     * The bodies are tagged so collision callbacks resolve back to `ownerObject`
+     * (defaults to the tilemap's GameObject). Call again after setMap to rebuild.
+     *
+     * @param {Physics} physics - The physics engine
+     * @param {Object} [options] - { isSolid, friction = 0.2, restitution = 0,
+     *   density = 0, ownerObject }
+     * @returns {Tilemap} - this
+     */
+    buildColliders(physics: Physics, options?: any): Tilemap;
+    /**
+     * @method clearColliders
+     * @description Destroys the physics bodies created by buildColliders.
+     * @returns {Tilemap} - this
+     */
+    clearColliders(): Tilemap;
+    /**
+     * @method setAutoTiledMap
+     * @description Convenience: computes frame indices from a solidity grid using
+     * bitmask auto-tiling, then builds the map. See Tilemap.computeAutoTile.
+     * @param {Array<Array<boolean|number>>} solidGrid - Truthy = solid cell
+     * @param {Object} [options] - Auto-tile options + setMap options
+     * @returns {Tilemap} - this
+     */
+    setAutoTiledMap(solidGrid: Array<Array<boolean | number>>, options?: any): Tilemap;
+}
+import GameObject from "./components/GameObject.js";
+import InstancedTexture from "./InstancedTexture.js";

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

@@ -0,0 +1,53 @@
+export default Time;
+/**
+ * @class Time
+ * @description Global time state for the game. `deltaTime` is the (scaled)
+ * seconds since the last frame, `elapsedTime` accumulates total scaled time, and
+ * `timeScale` lets you slow down / speed up / pause the simulation.
+ */
+declare class Time {
+    /**
+     * @method getDeltaTime
+     * @description Returns the (time-scaled) delta time in seconds
+     * @returns {number} - The delta time
+     */
+    static getDeltaTime(): number;
+    /**
+     * @method setDeltaTime
+     * @description Sets the delta time. The stored value is multiplied by
+     * `timeScale`, and `elapsedTime` is advanced by the scaled amount. Called by
+     * `Emerald.drawScene`, but can be called manually for custom loops.
+     * @param {number} deltaTime - The unscaled delta time in seconds
+     */
+    static setDeltaTime(deltaTime: number): void;
+    /**
+     * @method getUnscaledDeltaTime
+     * @description Returns the raw delta time, ignoring timeScale
+     * @returns {number} - The unscaled delta time
+     */
+    static getUnscaledDeltaTime(): number;
+    /**
+     * @method getElapsedTime
+     * @description Returns the total accumulated (scaled) time in seconds
+     * @returns {number} - The elapsed time
+     */
+    static getElapsedTime(): number;
+    /**
+     * @method setTimeScale
+     * @description Sets the time scale (1 = normal, 0 = paused, 2 = double speed)
+     * @param {number} scale - The time scale (clamped to >= 0)
+     */
+    static setTimeScale(scale: number): void;
+    /**
+     * @method getTimeScale
+     * @description Returns the current time scale
+     * @returns {number} - The time scale
+     */
+    static getTimeScale(): number;
+}
+declare namespace Time {
+    let deltaTime: number;
+    let unscaledDeltaTime: number;
+    let elapsedTime: number;
+    let timeScale: number;
+}

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

@@ -0,0 +1,54 @@
+export default Timer;
+/**
+ * @class Timer
+ * @description Schedules delayed and repeating callbacks measured in seconds.
+ * Driven by `Emerald.drawScene` with time-scaled delta, so timers honor
+ * pause/slow-mo. Each scheduler call returns a handle you can pass to `clear`.
+ *
+ * @example
+ * Timer.after(2, () => spawnEnemy());        // once, after 2s
+ * Timer.every(0.5, () => tick(), 10);        // 10 times, every 0.5s
+ * const h = Timer.every(1, () => poll());    // forever until cleared
+ * Timer.clear(h);
+ */
+declare class Timer {
+    /**
+     * @method after
+     * @description Runs a callback once after a delay.
+     * @param {number} seconds - Delay in seconds
+     * @param {Function} callback
+     * @returns {Object} - A handle for clear()
+     */
+    static after(seconds: number, callback: Function): any;
+    /**
+     * @method every
+     * @description Runs a callback repeatedly on an interval.
+     * @param {number} seconds - Interval in seconds
+     * @param {Function} callback
+     * @param {number} [repeats] - Number of repeats (default Infinity)
+     * @returns {Object} - A handle for clear()
+     */
+    static every(seconds: number, callback: Function, repeats?: number): any;
+    /** @private */
+    private static _add;
+    /**
+     * @method clear
+     * @description Cancels a scheduled timer by its handle.
+     * @param {Object} handle - The handle returned by after/every
+     */
+    static clear(handle: any): void;
+    /**
+     * @method clearAll
+     * @description Cancels all timers.
+     */
+    static clearAll(): void;
+    /**
+     * @method update
+     * @description Advances all timers. Driven by Emerald.drawScene.
+     * @param {number} dt - Seconds since the last frame
+     */
+    static update(dt: number): void;
+}
+declare namespace Timer {
+    let entries: any[];
+}

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

@@ -0,0 +1,94 @@
+export default Transform;
+/**
+ * @class Transform
+ * @description Represents a transform with optional parent/child hierarchy.
+ * Local position/rotation/scale are composed up the parent chain to produce a
+ * world transform. Objects with no parent behave exactly as before (the world
+ * transform is the local transform), so existing code is unaffected.
+ * @param {Vector3} position - The local position
+ * @param {number} rotation - The local rotation (radians)
+ * @param {Vector2} scale - The local scale
+ */
+declare class Transform {
+    constructor(position: any, rotation: any, scale: any);
+    position: any;
+    rotation: any;
+    scale: any;
+    parent: any;
+    children: any[];
+    /** @private */
+    private _world;
+    /**
+     * @method setParent
+     * @description Sets (or clears) the parent transform, maintaining the
+     * children list on both sides.
+     * @param {Transform|null} parent - The parent transform, or null to detach
+     */
+    setParent(parent: Transform | null): void;
+    /**
+     * @method getWorldParts
+     * @description Returns the composed world TRS as primitives. Composition is
+     * standard 2D: child local space is scaled and rotated by the parent.
+     * @returns {{px:number, py:number, pz:number, rot:number, sx:number, sy:number}}
+     */
+    getWorldParts(): {
+        px: number;
+        py: number;
+        pz: number;
+        rot: number;
+        sx: number;
+        sy: number;
+    };
+    /**
+     * @method getWorldTransform
+     * @description Returns a transform-shaped object ({position, rotation, scale})
+     * in world space. The returned object is reused between calls.
+     * @returns {{position:{x,y,z}, rotation:number, scale:{x,y}}}
+     */
+    getWorldTransform(): {
+        position: {
+            x: any;
+            y: any;
+            z: any;
+        };
+        rotation: number;
+        scale: {
+            x: any;
+            y: any;
+        };
+    };
+    /**
+     * @method getWorldPosition
+     * @description Returns the world-space position as a plain { x, y, z }.
+     */
+    getWorldPosition(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * @method equals
+     * @description Checks if the transform is equal to another transform
+     * @param {Transform} other - The other transform
+     * @returns {boolean} - True if the transform is equal to the other transform
+     */
+    equals(other: Transform): boolean;
+    /**
+     * @method getPosition
+     * @description Returns the local position of the transform
+     * @returns {Vector3} - The position of the transform
+     */
+    getPosition(): Vector3;
+    /**
+     * @method getRotation
+     * @description Returns the local rotation of the transform
+     * @returns {number} - The rotation of the transform
+     */
+    getRotation(): number;
+    /**
+     * @method getScale
+     * @description Returns the local scale of the transform
+     * @returns {Vector2} - The scale of the transform
+     */
+    getScale(): Vector2;
+}

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

@@ -0,0 +1,81 @@
+export default Tween;
+/**
+ * @class Tween
+ * @description Animates numeric properties of a target object over time with
+ * easing. Tweens created via `Tween.to(...)` are auto-registered and advanced
+ * by `Emerald.drawScene` (using time-scaled delta), so they respect pause/slow-mo.
+ *
+ * @example
+ * Tween.to(sprite.transform.position, { x: 200, y: -50 }, 0.6, {
+ *   easing: Easing.outBack,
+ *   onComplete: () => console.log("done"),
+ * });
+ */
+declare class Tween {
+    /**
+     * @param {Object} target - The object whose numeric keys will be animated
+     * @param {Object} props - Map of key -> end value
+     * @param {number} duration - Duration in seconds
+     * @param {Object} [options] - { easing, delay, loop, yoyo, onUpdate, onComplete }
+     */
+    constructor(target: any, props: any, duration: number, options?: any);
+    target: any;
+    props: any;
+    duration: number;
+    easing: any;
+    delay: any;
+    loop: boolean;
+    yoyo: boolean;
+    onUpdate: any;
+    onComplete: any;
+    elapsed: number;
+    started: boolean;
+    done: boolean;
+    from: {};
+    /** @private */
+    private _begin;
+    /**
+     * @method update
+     * @description Advances the tween. Returns false when finished.
+     * @param {number} dt - Seconds since the last update
+     * @returns {boolean} - Whether the tween is still active
+     */
+    update(dt: number): boolean;
+    /**
+     * @method then
+     * @description Chains a callback to run when the tween completes.
+     * @param {Function} callback
+     * @returns {Tween} - this
+     */
+    then(callback: Function): Tween;
+    /**
+     * @method stop
+     * @description Stops the tween immediately (without firing onComplete).
+     */
+    stop(): void;
+}
+declare namespace Tween {
+    let active: any[];
+    /**
+     * @method Tween.to
+     * @description Creates and registers a tween.
+     * @returns {Tween}
+     */
+    function to(target: any, props: any, duration: any, options: any): Tween;
+    /**
+     * @method Tween.update
+     * @description Advances all active tweens. Driven by Emerald.drawScene.
+     * @param {number} dt - Seconds since the last frame
+     */
+    function update(dt: number): void;
+    /**
+     * @method Tween.killOf
+     * @description Removes all tweens targeting the given object.
+     */
+    function killOf(target: any): void;
+    /**
+     * @method Tween.killAll
+     * @description Removes every active tween.
+     */
+    function killAll(): void;
+}

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

@@ -0,0 +1,121 @@
+export default UI;
+/**
+ * @class UI
+ * @description A small retained-mode UI toolkit rendered entirely with the
+ * engine (no DOM/HTML overlay): panels, labels, buttons and text fields, drawn
+ * as screen-space objects on a dedicated layer with their own pointer/keyboard
+ * hit-testing. Positions are in pixels from the viewport center (y up), or a
+ * `(viewW, viewH) => ({x, y})` function for responsive anchoring; call
+ * `relayout()` on resize.
+ *
+ * Pair it with a UI camera (see {@link UI.createCamera}) so the UI draws over
+ * the game and the game cameras ignore the UI layer.
+ *
+ * @example
+ * const uiCam = UI.createCamera();           // onlyLayers = [UI layer]
+ * gameCamera.ignoreLayer(UI.LAYER);
+ * emerald.setCameras([gameCamera, uiCam]);
+ *
+ * const ui = new UI(scene, canvas);
+ * ui.label(() => ({ x: 0, y: 200 }), "PAUSED", { font: "700 48px sans-serif" });
+ * ui.button(() => ({ x: 0, y: 0 }), "Resume", 220, 56, { onClick: resume });
+ * // in the loop: ui.relayout() on resize; remove input via ui.destroy().
+ */
+declare class UI {
+    /**
+     * @method createCamera
+     * @description Returns a full-screen camera that renders only the UI layer,
+     * so UI draws over the game. Add it last in setCameras.
+     * @param {number} [layer] - The UI layer (defaults to UI.LAYER)
+     * @returns {Camera}
+     */
+    static createCamera(layer?: number): Camera;
+    /**
+     * @param {Scene} scene - Scene to add UI objects to
+     * @param {HTMLCanvasElement} canvas - Canvas for pointer coordinates
+     * @param {Object} [options] - { layer = UI.LAYER, accent = [110,180,255] }
+     */
+    constructor(scene: Scene, canvas: HTMLCanvasElement, options?: any);
+    scene: Scene;
+    canvas: HTMLCanvasElement;
+    layer: any;
+    accent: any;
+    elements: any[];
+    focused: any;
+    /** @private */
+    private _hover;
+    /** @private */
+    private _onMove;
+    /** @private */
+    private _onDown;
+    /** @private */
+    private _onKey;
+    /** @private */
+    private _resolvePos;
+    /**
+     * @method relayout
+     * @description Recomputes positions of all elements (call after a resize).
+     */
+    relayout(): void;
+    /**
+     * @method panel
+     * @description Adds a rectangular panel.
+     * @returns {Object} - Element handle
+     */
+    panel(pos: any, width: any, height: any, options?: {}): any;
+    /**
+     * @method dim
+     * @description Adds a full-screen dimmer (modal backdrop).
+     * @returns {Object} - Element handle
+     */
+    dim(opacity?: number): any;
+    /**
+     * @method label
+     * @description Adds a text label.
+     * @returns {Object} - Element handle with setText(text)
+     */
+    label(pos: any, text: any, options?: {}): any;
+    /**
+     * @method button
+     * @description Adds an interactive button (panel + centered label).
+     * @param {Object} [options] - { onClick, accent, font, color }
+     * @returns {Object} - Element handle with setText(text), setEnabled(bool)
+     */
+    button(pos: any, text: any, width: any, height: any, options?: any): any;
+    /**
+     * @method textField
+     * @description Adds an editable single-line text field.
+     * @param {Object} [options] - { value, placeholder, onChange, maxLength, font }
+     * @returns {Object} - Element handle with getValue()/setValue(text)
+     */
+    textField(pos: any, width: any, height: any, options?: any): any;
+    /** @private */
+    private _makeQuad;
+    /** @private */
+    private _register;
+    /** @private */
+    private _toScreen;
+    /** @private */
+    private _hitTest;
+    /**
+     * @method isOver
+     * @description Whether an interactive element is under the given page point,
+     * useful to suppress game clicks behind the UI.
+     */
+    isOver(clientX: any, clientY: any): boolean;
+    /** @private */
+    private _handleMove;
+    /** @private */
+    private _handleDown;
+    /** @private */
+    private _handleKey;
+    /**
+     * @method destroy
+     * @description Removes all UI objects and detaches input listeners.
+     */
+    destroy(): void;
+}
+declare namespace UI {
+    let LAYER: number;
+}
+import Camera from "./Camera.js";

package/dist/types/src/components/Behaviour.d.ts

@@ -0,0 +1,71 @@
+export default Behaviour;
+/**
+ * @class Behaviour
+ * @description Base class for custom per-object game logic. Subclass it and
+ * override `start()` (called once, the first update after being added) and
+ * `update(deltaTime)` (called every frame the owner is active). Add it to a
+ * GameObject like any other component; it is ticked by `Scene.update(dt)` via
+ * `GameObject.update(dt)`.
+ *
+ * @example
+ * class Spinner extends Behaviour {
+ *   start() { this.speed = 2; }
+ *   update(dt) { this.gameObject.transform.rotation += this.speed * dt; }
+ * }
+ * obj.addComponent(new Spinner());
+ */
+declare class Behaviour {
+    id: string;
+    parentObject: any;
+    enabled: boolean;
+    /** @private */
+    private _started;
+    /**
+     * @member gameObject
+     * @description Convenience accessor for the owning GameObject.
+     */
+    get gameObject(): any;
+    /**
+     * @method setParent
+     * @description Sets the owning object. Called automatically by addComponent.
+     * @param {Object} parent - The owning GameObject (or Instance)
+     */
+    setParent(parent: any): void;
+    /**
+     * @method getParent
+     * @description Returns the owning object
+     * @returns {Object} - The owning object
+     */
+    getParent(): any;
+    /**
+     * @method start
+     * @description Called once before the first update. Override in subclasses.
+     */
+    start(): void;
+    /**
+     * @method update
+     * @description Called every active frame. Override in subclasses.
+     * @param {number} deltaTime - Seconds since the previous frame (time-scaled)
+     */
+    update(deltaTime: number): void;
+    /**
+     * @method onDestroy
+     * @description Called when the behaviour is removed. Override for cleanup.
+     */
+    onDestroy(): void;
+    /**
+     * @method onCollisionEnter
+     * @description Called when the owner's body starts touching another. Requires
+     * the Physics world to be ticked. Override in subclasses.
+     * @param {Object} other - The other GameObject/Instance (or null)
+     * @param {Object} contact - The physics contact
+     */
+    onCollisionEnter(other: any, contact: any): void;
+    /**
+     * @method onCollisionExit
+     * @description Called when the owner's body stops touching another.
+     * @param {Object} other - The other GameObject/Instance (or null)
+     * @param {Object} contact - The physics contact
+     */
+    onCollisionExit(other: any, contact: any): void;
+}

package/dist/types/{components → src/components}/BoxCollider.d.ts

@@ -1,9 +1,4 @@
-import * as planck from "planck";
-import BoxColliderDebug from "./BoxColliderDebug";
-import Collider from "./Collider";
-import { Vector2 } from "../Physics";
-import RigidBody from "./RigidBody";
-import GameObject from "./GameObject";
+export default BoxCollider;
 /**
  * @class BoxCollider
  * @extends Collider
@@ -16,11 +11,16 @@ import GameObject from "./GameObject";
  * @param {GameObject} parentObject - The parent object of the collider
  */
 declare class BoxCollider extends Collider {
-    collider: planck.Fixture;
-    fixtureSize: Vector2;
-    name: string;
-    debugShape: BoxColliderDebug;
-    constructor(rigidbody: RigidBody, fixtureSize: Vector2, density: number, friction: number, restitution: number, isSensor?: boolean, parentObject?: GameObject | null);
+    constructor(rigidbody: any, fixtureSize: any, density: any, friction: any, restitution: any, isSensor?: boolean, parentObject?: any, filter?: any);
+    collider: any;
+    fixtureSize: any;
+    /**
+     * @method debugShape
+     * @description Lazily builds the debug visualization on first access, so a
+     * collider stays free of any GameObject/GL allocation until it is debugged.
+     * @returns {BoxColliderDebug} - The debug shape
+     */
+    get debugShape(): BoxColliderDebug;
     /**
      * @method showDebugShape
      * @description Shows the debug shape of the collider
@@ -35,7 +35,7 @@ declare class BoxCollider extends Collider {
      * @method getFixtureSize
      * @description Returns the size of the collider
      */
-    getFixtureSize(): Vector2;
+    getFixtureSize(): any;
 }
-export default BoxCollider;
-//# sourceMappingURL=BoxCollider.d.ts.map
+import Collider from "./Collider.js";
+import BoxColliderDebug from "./BoxColliderDebug.js";

package/dist/types/src/components/BoxColliderDebug.d.ts

@@ -0,0 +1,15 @@
+export default BoxColliderDebug;
+/**
+ * @class BoxColliderDebug
+ * @param {Rigidbody} rigidbody - The rigidbody to attach the collider to
+ * @param {Color} color - The color of the collider
+ */
+declare class BoxColliderDebug {
+    constructor(rigidbody: any, color?: any);
+    rigidbody: any;
+    physics: any;
+    scale: any;
+    color: any;
+    gameObject: GameObject;
+}
+import GameObject from "./GameObject.js";

package/dist/types/{components → src/components}/CircleCollider.d.ts

@@ -1,7 +1,4 @@
-import * as planck from "planck";
-import CircleColliderDebug from "./CircleColliderDebug";
-import Collider from "./Collider";
-import RigidBody from "./RigidBody";
+export default CircleCollider;
 /**
  * @class CircleCollider
  * @extends Collider
@@ -14,11 +11,16 @@ import RigidBody from "./RigidBody";
  * @param {GameObject} parentObject - The parent object of the collider
  */
 declare class CircleCollider extends Collider {
-    radius: number;
-    debugShape: CircleColliderDebug;
-    collider: planck.Fixture;
-    name: string;
-    constructor(rigidbody: RigidBody, radius: number, density: number, friction: number, restitution: number, isSensor?: boolean, parentObject?: null);
+    constructor(rigidbody: any, radius: any, density: any, friction: any, restitution: any, isSensor?: boolean, parentObject?: any, filter?: any);
+    collider: any;
+    radius: any;
+    /**
+     * @method debugShape
+     * @description Lazily builds the debug visualization on first access, so a
+     * collider stays free of any GameObject/GL allocation until it is debugged.
+     * @returns {CircleColliderDebug} - The debug shape
+     */
+    get debugShape(): CircleColliderDebug;
     /**
      * @method showDebugShape
      * @description Shows the debug shape of the collider
@@ -33,7 +35,7 @@ declare class CircleCollider extends Collider {
      * @method getRadius
      * @description Returns the radius of the collider
      */
-    getRadius(): number;
+    getRadius(): any;
 }
-export default CircleCollider;
-//# sourceMappingURL=CircleCollider.d.ts.map
+import Collider from "./Collider.js";
+import CircleColliderDebug from "./CircleColliderDebug.js";

package/dist/types/src/components/CircleColliderDebug.d.ts

@@ -0,0 +1,15 @@
+export default CircleColliderDebug;
+/**
+ * @class CircleColliderDebug
+ * @param {Rigidbody} rigidbody - The rigidbody to attach the collider to
+ * @param {Color} color - The color of the collider
+ */
+declare class CircleColliderDebug {
+    constructor(rigidbody: any, color?: any);
+    rigidbody: any;
+    physics: any;
+    scale: any;
+    color: any;
+    gameObject: GameObject;
+}
+import GameObject from "./GameObject.js";