emeraldengine 2.2.1 → 3.1.0

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

@@ -0,0 +1,337 @@
+/**
+ * @class Physics
+ * @description The game-facing front end of Emerald's own rigid-body engine
+ * (see `src/physics`). It owns the {@link World}, converts between world
+ * (pixel) units and physics units via `scale`, steps the simulation on a fixed
+ * timestep, and routes contacts to `onCollisionEnter`/`onCollisionExit` on your
+ * objects and {@link Behaviour} components.
+ * @param {number} gravity - The gravity of the physics engine
+ * @param {number} scale - Pixels per physics unit (meter)
+ * @param {number} velocityThreshold - Relative speed below which impacts stop
+ *   bouncing, which is what lets resting bodies settle instead of jittering
+ */
+export class Physics {
+    /**
+     * @method scheduleAction
+     * @description Schedules an action to be executed as soon as possible
+     * @param {Function} callback - The callback function to execute
+     */
+    static scheduleAction(callback: Function): void;
+    constructor(gravity: any, scale: any, velocityThreshold?: number);
+    world: World;
+    gravity: any;
+    scale: any;
+    fixedTimeStep: number;
+    maxSubSteps: number;
+    /** Largest slice the variable mode will simulate in one step. */
+    maxTimeStep: number;
+    /** "fixed" or "variable", see {@link Physics#setVariableTimeStep}. */
+    timeStepMode: string;
+    /** Steps taken by the last process() call. */
+    lastStepCount: number;
+    /** @private */
+    private _accumulator;
+    /** World-level listeners added via onCollisionEnter. @private */
+    private _enterCallbacks;
+    /** World-level listeners added via onCollisionExit. @private */
+    private _exitCallbacks;
+    /**
+     * @method _dispatchContacts
+     * @description Binds contact routing to the current world: owning objects (so
+     * Behaviour components receive onCollisionEnter/onCollisionExit) first, then
+     * any world-level listeners. Bodies created through RigidBody carry the owner
+     * via userData. Re-run whenever the world is replaced, so subscriptions
+     * survive a clear().
+     * @private
+     */
+    private _dispatchContacts;
+    /**
+     * @method raycast
+     * @description Casts a ray through the world and returns the closest hit.
+     * @param {Object} origin - World-space { x, y } start point
+     * @param {Object} direction - Ray direction { x, y } (need not be normalized)
+     * @param {number} maxDistance - Max ray length in world units
+     * @returns {{object, rigidBody, point, normal, fraction}|null}
+     */
+    raycast(origin: any, direction: any, maxDistance: number): {
+        object: any;
+        rigidBody: any;
+        point: any;
+        normal: any;
+        fraction: any;
+    } | null;
+    /**
+     * @method queryPoint
+     * @description Returns the objects whose colliders contain a world-space point.
+     * @param {Object} point - World-space { x, y }
+     * @returns {Array} - Owning objects at the point
+     */
+    queryPoint(point: any): any[];
+    /**
+     * @method setFixedTimeStep
+     * @description Runs the simulation in constant-size slices, independent of
+     * the frame rate: `process()` banks the elapsed time and steps as many whole
+     * slices as fit. This is the default and the safe choice: the same inputs
+     * produce the same result on every machine, and a slow frame can't destabilise
+     * the solver.
+     *
+     * The cost is that motion updates at the step rate, not the display rate. On
+     * a 120Hz screen with a 1/60 step, every simulated position is shown for two
+     * frames, so anything that moves in the render frame (a smoothly lerped
+     * camera, for instance) will slide against sprites that only move every other
+     * frame. Either drive those from the same fixed step, or use
+     * {@link Physics#setVariableTimeStep}.
+     *
+     * @param {number} step - Fixed step in seconds (e.g. 1/60)
+     * @param {number} [maxSubSteps] - Max steps per process() call (spiral guard)
+     * @returns {Physics} - this
+     */
+    setFixedTimeStep(step: number, maxSubSteps?: number): Physics;
+    /**
+     * @method setVariableTimeStep
+     * @description Advances the simulation once per `process()` call using the
+     * frame's own delta, so physics runs at exactly the rendering rate. Every
+     * rendered frame then shows a freshly simulated position, which is what
+     * removes the stepping you otherwise see when the display refreshes faster
+     * than the simulation.
+     *
+     * The trade-offs are real and worth knowing:
+     * - **Not deterministic.** Results depend on the frame timings the machine
+     *   happened to produce, so replays and lockstep networking need fixed steps.
+     * - **Solver accuracy tracks the frame rate.** Contacts are resolved
+     *   iteratively, so a long frame is a coarser solve; deep stacks and fast
+     *   bodies are more forgiving under a fixed step.
+     *
+     * A frame longer than `maxStep` is split into several equal steps rather than
+     * simulated in one lump, up to `maxSubSteps`; beyond that the excess time is
+     * dropped instead of letting the world explode or spiral.
+     *
+     * @param {number} [maxStep=1/30] - Longest slice to simulate in one step
+     * @param {number} [maxSubSteps] - Max steps per process() call
+     * @returns {Physics} - this
+     */
+    setVariableTimeStep(maxStep?: number, maxSubSteps?: number): Physics;
+    /**
+     * @method getTimeStepMode
+     * @description Returns "fixed" or "variable".
+     * @returns {string}
+     */
+    getTimeStepMode(): string;
+    /**
+     * @method createBody
+     * @description Creates a body in the physics engine
+     * @param {string} type - The type of the body
+     * @param {Vector2} position - The position of the body
+     * @param {boolean} fixedRotation - Whether the body should have a fixed rotation
+     * @param {boolean} attachFixture - Whether the body should have a fixture
+     * @param {Vector2} fixtureSize - The size of the fixture
+     * @param {number} density - The density of the fixture
+     * @param {number} friction - The friction of the fixture
+     * @param {number} restitution - The restitution of the fixture
+     * @returns {Body} - The body
+     */
+    createBody(type: string, position?: Vector2, fixedRotation?: boolean, attachFixture?: boolean, fixtureSize?: Vector2, density?: number, friction?: number, restitution?: number): Body;
+    /**
+     * @method createDistanceJoint
+     * @description Connects two rigid bodies with a fixed-length rod between two
+     * world-space anchor points, or a damped spring toward that length when
+     * `frequencyHz` is set.
+     * @param {RigidBody} rigidBodyA
+     * @param {RigidBody} rigidBodyB
+     * @param {Object} [options] - `{ anchorA, anchorB, length, frequencyHz,
+     *   dampingRatio, collideConnected }`. `anchorA`/`anchorB` are world-space
+     *   pixel points; each defaults to its body's own center. `length` is in
+     *   pixels; it defaults to the current distance between the anchors.
+     * @returns {DistanceJoint}
+     */
+    createDistanceJoint(rigidBodyA: RigidBody, rigidBodyB: RigidBody, options?: any): DistanceJoint;
+    /**
+     * @method createRevoluteJoint
+     * @description Pins two rigid bodies together at a shared world-space point,
+     * like a hinge: a door, a pendulum arm, a see-saw. Set `enableMotor` to
+     * drive it toward a target angular speed instead of swinging freely.
+     * @param {RigidBody} rigidBodyA
+     * @param {RigidBody} rigidBodyB
+     * @param {Object} anchor - World-space pixel point both bodies pin to
+     * @param {Object} [options] - `{ enableMotor, motorSpeed, maxMotorTorque,
+     *   collideConnected }`
+     * @returns {RevoluteJoint}
+     */
+    createRevoluteJoint(rigidBodyA: RigidBody, rigidBodyB: RigidBody, anchor: any, options?: any): RevoluteJoint;
+    /**
+     * @method destroyJoint
+     * @description Removes a joint created by {@link Physics#createDistanceJoint}
+     * or {@link Physics#createRevoluteJoint}.
+     * @param {Joint} joint
+     */
+    destroyJoint(joint: Joint): void;
+    /**
+     * @method onCollisionEnter
+     * @description Registers a world-level listener called whenever any two
+     * fixtures start touching. Survives {@link Physics#clear}.
+     * @param {Function} callback - Called with (bodyA, bodyB, contact)
+     */
+    onCollisionEnter(callback: Function): void;
+    /**
+     * @method onCollisionExit
+     * @description Registers a world-level listener called whenever any two
+     * fixtures stop touching. Survives {@link Physics#clear}.
+     * @param {Function} callback - Called with (bodyA, bodyB, contact)
+     */
+    onCollisionExit(callback: Function): void;
+    /**
+     * @method process
+     * @description Advances the simulation by `dt` seconds, in whichever way the
+     * current time-step mode calls for. Call it once per frame.
+     * @param {number} dt - Seconds elapsed since the previous call
+     * @returns {number} - How many steps were simulated
+     */
+    process(dt: number): number;
+    /**
+     * @method _stepVariable
+     * @description Simulates the frame's own delta. Normally that is a single
+     * step of exactly `dt`, so physics advances in lock-step with rendering. Only
+     * an unusually long frame is divided, and only far enough to keep each slice
+     * within `maxTimeStep`.
+     * @param {number} dt
+     * @returns {number} - Steps taken
+     * @private
+     */
+    private _stepVariable;
+    /**
+     * @method _stepFixed
+     * @description Banks elapsed time and simulates as many constant-size slices
+     * as have accumulated, leaving the remainder for next frame.
+     * @param {number} dt
+     * @returns {number} - Steps taken
+     * @private
+     */
+    private _stepFixed;
+    /**
+     * @method getInterpolationAlpha
+     * @description How far the fixed-step simulation currently sits between its
+     * last completed step and the next one (0..1). Useful if you interpolate
+     * renderables between physics states. Always 0 in variable mode, where every
+     * frame already renders a freshly simulated position.
+     * @returns {number}
+     */
+    getInterpolationAlpha(): number;
+    /**
+     * @method clear
+     * @description Drops every body and starts a fresh world with the original
+     * gravity; use it when tearing a level down. Collision routing and any
+     * listeners added through onCollisionEnter/onCollisionExit are re-bound to
+     * the new world, so they keep working afterwards.
+     */
+    clear(): void;
+    /**
+     * @method getGravity
+     * @description Returns the gravity of the physics engine
+     * @returns {number} - The gravity of the physics engine
+     */
+    getGravity(): number;
+    /**
+     * @method getScale
+     * @description Returns the scale of the physics engine
+     * @returns {number} - The scale of the physics engine
+     */
+    getScale(): number;
+}
+/**
+ * @class Vector2
+ * @description Represents a 2D vector
+ * @param {number} x - The x coordinate of the vector
+ * @param {number} y - The y coordinate of the vector
+ */
+export class Vector2 {
+    constructor(x?: number, y?: number);
+    x: number;
+    y: number;
+    /**
+     * @method set
+     * @description Sets the x and y coordinates in place
+     * @param {number} x - The x coordinate
+     * @param {number} y - The y coordinate
+     * @returns {Vector2} - This vector
+     */
+    set(x: number, y: number): Vector2;
+    /**
+     * @method clone
+     * @description Returns a copy of the vector
+     * @returns {Vector2} - The cloned vector
+     */
+    clone(): Vector2;
+    /**
+     * @method equals
+     * @description Checks if the vector is equal to another vector
+     * @param {Vector2} other - The other vector
+     * @returns {boolean} - True if the vector is equal to the other vector
+     */
+    equals(other: Vector2): boolean;
+    /**
+     * @method getX
+     * @description Returns the x coordinate of the vector
+     * @returns {number} - The x coordinate of the vector
+     */
+    getX(): number;
+    /**
+     * @method getY
+     * @description Returns the y coordinate of the vector
+     * @returns {number} - The y coordinate of the vector
+     */
+    getY(): number;
+}
+/**
+ * @class Vector3
+ * @description Represents a 3D vector
+ * @param {number} x - The x coordinate of the vector
+ * @param {number} y - The y coordinate of the vector
+ * @param {number} z - The z coordinate of the vector
+ */
+export class Vector3 {
+    constructor(x?: number, y?: number, z?: number);
+    x: number;
+    y: number;
+    z: number;
+    /**
+     * @method set
+     * @description Sets the x, y and z coordinates in place
+     * @param {number} x - The x coordinate
+     * @param {number} y - The y coordinate
+     * @param {number} z - The z coordinate
+     * @returns {Vector3} - This vector
+     */
+    set(x: number, y: number, z: number): Vector3;
+    /**
+     * @method clone
+     * @description Returns a copy of the vector
+     * @returns {Vector3} - The cloned vector
+     */
+    clone(): Vector3;
+    /**
+     * @method equals
+     * @description Checks if the vector is equal to another vector
+     * @param {Vector3} other - The other vector
+     * @returns {boolean} - True if the vector is equal to the other vector
+     */
+    equals(other: Vector3): boolean;
+    /**
+     * @method getX
+     * @description Returns the x coordinate of the vector
+     * @returns {number} - The x coordinate of the vector
+     */
+    getX(): number;
+    /**
+     * @method getY
+     * @description Returns the y coordinate of the vector
+     * @returns {number} - The y coordinate of the vector
+     */
+    getY(): number;
+    /**
+     * @method getZ
+     * @description Returns the z coordinate of the vector
+     * @returns {number} - The z coordinate of the vector
+     */
+    getZ(): number;
+}
+import { World } from "./physics/index.js";

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

@@ -0,0 +1,53 @@
+export default Pool;
+/**
+ * @class Pool
+ * @description Generic object pool to avoid per-frame allocations for churny
+ * objects (bullets, particles, enemies). Provide a factory and an optional
+ * reset function; acquire reused objects and release them when done.
+ *
+ * @example
+ * const bullets = new Pool(() => new Bullet(), (b, x, y) => b.spawn(x, y), 50);
+ * const b = bullets.acquire(px, py);
+ * // later...
+ * bullets.release(b);
+ */
+declare class Pool {
+    /**
+     * @param {Function} factory - Creates a new pooled object
+     * @param {Function} [reset] - Called on acquire as reset(obj, ...args)
+     * @param {number} [initialSize] - Number of objects to pre-create
+     */
+    constructor(factory: Function, reset?: Function, initialSize?: number);
+    factory: Function;
+    reset: Function;
+    available: any[];
+    active: Set<any>;
+    /**
+     * @method acquire
+     * @description Returns a pooled object (reused or freshly created). Extra
+     * arguments are forwarded to the reset function.
+     * @returns {*} - The acquired object
+     */
+    acquire(...args: any[]): any;
+    /**
+     * @method release
+     * @description Returns an object to the pool.
+     * @param {*} obj - The object to release
+     */
+    release(obj: any): void;
+    /**
+     * @method releaseAll
+     * @description Returns every active object to the pool.
+     */
+    releaseAll(): void;
+    /**
+     * @member activeCount
+     * @description Number of currently-acquired objects.
+     */
+    get activeCount(): number;
+    /**
+     * @member size
+     * @description Total objects managed by the pool (active + available).
+     */
+    get size(): number;
+}

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

@@ -0,0 +1,68 @@
+export default PostEffects;
+declare namespace PostEffects {
+    /**
+     * @method grayscale
+     * @description Desaturates the image.
+     */
+    function grayscale(): PostEffect;
+    /**
+     * @method vignette
+     * @description Darkens the edges of the screen.
+     * @param {Object} [options] - { intensity = 0.5, radius = 0.75, softness = 0.45 }
+     */
+    function vignette(options?: any): PostEffect;
+    /**
+     * @method colorGrade
+     * @description Adjusts brightness, contrast and saturation.
+     * @param {Object} [options] - { brightness = 0, contrast = 1, saturation = 1 }
+     */
+    function colorGrade(options?: any): PostEffect;
+    /**
+     * @method chromaticAberration
+     * @description Splits the RGB channels toward the screen edges.
+     * @param {Object} [options] - { amount = 0.003 }
+     */
+    function chromaticAberration(options?: any): PostEffect;
+    /**
+     * @method scanlines
+     * @description Overlays horizontal scanlines.
+     * @param {Object} [options] - { intensity = 0.15, count = 480 }
+     */
+    function scanlines(options?: any): PostEffect;
+    /**
+     * @method crt
+     * @description Retro CRT look: barrel distortion, scanlines and edge vignette.
+     * @param {Object} [options] - { curvature = 4.0, scanlineIntensity = 0.2, vignette = 0.3 }
+     */
+    function crt(options?: any): PostEffect;
+    /**
+     * @method bloom
+     * @description Glow around bright areas (multi-pass).
+     * @param {Object} [options] - { threshold = 0.7, intensity = 1.0, spread = 1.0 }
+     */
+    function bloom(options?: any): BloomEffect;
+}
+/**
+ * @class BloomEffect
+ * @description Multi-pass bloom: extract bright pixels above a threshold, blur
+ * them with a separable Gaussian, then add the result back over the scene. Built
+ * via {@link PostEffects.bloom}.
+ */
+export class BloomEffect extends PostEffect {
+    constructor(options?: {});
+    threshold: any;
+    intensity: any;
+    spread: any;
+    /** @private */
+    private _threshold;
+    /** @private */
+    private _blurH;
+    /** @private */
+    private _blurV;
+    /** @private */
+    private _composite;
+    render(ctx: any): void;
+    /** @private */
+    private _bloomTex;
+}
+import { PostEffect } from "./PostProcessor.js";

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

@@ -0,0 +1,124 @@
+export default PostProcessor;
+/**
+ * @class PostProcessor
+ * @description Drives a chain of full-screen {@link PostEffect}s. The scene is
+ * rendered into a texture, then each effect is applied in sequence (ping-ponging
+ * between two render targets), and the final result is drawn to the screen.
+ *
+ * Created and managed by Emerald when you call `emerald.enablePostProcessing()`;
+ * you usually just add effects via `emerald.addPostEffect(PostEffects.bloom())`.
+ */
+declare class PostProcessor {
+    gl: WebGLRenderingContext;
+    effects: any[];
+    enabled: boolean;
+    /** @private */
+    private _quad;
+    /** @private */
+    private _rtA;
+    /** @private */
+    private _rtB;
+    /** @private */
+    private _temps;
+    /** @private */
+    private _width;
+    /** @private */
+    private _height;
+    /**
+     * @method _restoreGL
+     * @description Rebuilds the fullscreen quad, ping-pong render targets, and
+     * every effect's program after a WebGL context loss.
+     * @private
+     */
+    private _restoreGL;
+    /**
+     * @method addEffect
+     * @description Appends an effect to the chain.
+     * @param {PostEffect} effect
+     * @returns {PostProcessor} - this
+     */
+    addEffect(effect: PostEffect): PostProcessor;
+    /**
+     * @method removeEffect
+     * @description Removes an effect from the chain.
+     */
+    removeEffect(effect: any): this;
+    /**
+     * @method clear
+     * @description Removes all effects.
+     */
+    clear(): this;
+    /**
+     * @method hasEffects
+     * @returns {boolean} - Whether any enabled effects exist.
+     */
+    hasEffects(): boolean;
+    /** @private */
+    private _acquireTemp;
+    /**
+     * @method process
+     * @description Applies the effect chain, drawing the final image to the canvas.
+     * @param {WebGLTexture} sceneTexture - The rendered scene
+     * @param {number} width - Canvas width in pixels
+     * @param {number} height - Canvas height in pixels
+     * @param {number} time - Seconds (for time-based effects)
+     */
+    process(sceneTexture: WebGLTexture, width: number, height: number, time: number): void;
+    /**
+     * @method _blit
+     * @description Renders one effect program from `input` into `output` (null =
+     * screen), setting the standard uniforms.
+     * @private
+     */
+    private _blit;
+    /**
+     * @method dispose
+     * @description Frees the render targets owned by this processor.
+     */
+    dispose(): void;
+}
+/**
+ * @class PostEffect
+ * @description A single full-screen post-processing pass: a fragment shader that
+ * samples the previous pass (`uScene`) and writes the next image. The shader
+ * automatically has `vUV`, `uScene`, `uResolution`, and `uTime` available; add
+ * your own uniforms and set them with the `setUniforms` callback.
+ *
+ * @example
+ * const tint = new PostEffect("tint", `
+ *   uniform vec3 uTint;
+ *   void main() { gl_FragColor = texture2D(uScene, vUV) * vec4(uTint, 1.0); }
+ * `, { setUniforms: (gl, loc) => gl.uniform3f(loc("uTint"), 1.0, 0.8, 0.8) });
+ */
+export class PostEffect {
+    /**
+     * @param {string} name - A label (for debugging)
+     * @param {string} fragmentSource - Fragment shader body (declares void main)
+     * @param {Object} [options] - { setUniforms(gl, loc, ctx), enabled = true }
+     */
+    constructor(name: string, fragmentSource: string, options?: any);
+    name: string;
+    fragmentSource: string;
+    setUniforms: any;
+    enabled: boolean;
+    program: any;
+    /** @private */
+    private _locCache;
+    /** @private */
+    private _compile;
+    /**
+     * @method _restoreGL
+     * @description Drops the dead program/locations after a context loss so the
+     * next _compile builds fresh ones.
+     * @private
+     */
+    private _restoreGL;
+    loc(gl: any, name: any): any;
+    /**
+     * @method render
+     * @description Renders this effect from ctx.input into ctx.output. Override for
+     * multi-pass effects.
+     * @param {Object} ctx - Provided by the PostProcessor
+     */
+    render(ctx: any): void;
+}

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

@@ -0,0 +1,56 @@
+export default RenderTarget;
+/**
+ * @class RenderTarget
+ * @description An offscreen render surface: a framebuffer backed by a color
+ * texture (and an optional depth buffer). Bind it to render the scene (or a
+ * post-processing pass) into a texture instead of the screen. The resulting
+ * `texture` can then be sampled by another pass or drawn to the canvas.
+ *
+ * Used by the post-processing pipeline, but also useful on its own for
+ * minimaps, mirrors, render-to-texture effects, or picture-in-picture.
+ *
+ * @example
+ * const rt = new RenderTarget(512, 512);
+ * rt.bind();
+ * // ...draw...
+ * rt.unbind();
+ * // rt.texture now holds the rendered image
+ */
+declare class RenderTarget {
+    /**
+     * @param {number} width - Width in pixels
+     * @param {number} height - Height in pixels
+     * @param {Object} [options] - { depth = false, pixelart = false }
+     */
+    constructor(width: number, height: number, options?: any);
+    gl: WebGLRenderingContext;
+    width: number;
+    height: number;
+    depth: boolean;
+    pixelart: boolean;
+    framebuffer: WebGLFramebuffer;
+    texture: WebGLTexture;
+    depthBuffer: WebGLRenderbuffer;
+    /** @private */
+    private _allocate;
+    /**
+     * @method resize
+     * @description Resizes the surface (reallocating storage) if dimensions change.
+     */
+    resize(width: any, height: any): void;
+    /**
+     * @method bind
+     * @description Binds this framebuffer and sets the viewport to its full size.
+     */
+    bind(): void;
+    /**
+     * @method unbind
+     * @description Restores the default framebuffer (the canvas).
+     */
+    unbind(): void;
+    /**
+     * @method dispose
+     * @description Frees all GL resources held by this target.
+     */
+    dispose(): void;
+}