emeraldengine 2.2.0 → 3.0.0

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

@@ -1,4 +1,3 @@
-import * as planck from "planck";
 /**
  * @class Physics
  * @description Represents the physics engine
@@ -6,11 +5,58 @@ import * as planck from "planck";
  * @param {number} scale - The scale of the physics engine
  * @param {number} velocityThreshold - The velocity threshold of the physics engine
  */
-declare class Physics {
+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: planck.World;
-    gravity: number;
-    scale: number;
-    constructor(gravity: number, scale: number, velocityThreshold?: number);
+    gravity: any;
+    scale: any;
+    fixedTimeStep: number;
+    maxSubSteps: number;
+    /** @private */
+    private _accumulator;
+    /**
+     * @method _dispatchContacts
+     * @description Routes planck contacts to the owning objects so Behaviour
+     * components receive onCollisionEnter/onCollisionExit. Bodies created through
+     * RigidBody carry the owner via userData.
+     * @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 Sets the fixed physics step (seconds) and optional substep cap.
+     * @param {number} step - Fixed step in seconds (e.g. 1/60)
+     * @param {number} [maxSubSteps] - Max steps per process() call (spiral guard)
+     */
+    setFixedTimeStep(step: number, maxSubSteps?: number): void;
     /**
      * @method createBody
      * @description Creates a body in the physics engine
@@ -24,19 +70,19 @@ declare class Physics {
      * @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): planck.Body;
+    createBody(type: string, position?: Vector2, fixedRotation?: boolean, attachFixture?: boolean, fixtureSize?: Vector2, density?: number, friction?: number, restitution?: number): Body;
     /**
      * @method onCollisionEnter
      * @description Handles the collision enter event
      * @param {Function} callback - The callback function to handle the collision enter event
      */
-    onCollisionEnter(callback: (bodyA: planck.Body, bodyB: planck.Body, contact: planck.Contact) => void): void;
+    onCollisionEnter(callback: Function): void;
     /**
      * @method onCollisionExit
      * @description Handles the collision exit event
      * @param {Function} callback - The callback function to handle the collision exit event
      */
-    onCollisionExit(callback: (bodyA: planck.Body, bodyB: planck.Body, contact: planck.Contact) => void): void;
+    onCollisionExit(callback: Function): void;
     /**
      * @method process
      * @description Processes the physics engine
@@ -60,12 +106,6 @@ declare class Physics {
      * @returns {number} - The scale of the physics engine
      */
     getScale(): number;
-    /**
-     * @method scheduleAction
-     * @description Schedules an action to be executed as soon as possible
-     * @param {Function} callback - The callback function to execute
-     */
-    static scheduleAction(callback: () => void): void;
 }
 /**
  * @class Vector2
@@ -73,10 +113,24 @@ declare class Physics {
  * @param {number} x - The x coordinate of the vector
  * @param {number} y - The y coordinate of the vector
  */
-declare class Vector2 {
+export class Vector2 {
+    constructor(x?: number, y?: number);
     x: number;
     y: number;
-    constructor(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
@@ -104,11 +158,26 @@ declare class Vector2 {
  * @param {number} y - The y coordinate of the vector
  * @param {number} z - The z coordinate of the vector
  */
-declare class Vector3 {
+export class Vector3 {
+    constructor(x?: number, y?: number, z?: number);
     x: number;
     y: number;
     z: number;
-    constructor(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
@@ -135,5 +204,4 @@ declare class Vector3 {
      */
     getZ(): number;
 }
-export { Physics, Vector2, Vector3 };
-//# sourceMappingURL=Physics.d.ts.map
+import * as planck from "planck";

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

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

@@ -0,0 +1,62 @@
+export default Scene;
+/**
+ * @class Scene
+ * @description Represents a scene
+ * @param {Array} objects - The objects in the scene
+ */
+declare class Scene {
+    constructor(objects?: any[]);
+    objects: any[];
+    /**
+     * @method add
+     * @description Adds an object to the scene
+     * @param {GameObject} object - The object to add
+     */
+    add(object: GameObject): void;
+    /**
+     * @method remove
+     * @description Removes an object from the scene. By default the object's GPU
+     * resources stay alive so it can be re-added later; pass { dispose: true }
+     * to also destroy it (free GL buffers/textures, physics bodies) when it is
+     * being removed for good.
+     * @param {GameObject} object - The object to remove
+     * @param {Object} [options] - { dispose = false }
+     */
+    remove(object: GameObject, options?: any): void;
+    /**
+     * @method dispose
+     * @description Destroys every object in the scene (freeing their GPU
+     * resources and physics bodies) and empties it. Call when a level/screen is
+     * torn down for good — removing objects without disposing leaks GL buffers
+     * over repeated scene swaps.
+     */
+    dispose(): void;
+    /**
+     * @method update
+     * @description Ticks every active object's component lifecycle. Call once per
+     * frame (before or after drawScene) to drive Behaviour components.
+     * @param {number} deltaTime - Seconds since the previous frame
+     */
+    update(deltaTime: number): void;
+    /**
+     * @method setIsActive
+     * @description Sets the active state of the scene
+     * @param {boolean} bool - The active state
+     */
+    setIsActive(bool: boolean): void;
+    /**
+     * @method setActiveRecursive
+     * @description Sets the active state of the scene recursively
+     * @param {Object} object - The object to set the active state of
+     * @param {boolean} bool - The active state
+     */
+    setActiveRecursive(object: any, bool: boolean): void;
+    forEach(callback: any): void;
+    [Symbol.iterator](): {
+        next: () => {
+            value: any;
+            done: boolean;
+        };
+    };
+}
+import GameObject from "./components/GameObject.js";

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

@@ -0,0 +1,111 @@
+export default ScreenEffects;
+/**
+ * @class ScreenEffects
+ * @description In-engine full-screen camera/transition effects: fade to/from a
+ * color, screen flash, and cinematic letterbox bars. Everything is drawn with
+ * the engine's own screen-space quads (no DOM/CSS overlay), so it survives
+ * resolution changes, post-processing, and split-screen (the quads overfill
+ * every viewport and are clipped per camera).
+ *
+ * Add it to your scene's update loop by calling `update(dt)` each frame.
+ *
+ * @example
+ * const fx = new ScreenEffects(scene, { layer: 100000 });
+ * await fx.fadeOut(0.4, new Color(0,0,0,255));  // to black
+ * loadNextLevel();
+ * await fx.fadeIn(0.4);
+ * // bumps:
+ * fx.flash(new Color(255,255,255,255), 0.15);
+ * // in the loop, before drawScene: fx.update(dt);
+ */
+declare class ScreenEffects {
+    /**
+     * @param {Scene} scene - The scene to draw the overlays into
+     * @param {Object} [options] - { layer = 100000, size = 5000 }
+     */
+    constructor(scene: Scene, options?: any);
+    scene: Scene;
+    /** @private */
+    private _fade;
+    /** @private */
+    private _flashQuad;
+    /** @private */
+    private _barTop;
+    /** @private */
+    private _barBottom;
+    /** @private */
+    private _letterboxHeight;
+    /** @private */
+    private _letterboxTarget;
+    /** @private */
+    private _barHalf;
+    /** @private */
+    private _fadeAnim;
+    /** @private */
+    private _flashAnim;
+    /** @private */
+    private _makeQuad;
+    /** @private */
+    private _shapeOf;
+    /** @private */
+    private _setColor;
+    /**
+     * @method fadeOut
+     * @description Fades the screen to a solid color (opacity 0 -> 1).
+     * @param {number} duration - Seconds
+     * @param {Color} [color] - Target color (default black)
+     * @param {Function} [easing] - Easing function (default linear)
+     * @returns {Promise<void>} - Resolves when the fade completes
+     */
+    fadeOut(duration?: number, color?: Color, easing?: Function): Promise<void>;
+    /**
+     * @method fadeIn
+     * @description Fades the screen back in from the current overlay (opacity -> 0).
+     * @param {number} duration - Seconds
+     * @param {Function} [easing] - Easing function (default linear)
+     * @returns {Promise<void>}
+     */
+    fadeIn(duration?: number, easing?: Function): Promise<void>;
+    /** @private */
+    private _startFade;
+    /**
+     * @method flash
+     * @description Flashes a color that ramps to full then fades out.
+     * @param {Color} [color] - Flash color (default white)
+     * @param {number} duration - Total seconds for the flash
+     * @returns {Promise<void>}
+     */
+    flash(color?: Color, duration?: number): Promise<void>;
+    /**
+     * @method transition
+     * @description Fades the screen out to a color, runs a swap callback at the
+     * darkest point (e.g. tear down the old scene and build the new one), then
+     * fades back in. Requires `update(dt)` to be pumped each frame by your loop.
+     * @param {Function} swap - Called (and awaited) while the screen is covered
+     * @param {Object} [options] - { duration = 0.4, color = black, outDuration,
+     *   inDuration, easing }
+     * @returns {Promise<void>} - Resolves after the fade-in completes
+     */
+    transition(swap: Function, options?: any): Promise<void>;
+    /**
+     * @method setLetterbox
+     * @description Animates cinematic black bars to the given height (in pixels,
+     * per bar). Pass 0 to retract them.
+     * @param {number} heightPx - Target bar height in pixels
+     */
+    setLetterbox(heightPx: number): void;
+    /**
+     * @method update
+     * @description Advances all active transitions. Call once per frame.
+     * @param {number} dt - Seconds since last frame
+     */
+    update(dt: number): void;
+    /** @private */
+    private _screenHalfHeight;
+    /**
+     * @method destroy
+     * @description Removes all overlay objects from the scene.
+     */
+    destroy(): void;
+}
+import Color from "./Color.js";