emeraldengine 2.2.0 → 3.0.0

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 planck 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 planck 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";

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

@@ -0,0 +1,96 @@
+export default Collider;
+/**
+ * @class Collider
+ * @param {Rigidbody} rigidbody - The rigidbody to attach the collider to
+ * @param {boolean} isSensor - Whether the collider is a sensor
+ * @param {GameObject} parentObject - The parent object of the collider
+ */
+declare class Collider {
+    constructor(rigidbody: any, isSensor?: boolean, parentObject?: any);
+    rigidbody: any;
+    parentObject: any;
+    isSensor: boolean;
+    id: string;
+    name: string;
+    /** @private */
+    private _debugShape;
+    /**
+     * @method syncDebugShape
+     * @description Mirrors a transform onto the debug shape, but only if one has
+     * already been created. Never forces lazy creation.
+     * @param {Transform} transform - The source transform
+     */
+    syncDebugShape(transform: Transform): void;
+    /**
+     * @method setFilter
+     * @description Sets the raw planck collision filter on this collider's
+     * fixture. Two fixtures collide only when each one's category bit is present
+     * in the other's mask. Subclasses must have created `this.collider`
+     * (the fixture) first.
+     * @param {Object} filter - { category, mask, group }
+     * @param {number} [filter.category=0x0001] - This fixture's category bits
+     * @param {number} [filter.mask=0xFFFF] - Bits this fixture collides with
+     * @param {number} [filter.group=0] - Group index (>0 always collide, <0 never)
+     * @returns {Collider} - this
+     */
+    setFilter({ category, mask, group }?: {
+        category?: number;
+        mask?: number;
+        group?: number;
+    }): Collider;
+    /** @private */
+    private _filter;
+    /**
+     * @method setCategory
+     * @description Sets which named layer this collider belongs to (its category
+     * bits), preserving the current mask/group. See {@link CollisionLayers}.
+     * @param {string|number} layer - Layer name or raw category bits
+     * @returns {Collider} - this
+     */
+    setCategory(layer: string | number): Collider;
+    /**
+     * @method setCollidesWith
+     * @description Sets which layers this collider can collide with (its mask),
+     * preserving the current category/group.
+     * @param {string|string[]|number} layers - Layer name(s) or raw mask bits
+     * @returns {Collider} - this
+     */
+    setCollidesWith(layers: string | string[] | number): Collider;
+    /**
+     * @method getFilter
+     * @description Returns the last applied filter, or null if none was set.
+     * @returns {{category:number, mask:number, group:number}|null}
+     */
+    getFilter(): {
+        category: number;
+        mask: number;
+        group: number;
+    } | null;
+    /**
+     * @method _applyFilterSpec
+     * @description Applies a friendly filter spec from a constructor, accepting
+     * layer names or raw bits. Spec: { category, collidesWith, group }.
+     * @private
+     */
+    private _applyFilterSpec;
+    /**
+     * @method getRigidBody
+     * @description Returns the rigidbody of the collider
+     */
+    getRigidBody(): any;
+    /**
+     * @method getCollider
+     * @description Returns the collider
+     */
+    getCollider(): any;
+    /**
+     * @method setParent
+     * @description Sets the parent object of the collider
+     */
+    setParent(parent: any): void;
+    /**
+     * @method getParent
+     * @description Returns the parent object of the collider
+     */
+    getParent(): any;
+}