emeraldengine 2.2.1 → 3.1.0

package/dist/types/{Instance.d.ts → src/Instance.d.ts}

@@ -1,6 +1,4 @@
-import InstancedTexture from "./InstancedTexture";
-import { Vector2, Vector3 } from "./Physics";
-import Transform from "./Transform";
+export default Instance;
 /**
  * @class Instance
  * @description Represents an instance
@@ -11,40 +9,63 @@ import Transform from "./Transform";
  * @param {number} frame - The frame of the instance
  */
 declare class Instance {
-    name: string;
+    constructor(name: any, position?: Vector3, scale?: Vector2, rotation?: number, frame?: number);
+    name: any;
     transform: Transform;
     id: string;
-    parent: InstancedTexture | null;
+    parent: Instance;
     frame: number;
     isAnimating: boolean;
-    animationFrames: number[];
+    animationFrames: any[];
     currentAnimationIndex: number;
     animationSpeed: number;
     lastFrameTime: number;
     playOnce: boolean;
     originalFrame: number;
     components: any[];
-    constructor(name: string, position?: Vector3, scale?: Vector2, rotation?: number, frame?: number);
+    /** @private */
+    private _tint;
+    /**
+     * @method setColor
+     * @description Sets this instance's tint. Accepts a Color (0..255 channels) or
+     * raw 0..1 components. Multiplies the texture/base color in the shader.
+     * @param {Color|number} colorOrR - A Color instance, or the red channel
+     * @param {number} [g]
+     * @param {number} [b]
+     * @param {number} [a]
+     */
+    setColor(colorOrR: Color | number, g?: number, b?: number, a?: number): void;
+    /**
+     * @method setTexCoords
+     * @description Gives this instance an explicit UV quad (8 floats, one vec2
+     * per corner in the same order as getFrameTexCoords) instead of the shared
+     * frame grid. Lets one InstancedTexture batch tiles from an atlas with
+     * margins/spacing or per-instance flips. Pass null to go back to `frame`.
+     * @param {number[]|Float32Array|null} uv8 - 8 UV floats, or null to clear
+     */
+    setTexCoords(uv8: number[] | Float32Array | null): void;
+    /** @private */
+    private _regionUV;
     /**
      * @method setParent
      * @description Sets the parent of the instance
      * @param {Instance} parent - The parent of the instance
      */
-    setParent(parent: InstancedTexture): void;
+    setParent(parent: Instance): void;
     /**
      * @method playAnimation
      * @description Plays an animation with an array of frames
      * @param {Array} frames - The frames to play
      * @param {number} speed - The speed of the animation
      */
-    playAnimation(frames: number[], speed?: number): void;
+    playAnimation(frames: any[], speed?: number): void;
     /**
      * @method playAnimationOnce
      * @description Plays an animation with an array of frames once then stops
      * @param {Array} frames - The frames to play
      * @param {number} speed - The speed of the animation
      */
-    playAnimationOnce(frames: number[], speed?: number): void;
+    playAnimationOnce(frames: any[], speed?: number): void;
     /**
      * @method stopAnimation
      * @description Stops the animation and optionally reverts to the original frame
@@ -68,20 +89,21 @@ declare class Instance {
      * @description Adds a component to the instance
      * @param {Component} componentInstance - The component to add
      */
-    addComponent(componentInstance: any): void;
+    addComponent(componentInstance: Component): void;
     /**
      * @method removeComponent
      * @description Removes a component from the instance
      * @param {Component} component - The component to remove
      */
-    removeComponent(component: any): void;
+    removeComponent(component: Component): void;
     /**
      * @method getComponent
      * @description Gets a component from the instance
      * @param {Component} componentType - The type of the component to get
      * @returns {Component} - The component
      */
-    getComponent(componentType: any): any;
+    getComponent(componentType: Component): Component;
 }
-export default Instance;
-//# sourceMappingURL=Instance.d.ts.map
+import Transform from "./Transform.js";
+import { Vector3 } from "./Physics.js";
+import { Vector2 } from "./Physics.js";

package/dist/types/{InstancedTexture.d.ts → src/InstancedTexture.d.ts}

@@ -1,6 +1,4 @@
-import Instance from "./Instance";
-import Drawable from "./Drawable";
-import { Vector3 } from "./Physics";
+export default InstancedTexture;
 /**
  * @class InstancedTexture
  * @description Represents an instanced texture component
@@ -16,18 +14,33 @@ import { Vector3 } from "./Physics";
  * @param {boolean} useLighting - Whether to use lighting
  */
 declare class InstancedTexture extends Drawable {
+    constructor(texturePath?: {}, instanceCount?: number, frameWidth?: number, frameHeight?: number, framesPerRow?: number, totalFrames?: number, animationSpeed?: number, autoPlay?: boolean, pixelart?: boolean, useLighting?: boolean);
     instanceCount: number;
-    instances: Instance[];
-    instanceMatrices: Float32Array;
-    instanceTexCoords: Float32Array;
-    instanceMatrixBuffer: WebGLBuffer;
-    instanceTexCoordBuffer: WebGLBuffer;
-    instanceClickListeners: Map<string, Set<Function>>;
-    instanceHoverListeners: Map<string, {
-        enter: Set<Function>;
-        leave: Set<Function>;
-    }>;
-    constructor(texturePath?: string, instanceCount?: number, frameWidth?: number, frameHeight?: number, framesPerRow?: number, totalFrames?: number, animationSpeed?: number, autoPlay?: boolean, pixelart?: boolean, useLighting?: boolean);
+    instances: any[];
+    instanceMatrices: Float32Array<ArrayBuffer>;
+    instanceTexCoords: Float32Array<ArrayBuffer>;
+    instanceColors: Float32Array<ArrayBuffer>;
+    instanceMatrixBuffer: any;
+    instanceTexCoordBuffer: any;
+    instanceColorBuffer: any;
+    instanceClickListeners: Map<any, any>;
+    instanceHoverListeners: Map<any, any>;
+    static: boolean;
+    /** @private */
+    private _matricesDirty;
+    /** The animation every instance starts with; set by playAnimation/playAnimationOnce. @private */
+    private _defaultAnimation;
+    /**
+     * @method setStatic
+     * @description Toggles static mode (see constructor notes).
+     * @param {boolean} isStatic - Whether instances are non-moving
+     */
+    setStatic(isStatic: boolean): void;
+    /**
+     * @method markDirty
+     * @description Forces an instance-matrix rebuild on the next draw.
+     */
+    markDirty(): void;
     /**
      * @method addInstance
      * @description Adds an instance to the instanced texture
@@ -62,6 +75,18 @@ declare class InstancedTexture extends Drawable {
      * @description Updates all instance matrices
      */
     updateAllInstanceMatrices(): void;
+    /**
+     * @method updateInstanceColor
+     * @description Writes a single instance's RGBA tint into the color array.
+     * Reads `instance._tint` ([r,g,b,a] in 0..1) when set, else opaque white.
+     * @param {number} index - The instance index
+     */
+    updateInstanceColor(index: number): void;
+    /**
+     * @method updateAllInstanceColors
+     * @description Rebuilds and uploads the per-instance color buffer.
+     */
+    updateAllInstanceColors(): void;
     /**
      * @method updateInstanceTexCoords
      * @description Updates the texture coordinates for a specific instance
@@ -79,7 +104,7 @@ declare class InstancedTexture extends Drawable {
      * @param {string} id - The ID of the instance to get
      * @returns {Instance} - The instance
      */
-    getInstanceWithId(id: string): Instance | undefined;
+    getInstanceWithId(id: string): Instance;
     /**
      * @method update
      * @description Updates the instanced texture
@@ -93,7 +118,7 @@ declare class InstancedTexture extends Drawable {
      * @param {Array} frames - The frames to animate
      * @param {number} speed - The speed of the animation
      */
-    animateInstance(instanceId: string, frames: number[], speed?: number): void;
+    animateInstance(instanceId: string, frames: any[], speed?: number): void;
     /**
      * @method stopInstanceAnimation
      * @description Stops animation on a specific instance
@@ -133,7 +158,14 @@ declare class InstancedTexture extends Drawable {
      * @param {number} frame - The frame to calculate the texture coordinates for
      * @returns {Array} - The texture coordinates
      */
-    getFrameTexCoords(frame: number): number[];
+    getFrameTexCoords(frame: number): any[];
+    /**
+     * @method syncPhysics
+     * @description Copies simulation state (position + rotation) from each
+     * instance's dynamic rigidbody onto the instance transform. Driven once per
+     * frame by the owning GameObject's syncPhysics(), so draw() stays read-only.
+     */
+    syncPhysics(): void;
     /**
      * @method draw
      * @description Draws the instanced texture
@@ -162,14 +194,14 @@ declare class InstancedTexture extends Drawable {
      * @param {number} tolerance - The tolerance for the position
      * @returns {Instance} - The instance at the position
      */
-    getInstanceAtPosition(position: Vector3, tolerance?: number): Instance | undefined;
+    getInstanceAtPosition(position: Vector3, tolerance?: number): Instance;
     /**
      * @method getInstanceByFrame
      * @description Gets an instance by its frame index
      * @param {number} frameIndex - The frame index to get
      * @returns {Instance} - The instance at the frame index
      */
-    getInstanceByFrame(frameIndex: number): Instance | undefined;
+    getInstanceByFrame(frameIndex: number): Instance;
     /**
      * @method getInstanceAtPoint
      * @description Gets an instance at a specific point
@@ -177,7 +209,7 @@ declare class InstancedTexture extends Drawable {
      * @param {number} y - The y coordinate of the point
      * @returns {Instance} - The instance at the point
      */
-    getInstanceAtPoint(x: number, y: number): Instance | undefined;
+    getInstanceAtPoint(x: number, y: number): Instance;
     /**
      * @method addInstanceClickEvent
      * @description Adds a click event listener to a specific instance
@@ -224,7 +256,27 @@ declare class InstancedTexture extends Drawable {
      * @param {number} y - The y coordinate of the hover
      * @param {Instance} lastHoveredInstance - The last hovered instance
      */
-    handleInstanceHover(event: Event, x: number, y: number, lastHoveredInstance: Instance | undefined): Instance | undefined;
+    handleInstanceHover(event: Event, x: number, y: number, lastHoveredInstance: Instance): Instance;
+    /**
+     * @method playAnimationOnce
+     * @description Plays the same animation once, in lockstep, on every
+     * instance, then holds each on its last frame: the current instances
+     * immediately, and any added later via {@link InstancedTexture#addInstance}.
+     * @param {Array} frames - The frames to play
+     * @param {number} [speed=1000] - Milliseconds per frame
+     */
+    playAnimationOnce(frames: any[], speed?: number): void;
+    /**
+     * @method stopAnimation
+     * @description Stops the shared animation started by playAnimation/
+     * playAnimationOnce on every current instance, and clears it so instances
+     * added afterwards no longer start playing it either. Instances animated
+     * individually via {@link InstancedTexture#animateInstance} are unaffected
+     * unless you stop them the same way, through {@link InstancedTexture#stopInstanceAnimation}.
+     * @param {boolean} [revertToOriginal=false] - Whether to reset each
+     *   instance back to the frame it had before playAnimation was called
+     */
+    stopAnimation(revertToOriginal?: boolean): void;
 }
-export default InstancedTexture;
-//# sourceMappingURL=InstancedTexture.d.ts.map
+import Drawable from "./Drawable.js";
+import Instance from "./Instance.js";

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

@@ -0,0 +1,66 @@
+export default Interpolator;
+/**
+ * @class Interpolator
+ * @description Snapshot interpolation buffer for smoothing networked state.
+ * Authoritative updates arrive at a low, irregular rate (e.g. 10–20 Hz); this
+ * buffers timestamped snapshots and lets you sample a position "in the past" by
+ * a fixed render delay, so remote entities move smoothly between updates instead
+ * of teleporting.
+ *
+ * It is transport-agnostic and pure (no network/DOM dependency), so it works
+ * with the built-in NetworkManager, any other transport, or in tests.
+ *
+ * @example
+ * const interp = new Interpolator({ delay: 0.1 });
+ * // on each server update for an entity:
+ * interp.push(entityId, { x, y }, serverTimeSeconds);
+ * // each frame:
+ * const pos = interp.sample(entityId, nowSeconds); // { x, y } or null
+ */
+declare class Interpolator {
+    /**
+     * @param {Object} [options] - { delay = 0.1, maxBuffer = 60 }
+     */
+    constructor(options?: any);
+    delay: any;
+    maxBuffer: any;
+    /** @private */
+    private _buffers;
+    /**
+     * @method push
+     * @description Records a snapshot for an entity at a given timestamp.
+     * @param {string|number} id - Entity id
+     * @param {Object} state - Any object with numeric fields to interpolate (e.g. {x,y})
+     * @param {number} time - Snapshot timestamp in seconds
+     */
+    push(id: string | number, state: any, time: number): void;
+    /**
+     * @method sample
+     * @description Returns the interpolated state for an entity at (now - delay).
+     * Linearly interpolates numeric fields between the two surrounding snapshots.
+     * Returns the latest snapshot if rendering ahead of the buffer, or null if no
+     * data exists.
+     * @param {string|number} id - Entity id
+     * @param {number} now - Current time in seconds
+     * @returns {Object|null} - Interpolated state, or null
+     */
+    sample(id: string | number, now: number): any | null;
+    /**
+     * @method remove
+     * @description Drops an entity's buffer (e.g. when it leaves).
+     */
+    remove(id: any): void;
+    /**
+     * @method prune
+     * @description Drops snapshots older than (now - delay - keep) to bound memory
+     * for long-lived entities.
+     * @param {number} now - Current time in seconds
+     * @param {number} [keep] - Extra history to retain past the render point
+     */
+    prune(now: number, keep?: number): void;
+    /**
+     * @method clear
+     * @description Removes all buffered snapshots.
+     */
+    clear(): void;
+}

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

@@ -0,0 +1,87 @@
+export default Material;
+/**
+ * @class Material
+ * @description A custom shader for a Drawable. By default it reuses the engine's
+ * standard vertex shader (so transforms, the camera, and instancing keep
+ * working) and only overrides the fragment program. Pass `options.vertex` to
+ * also supply a custom VERTEX program: the escape hatch for effects the fixed
+ * pipeline can't express (perspective tilt, vertex waves, billboarding, ...).
+ *
+ * The fragment shader always has: `vTexCoord`, `vFragPos`, `vInstanceColor`,
+ * `uSampler`, `uColor`, `uOpacity`, `uTime`. A custom vertex shader gets
+ * `aVertexPosition`, `aTextureCoord`, `uProjectionMatrix`, `uModelViewMatrix`,
+ * `uTime`, and must write `vTexCoord` + `gl_Position`.
+ *
+ * Declare extra uniforms and set them via `set(name, value)`. A uniform value
+ * may be a number, an array (vec2/3/4), or a FUNCTION: the function is called
+ * each draw and receives the Drawable currently rendering, so a single shared
+ * Material can read PER-OBJECT state (e.g. each card's own tilt angle).
+ *
+ * @example
+ * // Per-object 3D tilt with one shared material:
+ * const tilt = new Material(fragSrc, {
+ *   vertex: tiltVertexSrc,
+ *   uniforms: { uTiltX: (d) => d._tiltX || 0, uTiltY: (d) => d._tiltY || 0 },
+ * });
+ * cardA.setMaterial(tilt); cardB.setMaterial(tilt);
+ * cardA.getComponent(Texture)._tiltX = 0.3; // each object animates independently
+ */
+declare class Material {
+    /**
+     * @param {string} fragmentSource - Fragment shader body (declares void main)
+     * @param {Object} [options] - { vertex?: string, uniforms?: { name: value|function } }
+     */
+    constructor(fragmentSource: string, options?: any);
+    gl: WebGLRenderingContext;
+    /** @private */
+    private _vertexSource;
+    /** @private */
+    private _fragmentSource;
+    program: any;
+    programInfo: {
+        program: any;
+        attribLocations: {
+            vertexPosition: number;
+            aTexCoord: number;
+        };
+        uniformLocations: {
+            projectionMatrix: WebGLUniformLocation;
+            globalViewMatrix: WebGLUniformLocation;
+            useInstances: WebGLUniformLocation;
+            uSampler: WebGLUniformLocation;
+            color: WebGLUniformLocation;
+            uOpacity: WebGLUniformLocation;
+            uTime: WebGLUniformLocation;
+        };
+    };
+    uniforms: any;
+    /** @private */
+    private _locCache;
+    /**
+     * @method _restoreGL
+     * @description Recompiles the material's program and refreshes every cached
+     * location after a WebGL context loss.
+     * @private
+     */
+    private _restoreGL;
+    /**
+     * @method set
+     * @description Sets (or schedules) a custom uniform value. Numbers, arrays
+     * (vec2/3/4), and functions returning those are supported. A function uniform
+     * receives the Drawable currently being rendered.
+     * @param {string} name - Uniform name
+     * @param {number|number[]|Function} value
+     * @returns {Material} - this
+     */
+    set(name: string, value: number | number[] | Function): Material;
+    /** @private */
+    private _loc;
+    /**
+     * @method applyCustomUniforms
+     * @description Uploads all user-declared uniforms. Called by Drawable each draw
+     * after the program is bound. Inferred by value shape. Function uniforms are
+     * called with the rendering Drawable so shared materials can read per-object data.
+     * @param {Drawable} [drawable] - The drawable currently rendering
+     */
+    applyCustomUniforms(drawable?: Drawable): void;
+}

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

@@ -0,0 +1,81 @@
+export default MathUtils;
+/**
+ * @class MathUtils
+ * @description Common math helpers for games: interpolation, clamping, angle
+ * conversion, random ranges, and lightweight 2D vector operations that work on
+ * any `{ x, y }` object (including the physics engine's Vec2 and Emerald
+ * Vector2).
+ */
+declare class MathUtils {
+    /**
+     * Clamps a value to the [min, max] range.
+     */
+    static clamp(value: any, min: any, max: any): any;
+    /**
+     * Linearly interpolates between a and b by t (t is not clamped).
+     */
+    static lerp(a: any, b: any, t: any): any;
+    /**
+     * Inverse lerp: returns the t for which lerp(a, b, t) === value.
+     */
+    static inverseLerp(a: any, b: any, value: any): number;
+    /**
+     * Remaps a value from one range to another.
+     */
+    static map(value: any, inMin: any, inMax: any, outMin: any, outMax: any): any;
+    /**
+     * Converts degrees to radians.
+     */
+    static degToRad(degrees: any): number;
+    /**
+     * Converts radians to degrees.
+     */
+    static radToDeg(radians: any): number;
+    /**
+     * Returns a random float in [min, max).
+     */
+    static randomRange(min: any, max: any): any;
+    /**
+     * Returns a random integer in [min, max] (inclusive).
+     */
+    static randomInt(min: any, max: any): number;
+    /**
+     * Returns a random element of an array (or undefined if empty).
+     */
+    static randomChoice(array: any): any;
+    /**
+     * Euclidean distance between two `{ x, y }` points.
+     */
+    static distance(a: any, b: any): number;
+    /**
+     * Squared distance between two points (cheaper than distance for comparisons).
+     */
+    static distanceSquared(a: any, b: any): number;
+    /**
+     * Vector length (magnitude) of an `{ x, y }`.
+     */
+    static length(v: any): number;
+    /**
+     * Returns a normalized copy of `{ x, y }` as a plain object. Zero-length
+     * vectors return { x: 0, y: 0 }.
+     */
+    static normalize(v: any): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Dot product of two `{ x, y }` vectors.
+     */
+    static dot(a: any, b: any): number;
+    /**
+     * Angle in radians from a to b.
+     */
+    static angleBetween(a: any, b: any): number;
+    /**
+     * Linearly interpolates between two `{ x, y }` points, returning a plain object.
+     */
+    static lerpVector(a: any, b: any, t: any): {
+        x: any;
+        y: any;
+    };
+}

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

@@ -0,0 +1,131 @@
+export default ParticleEmitter;
+/**
+ * @class ParticleEmitter
+ * @description A reliable, allocation-free particle system built from a fixed
+ * pool of ordinary textured GameObjects. Each live particle's transform, tint
+ * and opacity are driven by hand every frame; there is no instanced-draw /
+ * dynamic-buffer lifecycle to desync, so it keeps drawing for the whole session
+ * (unlike the InstancedTexture-based `Particles`, which can stop emitting after
+ * heavy reuse on some GPUs).
+ *
+ * Spawn with `burst(n, cfg)` or `emit(cfg)`; advance with `update(dt)` once per
+ * frame. Every `cfg` field is optional and has a sensible default, so the
+ * minimal call is `emitter.burst(8, { x, y })`.
+ *
+ * @example
+ * const fx = new ParticleEmitter(scene, { texture: smokeImg, layer: 50 });
+ * fx.burst(12, {
+ *   x: 100, y: 200, dir: -Math.PI / 2, spread: Math.PI, speed: 180,
+ *   gy: -300, drag: 2, life: 0.4, size: 8, sFrom: 1, sTo: 0.1,
+ *   aFrom: 0.7, aTo: 0, cr: 255, cg: 220, cb: 120, additive: true,
+ *   shape: "circle", radius: 6,
+ * });
+ * // in the loop: fx.update(dt);
+ */
+declare class ParticleEmitter {
+    /**
+     * @param {Scene} scene - Scene the particle GameObjects are added to
+     * @param {Object} [options]
+     * @param {string|HTMLImageElement} [options.texture] - Particle sprite source
+     * @param {number} [options.capacity=256] - Pool size (max live particles)
+     * @param {number} [options.layer=0] - Render layer for every particle
+     * @param {boolean} [options.pixelart=false] - Pixel-art sampling for the sprite
+     * @param {Function} [options.spriteFactory] - `(texture, options) => Drawable`
+     *   override used to build each particle's drawable (handy for tests / custom
+     *   shaders). Defaults to a non-lit `Texture`.
+     */
+    constructor(scene: Scene, options?: {
+        texture?: string | HTMLImageElement;
+        capacity?: number;
+        layer?: number;
+        pixelart?: boolean;
+        spriteFactory?: Function;
+    });
+    scene: Scene;
+    capacity: number;
+    layer: number;
+    parts: {
+        go: GameObject;
+        drawable: any;
+        color: Color;
+        alive: boolean;
+        x: number;
+        y: number;
+        vx: number;
+        vy: number;
+        gx: number;
+        gy: number;
+        drag: number;
+        age: number;
+        life: number;
+        base: number;
+        sFrom: number;
+        sTo: number;
+        aFrom: number;
+        aTo: number;
+        rot: number;
+        rotSpeed: number;
+        additive: boolean;
+    }[];
+    free: {
+        go: GameObject;
+        drawable: any;
+        color: Color;
+        alive: boolean;
+        x: number;
+        y: number;
+        vx: number;
+        vy: number;
+        gx: number;
+        gy: number;
+        drag: number;
+        age: number;
+        life: number;
+        base: number;
+        sFrom: number;
+        sTo: number;
+        aFrom: number;
+        aTo: number;
+        rot: number;
+        rotSpeed: number;
+        additive: boolean;
+    }[];
+    /**
+     * @member activeCount
+     * @description Number of particles currently alive.
+     */
+    get activeCount(): number;
+    /**
+     * @method emit
+     * @description Spawns a single particle. Returns the emitter for chaining.
+     * @param {Object} cfg - Spawn config (see class example; all fields optional)
+     */
+    emit(cfg?: any): this;
+    /**
+     * @method burst
+     * @description Spawns `n` particles with the same config.
+     * @param {number} n - How many to spawn
+     * @param {Object} cfg - Spawn config
+     */
+    burst(n: number, cfg?: any): this;
+    /** @private */
+    private _spawn;
+    /**
+     * @method update
+     * @description Advances and renders every live particle. Call once per frame.
+     * @param {number} dt - Seconds since the last frame
+     */
+    update(dt: number): void;
+    /**
+     * @method reset
+     * @description Kills every live particle immediately (no fade).
+     */
+    reset(): void;
+    /**
+     * @method destroy
+     * @description Removes every particle GameObject from the scene.
+     */
+    destroy(): void;
+}
+import GameObject from "./components/GameObject.js";
+import Color from "./Color.js";