emeraldengine 2.2.1 → 3.0.0

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

@@ -0,0 +1,135 @@
+export default GameObject;
+/**
+ * @class GameObject
+ * @param {string} name - The name of the game object
+ * @param {Vector3} position - The position of the game object
+ * @param {number} rotation - The rotation of the game object
+ * @param {Vector2} scale - The scale of the game object
+ */
+declare class GameObject {
+    constructor(name: any, position?: Vector3, rotation?: number, scale?: Vector2);
+    name: any;
+    components: any[];
+    id: string;
+    isActive: boolean;
+    transform: Transform;
+    opacity: number;
+    layer: number;
+    screenSpace: boolean;
+    /**
+     * @method setLayer
+     * @description Sets the render layer. Objects are drawn by layer first, then
+     * by z within a layer.
+     * @param {number} layer - The layer index
+     * @returns {GameObject} - this
+     */
+    setLayer(layer: number): GameObject;
+    /**
+     * @method setScreenSpace
+     * @description When true, the object ignores the camera (fixed on screen) —
+     * useful for HUD/UI. Position is then in pixels from the viewport center.
+     * Note: not supported for InstancedTexture-based objects.
+     * @param {boolean} value
+     * @returns {GameObject} - this
+     */
+    setScreenSpace(value: boolean): GameObject;
+    /**
+     * @method addComponent
+     * @description Adds a component to the game object
+     * @param {Component} componentInstance - The component to add
+     */
+    addComponent(componentInstance: Component): void;
+    /**
+     * @method removeComponent
+     * @description Removes a component from the game object
+     * @param {Component} component - The component to remove
+     */
+    removeComponent(component: Component): void;
+    /**
+     * @method update
+     * @description Ticks the lifecycle of Behaviour components on this object.
+     * Only Behaviours are ticked here so component types with their own update
+     * signature (e.g. InstancedTexture) are left untouched.
+     * @param {number} deltaTime - Seconds since the previous frame (time-scaled)
+     */
+    update(deltaTime: number): void;
+    /**
+     * @method setParent
+     * @description Parents this object to another GameObject (or detaches with
+     * null). The object's transform then composes on top of the parent's, so
+     * moving/rotating/scaling the parent moves its children.
+     * @param {GameObject|null} parent - The parent GameObject, or null
+     * @returns {GameObject} - this
+     */
+    setParent(parent: GameObject | null): GameObject;
+    /**
+     * @method addChild
+     * @description Parents another GameObject to this one.
+     * @param {GameObject} child - The child GameObject
+     * @returns {GameObject} - this
+     */
+    addChild(child: GameObject): GameObject;
+    /**
+     * @method setIsActive
+     * @description Sets the active state of the game object
+     * @param {boolean} bool - The active state
+     */
+    setIsActive(bool: boolean): void;
+    /**
+     * @method setOpacity
+     * @description Sets the opacity of the game object (0..1)
+     * @param {number} value - The opacity value between 0 and 1
+     */
+    setOpacity(value: number): void;
+    /**
+     * @method getOpacity
+     * @description Gets the opacity of the game object
+     * @returns {number} - The opacity value between 0 and 1
+     */
+    getOpacity(): number;
+    /**
+     * @method getComponent
+     * @description Returns a component from the game object
+     * @param {Component} componentType - The type of component to return
+     */
+    getComponent(componentType: Component): any;
+    /**
+     * @method getRigidBodyAtPosition
+     * @description Returns the rigidbody at a position
+     * @param {Vector2} position - The position to check
+     */
+    getRigidBodyAtPosition(position: Vector2): RigidBody;
+    /**
+     * @method syncPhysics
+     * @description Copies simulation state (position + rotation) from this
+     * object's dynamic rigidbody onto its transform, and mirrors it onto any
+     * visible collider debug shape. Called once per frame from the render loop so
+     * draw() stays read-only and physics isn't re-applied per camera. Also
+     * forwards to components that own their own physics-driven content (e.g.
+     * InstancedTexture).
+     */
+    syncPhysics(): void;
+    /**
+     * @method destroy
+     * @description Permanently tears the object down: disposes every Drawable's
+     * GPU resources, destroys physics bodies, and runs Behaviour.onDestroy().
+     * Use it (or Scene.remove(obj, { dispose: true })) when an object will not
+     * be re-added — plain Scene.remove() keeps GPU resources alive for re-use.
+     * Safe to call twice.
+     */
+    destroy(): void;
+    /** @private */
+    private _destroyed;
+    /**
+     * @method draw
+     * @description Draws the game object
+     * @param {Matrix4} globalViewMatrix - The global view matrix
+     * @param {WebGLUniformLocation} uniformLocation - The uniform location
+     * @param {number} currentTime - The current time
+     */
+    draw(globalViewMatrix: Matrix4, uniformLocation: WebGLUniformLocation, currentTime: number): void;
+}
+import Transform from "../Transform.js";
+import { Vector2 } from "../Physics.js";
+import RigidBody from "./RigidBody.js";
+import { Vector3 } from "../Physics.js";

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

@@ -0,0 +1,183 @@
+export default RigidBody;
+/**
+ * @class RigidBody
+ * @param {Physics} physics - The physics engine
+ * @param {string | "static" | "dynamic" | "kinematic"} type - The type of rigidbody
+ * @param {Vector2} position - The position of the rigidbody
+ * @param {boolean} fixedRotation - Whether the rigidbody is fixed rotation
+ * @param {GameObject} parentObject - The parent object of the rigidbody
+ * @param {Vector2} offset - The offset of the rigidbody
+ */
+declare class RigidBody {
+    constructor(physics: any, type: any, position: any, fixedRotation: any, parentObject?: any, offset?: Vector2);
+    physics: any;
+    offset: Vector2;
+    type: any;
+    body: any;
+    parentObject: any;
+    position: any;
+    collider: Collider;
+    id: string;
+    name: string;
+    /**
+     * @method updatePosition
+     * @description Updates the position of the rigidbody
+     * @param {Vector2} position - The new position
+     */
+    updatePosition(position: Vector2): void;
+    /**
+     * @method getWorldX
+     * @description The single source of truth for body(physics) -> world(pixel)
+     * conversion on X: undo the scale and the spawn offset.
+     * @returns {number} - The live world-space x of the body
+     * @private
+     */
+    private getWorldX;
+    /**
+     * @method getWorldY
+     * @description World-space y counterpart of getWorldX.
+     * @returns {number} - The live world-space y of the body
+     * @private
+     */
+    private getWorldY;
+    /**
+     * @method syncTransform
+     * @description Writes the body's live world position and angle into a
+     * Transform. This is the one place body state is copied onto a renderable, so
+     * position and rotation stay in lock-step. Static/kinematic bodies are not
+     * driven by the simulation, so only dynamic bodies write back.
+     * @param {Transform} transform - The transform to update in place
+     */
+    syncTransform(transform: Transform): void;
+    /**
+     * @method getOffset
+     * @description Returns the offset of the rigidbody
+     * @returns {Vector2} - The offset of the rigidbody
+     */
+    getOffset(): Vector2;
+    /**
+     * @method setCollider
+     * @description Sets the collider of the rigidbody
+     * @param {Collider} collider - The collider to set
+     */
+    setCollider(collider: Collider): void;
+    /**
+     * @method setRotation
+     * @description Sets the rotation of the rigidbody
+     * @param {number} rotation - The new rotation
+     */
+    setRotation(rotation: number): void;
+    /**
+     * @method setLinearVelocity
+     * @description Sets the body's linear velocity in world (pixel) units per
+     * second. Converts to physics units internally.
+     * @param {number} vx - Horizontal velocity (world units/sec)
+     * @param {number} vy - Vertical velocity (world units/sec)
+     */
+    setLinearVelocity(vx: number, vy: number): void;
+    /**
+     * @method getLinearVelocity
+     * @description Returns the body's linear velocity in world (pixel) units/sec.
+     * @returns {{x:number, y:number}}
+     */
+    getLinearVelocity(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * @method applyImpulse
+     * @description Applies a linear impulse (world units) at the body's center.
+     * @param {number} ix
+     * @param {number} iy
+     */
+    applyImpulse(ix: number, iy: number): void;
+    /**
+     * @method setAwake
+     * @description Wakes or sleeps the body.
+     * @param {boolean} awake
+     */
+    setAwake(awake: boolean): void;
+    /**
+     * @method setContinuous
+     * @description Enables continuous collision detection (CCD) for this body by
+     * marking it a "bullet". Fast-moving bodies (e.g. a dash, a projectile, a
+     * player falling at high speed) otherwise sweep so far in a single fixed step
+     * that they tunnel straight through thin static geometry; with CCD on, planck
+     * solves the swept path against static bodies so the body stops at the wall
+     * instead of teleporting past it. Costs more per step, so reserve it for the
+     * handful of bodies that actually move fast.
+     * @param {boolean} [enabled=true]
+     * @returns {RigidBody} - this
+     */
+    setContinuous(enabled?: boolean): RigidBody;
+    /**
+     * @method isContinuous
+     * @description Whether CCD (bullet mode) is enabled for this body.
+     * @returns {boolean}
+     */
+    isContinuous(): boolean;
+    /**
+     * @method getPosition
+     * @description Returns the live world-space position of the body (kept in sync
+     * with the simulation), not the spawn position. Use getInitialPosition() for
+     * the position the body was created at.
+     * @returns {Vector2} - The current world-space position of the rigidbody
+     */
+    getPosition(): Vector2;
+    /**
+     * @method getInitialPosition
+     * @description Returns the world-space position the body was created at.
+     * @returns {Vector2} - The spawn position of the rigidbody
+     */
+    getInitialPosition(): Vector2;
+    /**
+     * @method getAngle
+     * @description Returns the angle of the rigidbody
+     * @returns {number} - The angle of the rigidbody
+     */
+    getAngle(): number;
+    /**
+     * @method getCollider
+     * @description Returns the collider of the rigidbody
+     * @returns {Collider} - The collider of the rigidbody
+     */
+    getCollider(): Collider;
+    /**
+     * @method getBody
+     * @description Returns the body of the rigidbody
+     * @returns {planck.Body} - The body of the rigidbody
+     */
+    getBody(): planck.Body;
+    /**
+     * @method getPhysics
+     * @description Returns the physics engine of the rigidbody
+     * @returns {Physics} - The physics engine of the rigidbody
+     */
+    getPhysics(): Physics;
+    /**
+     * @method destroy
+     * @description Destroys the rigidbody
+     */
+    destroy(): void;
+    /**
+     * @method detachCollider
+     * @description Detaches a collider from the rigidbody
+     * @param {Collider} collider - The collider to detach
+     */
+    detachCollider(collider: Collider): void;
+    /**
+     * @method setParent
+     * @description Sets the parent object of the rigidbody
+     * @param {GameObject} parent - The parent object to set
+     */
+    setParent(parent: GameObject): void;
+    /**
+     * @method getType
+     * @description Returns the type of the rigidbody
+     * @returns {string | "static" | "dynamic" | "kinematic"} - The type of the rigidbody
+     */
+    getType(): string | "static" | "dynamic" | "kinematic";
+}
+import { Vector2 } from "../Physics.js";
+import Collider from "./Collider.js";
+import * as planck from "planck";

package/dist/types/src/importers/Aseprite.d.ts

@@ -0,0 +1,79 @@
+export default Aseprite;
+/**
+ * @class Aseprite
+ * @description Imports sprite-sheet metadata exported from Aseprite
+ * (File ▸ Export Sprite Sheet, with "JSON Data" on) and turns its frame tags
+ * into engine animation clips. Works with both the Hash and Array JSON layouts.
+ * Pure parsing — pass it the already-parsed JSON object.
+ *
+ * Assumes the sheet is a uniform grid in frame order (the common case), so the
+ * frame indices line up with the engine's Texture/Animator frame numbering.
+ *
+ * @example
+ * const cfg = Aseprite.spriteConfig(sheetJson); // {frameWidth, framesPerRow, ...}
+ * const tex = new Texture("hero.png", cfg.frameWidth, cfg.frameHeight,
+ *   cfg.framesPerRow, cfg.totalFrames, 0, false);
+ * obj.addComponent(tex);
+ * const anim = new Animator();
+ * obj.addComponent(anim);
+ * Aseprite.applyTo(anim, sheetJson);   // registers "idle", "run", ... clips
+ * anim.play("run");
+ */
+declare class Aseprite {
+    /**
+     * @method frames
+     * @description Returns the frames as an ordered array regardless of whether
+     * the export used the Hash (object) or Array layout.
+     * @param {Object} sheet - Parsed Aseprite JSON
+     * @returns {Array<Object>}
+     */
+    static frames(sheet: any): Array<any>;
+    /**
+     * @method spriteConfig
+     * @description Derives the uniform-grid sprite config (for Texture) from the
+     * first frame and the sheet size.
+     * @param {Object} sheet - Parsed Aseprite JSON
+     * @returns {{frameWidth:number, frameHeight:number, framesPerRow:number, totalFrames:number}}
+     */
+    static spriteConfig(sheet: any): {
+        frameWidth: number;
+        frameHeight: number;
+        framesPerRow: number;
+        totalFrames: number;
+    };
+    /**
+     * @method durations
+     * @description Per-frame durations in milliseconds, in frame order.
+     * @param {Object} sheet - Parsed Aseprite JSON
+     * @returns {number[]}
+     */
+    static durations(sheet: any): number[];
+    /** @private */
+    private static _expandTag;
+    /**
+     * @method toClips
+     * @description Builds clip descriptors from the sheet's frame tags. Each clip
+     * is `{ name, frames, speed }` where `frames` are frame indices and `speed`
+     * is the average frame duration (ms) — the per-clip speed the Animator uses.
+     * If the sheet has no tags, a single "default" clip spanning all frames is
+     * returned.
+     * @param {Object} sheet - Parsed Aseprite JSON
+     * @returns {Array<{name:string, frames:number[], speed:number}>}
+     */
+    static toClips(sheet: any): Array<{
+        name: string;
+        frames: number[];
+        speed: number;
+    }>;
+    /**
+     * @method applyTo
+     * @description Registers every clip from the sheet on an Animator. Clips loop
+     * by default; pass `loop` as a boolean (applies to all) or an object mapping
+     * clip name -> boolean to override individual clips.
+     * @param {Animator} animator - Target animator
+     * @param {Object} sheet - Parsed Aseprite JSON
+     * @param {Object} [options] - { loop = true }
+     * @returns {Animator} - The animator (for chaining)
+     */
+    static applyTo(animator: Animator, sheet: any, options?: any): Animator;
+}

package/dist/types/src/importers/TiledMap.d.ts

@@ -0,0 +1,62 @@
+export default TiledMap;
+export const FLIP_FLAGS: 3758096384;
+export const GID_MASK: 536870911;
+/**
+ * @class TiledMap
+ * @description Imports orthogonal maps exported from the Tiled editor
+ * (https://www.mapeditor.org) in JSON format into the engine's Tilemap, plus
+ * helpers to pull object layers (spawn points, triggers, etc.) out as plain
+ * data. Pure parsing — pass it the already-parsed JSON object (load it with
+ * AssetManager.json or fetch).
+ *
+ * @example
+ * const map = TiledMap.toTilemap(mapJson, "tiles.png");
+ * scene.add(map.gameObject);
+ * map.buildColliders(physics);
+ * const spawns = TiledMap.objects(mapJson, { layer: "spawns", flipY: true });
+ */
+declare class TiledMap {
+    /**
+     * @method tilesetFor
+     * @description Finds the tileset a (masked) global id belongs to.
+     * @param {Object} map - Parsed Tiled map JSON
+     * @param {number} gid - Masked global tile id (flip flags removed)
+     * @returns {Object|null}
+     */
+    static tilesetFor(map: any, gid: number): any | null;
+    /** @private */
+    private static _tileLayer;
+    /**
+     * @method toFrameGrid
+     * @description Converts a tile layer into a 2D array of local frame indices
+     * (-1 for empty), ready for Tilemap.setMap. Global ids are converted to
+     * tileset-local indices and flip flags are stripped.
+     * @param {Object} map - Parsed Tiled map JSON
+     * @param {Object} [options] - { layer } (name, index, or first tile layer)
+     * @returns {number[][]}
+     */
+    static toFrameGrid(map: any, options?: any): number[][];
+    /**
+     * @method toTilemap
+     * @description Builds a ready-to-render Tilemap from a Tiled map. The tile
+     * sheet config (frame size, columns, count) is read from the map's first
+     * tileset; the render tile size comes from the map's tilewidth.
+     * @param {Object} map - Parsed Tiled map JSON
+     * @param {string} texturePath - Path to the tile sheet image
+     * @param {Object} [options] - { layer, pixelart = true, name, originX, originY }
+     * @returns {Tilemap}
+     */
+    static toTilemap(map: any, texturePath: string, options?: any): Tilemap;
+    /**
+     * @method objects
+     * @description Extracts the objects from an object layer as plain data
+     * (spawn points, triggers, regions). Tiled `properties` arrays are flattened
+     * into a `props` object. With `flipY` set, y is converted from Tiled's
+     * top-left pixel origin to a y-up world using the map's pixel height.
+     * @param {Object} map - Parsed Tiled map JSON
+     * @param {Object} [options] - { layer, flipY = false, originX = 0, originY = 0 }
+     * @returns {Array<Object>}
+     */
+    static objects(map: any, options?: any): Array<any>;
+}
+import Tilemap from "../Tilemap.js";

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