rapid-render 0.1.21 → 1.0.0

package/dist/matrix-engine.d.ts

@@ -0,0 +1,360 @@
+import { DynamicArrayBuffer } from './buffer';
+import { Vec2 } from './math';
+import { Rapid } from './render';
+export interface ITransformOptions {
+    /** Whether to push a save before applying transforms. Default: true. */
+    saveTransform?: boolean;
+    /** Called immediately after the save (if any). */
+    afterSave?: () => void;
+    x?: number;
+    y?: number;
+    position?: Vec2;
+    rotation?: number;
+    scale?: Vec2 | number;
+    offsetX?: number;
+    offsetY?: number;
+    offset?: Vec2;
+    /** Normalized anchor point (0~1). Number applies uniformly; Vec2 applies per-axis. */
+    origin?: number | Vec2;
+}
+/**
+ * A highly optimized store for a collection of 2D 3x3 matrices (stored as 6 elements: a, b, c, d, tx, ty).
+ * Matrices are stored flat in a dynamic Float32Array to improve memory locality and cache performance.
+ */
+export declare class MatrixStore {
+    /** Total number of matrices currently allocated in the store. */
+    matrixCount: number;
+    /** The dynamic buffer used to hold matrix data. */
+    buffer: DynamicArrayBuffer;
+    /** The raw floating-point data of all matrices. */
+    data: Float32Array;
+    /**
+     * Creates a new MatrixStore.
+     * @param capacity - The initial capacity of the matrix store (default is 10).
+     */
+    constructor(capacity?: number);
+    /**
+     * Allocates a new matrix and initializes it to the identity matrix.
+     * @returns The index of the newly allocated matrix.
+     */
+    alloc(): number;
+    /**
+     * Allocates a new matrix without initializing its elements.
+     * @returns The index of the newly allocated matrix.
+     */
+    allocDirty(): number;
+    /**
+     * Resets the store, clearing all allocated matrices.
+     */
+    reset(): void;
+    /**
+     * Sets the matrix at the given index to the identity matrix.
+     * @param index - The index of the matrix to modify.
+     */
+    identity(index: number): void;
+    /**
+     * Translates the matrix at the given index by x and y.
+     * @param index - The index of the matrix to modify.
+     * @param x - The x translation.
+     * @param y - The y translation.
+     */
+    translate(index: number, x: number, y: number): void;
+    /**
+     * Scales the matrix at the given index by scaleX and scaleY.
+     * @param index - The index of the matrix to modify.
+     * @param scaleX - The scale factor along the x-axis.
+     * @param scaleY - The scale factor along the y-axis.
+     */
+    scale(index: number, scaleX: number, scaleY: number): void;
+    /**
+     * Rotates the matrix at the given index by the specified radians.
+     * @param index - The index of the matrix to modify.
+     * @param radians - The rotation angle in radians.
+     */
+    rotate(index: number, radians: number): void;
+    /**
+     * Rotates the matrix at the given index around a local offset point (pivot).
+     *
+     * This is equivalent to:
+     * 1. Translating by `(offsetX, offsetY)` to move the pivot to the origin.
+     * 2. Rotating by `radians`.
+     * 3. Translating back by `(-offsetX, -offsetY)`.
+     *
+     * Useful for rotating a sprite around a point other than its own origin,
+     * e.g. a character's limb rotating around its joint.
+     *
+     * @param index   - The index of the matrix to modify.
+     * @param radians - The rotation angle in radians.
+     * @param offsetX - The x component of the pivot point in local space.
+     * @param offsetY - The y component of the pivot point in local space.
+     */
+    rotateWithOffset(index: number, radians: number, offsetX: number, offsetY: number): void;
+    /**
+     * Copies the elements from the source matrix to the destination matrix.
+     * @param dst - The index of the destination matrix.
+     * @param src - The index of the source matrix.
+     */
+    copy(dst: number, src: number): void;
+    /**
+     * Multiplies the destination matrix by the source matrix and stores the result in the destination.
+     * @param dst - The index of the destination matrix.
+     * @param src - The index of the source matrix.
+     */
+    multiply(dst: number, src: number): void;
+    /**
+     * Multiplies matrix A by matrix B and stores the result in the output matrix.
+     * @param out - The index of the output matrix.
+     * @param aIdx - The index of matrix A.
+     * @param bIdx - The index of matrix B.
+     */
+    multiplyOut(out: number, aIdx: number, bIdx: number): void;
+    /**
+     * Inverts the matrix at the given index. If the matrix is not invertible, it defaults to the identity matrix.
+     * @param index - The index of the matrix to invert.
+     */
+    invert(index: number): void;
+    /**
+     * Transforms a point by the matrix at the given index.
+     * @param index - The index of the transformation matrix.
+     * @param x - The x coordinate of the point.
+     * @param y - The y coordinate of the point.
+     * @returns The transformed point {x, y}.
+     */
+    transformPoint(index: number, x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Transforms a point from world coordinates to local coordinates using the matrix at the specified index.
+     * Useful for hit testing against objects placed in world space.
+     * @param index - The index of the world transformation matrix.
+     * @param x - World x coordinate.
+     * @param y - World y coordinate.
+     * @returns The transformed point in local coordinates.
+     */
+    worldToLocal(index: number, x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Transforms a point from local coordinates to world coordinates.
+     * @param index - The index of the local transformation matrix.
+     * @param x - Local x coordinate.
+     * @param y - Local y coordinate.
+     * @returns The transformed point in world coordinates.
+     */
+    localToWorld(index: number, x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Extracts the global position (translation) from the matrix at the given index.
+     * @param index - The index of the matrix.
+     * @returns An object containing `x` and `y` global coordinates.
+     */
+    getPosition(index: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Extracts the global scale from the matrix at the given index.
+     * @param index - The index of the matrix.
+     * @returns An object containing `x` and `y` global scale factors.
+     */
+    getScale(index: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Extracts the global rotation (in radians) from the matrix at the given index.
+     * @param index - The index of the matrix.
+     * @returns The global rotation in radians.
+     */
+    getRotation(index: number): number;
+    /**
+     * Converts the matrix at the given index to a CSS matrix string.
+     * @param index - The index of the matrix.
+     * @param scaleX - Extra scale applied to the a/c/tx components (e.g. to convert logic pixels to CSS pixels).
+     * @param scaleY - Extra scale applied to the b/d/ty components.
+     * @returns A CSS matrix string.
+     */
+    toCSSMatrix(index: number, scaleX?: number, scaleY?: number): string;
+    /**
+     * Retrieves a copy of the 6 elements [a, b, c, d, tx, ty] for the matrix at the specified index.
+     * Note: This uses `slice` to return a new Float32Array instance, ensuring the original data remains safely isolated.
+     *
+     * @param index - The index of the matrix.
+     * @returns A new Float32Array containing the 6 elements of the matrix.
+     */
+    getMatrix(index: number): Float32Array;
+    /**
+     * Retrieves a direct reference (view) to the 6 elements [a, b, c, d, tx, ty] for the matrix at the specified index.
+     * Note: This uses `subarray`. Any modifications made to the returned array will directly affect the underlying MatrixStore data.
+     *
+     * @param index - The index of the matrix.
+     * @returns A Float32Array view pointing directly to the matrix's data in memory.
+     */
+    getMatrixRef(index: number): Float32Array;
+    /**
+     * Overwrites the matrix at the specified index with the provided 6 elements [a, b, c, d, tx, ty].
+     *
+     * @param index - The index of the matrix to modify.
+     * @param f - An array (Float32Array or standard number array) containing the 6 new elements.
+     */
+    setMatrix(index: number, f: Float32Array | number[]): void;
+}
+/**
+ * A highly performant MatrixStack useful for hierarchal scene graphs.
+ * Handles both local and world transformations automatically.
+ */
+export declare class MatrixStack {
+    /** The underlying store for matrices. */
+    matrix: MatrixStore;
+    /** The current step or depth in the transformation hierarchy. */
+    step: number;
+    /** Internal stack maintaining structural information. */
+    stack: DynamicArrayBuffer;
+    /** Records the world matrices generated at each step. */
+    stepWorldM: DynamicArrayBuffer;
+    /** Records actions (push/pop) taken during the traversal. */
+    stepAction: DynamicArrayBuffer;
+    /** Records the parent world matrix for each step (used by updateMatrix). */
+    stepParentM: DynamicArrayBuffer;
+    /** Buffer used during hierarchy traversal updates. */
+    parentStack: DynamicArrayBuffer;
+    /** The index of the current local matrix in the matrix store. */
+    curLocalM: number;
+    /** The index of the current world matrix in the matrix store. */
+    curWorldM: number;
+    rapid: Rapid;
+    /**
+     * Creates a new MatrixStack and initializes its state.
+     */
+    constructor(rapid: Rapid);
+    /**
+     * Saves the current matrix state and pushes it onto the stack.
+     * Equivalent to context.save().
+     * @returns The current step counter before saving.
+     */
+    save(): {
+        world: number;
+        local: number;
+        step: number;
+    };
+    /**
+     * Restores the matrix state from the top of the stack.
+     * Equivalent to context.restore().
+     */
+    restore(): void;
+    /**
+     * Evaluates and updates matrices from the given step. Used primarily for deferred transformation.
+     * @param step - The initial step to update matrices from.
+     */
+    updateMatrix(step: number | {
+        step: number;
+    }): void;
+    /**
+     * Translates the current local and world matrices by x and y.
+     * @param x - Translation along the x-axis.
+     * @param y - Translation along the y-axis.
+     */
+    translate(x: number, y: number): void;
+    /**
+     * Scales the current local and world matrices by scaleX and scaleY.
+     * @param scaleX - Scaling factor along the x-axis.
+     * @param scaleY - Scaling factor along the y-axis.
+     */
+    scale(scaleX: number, scaleY?: number): void;
+    /**
+     * Rotates the current local and world matrices by the given radians.
+     * @param radians - The rotation angle in radians.
+     */
+    rotate(radians: number): void;
+    /**
+     * Rotates the current local and world matrices around a pivot point
+     * that is offset from the matrix origin by `(offsetX, offsetY)`.
+     *
+     * This is a convenience wrapper around the common translate → rotate → translate-back
+     * pattern, avoiding manual coordinate juggling at the call site.
+     *
+     * @example
+     * ```ts
+     * // Rotate a 64×64 sprite around its centre
+     * stack.rotateWithOffset(angle, 32, 32);
+     * ```
+     *
+     * @param radians - The rotation angle in radians.
+     * @param offsetX - The x component of the pivot point in local space.
+     * @param offsetY - The y component of the pivot point in local space.
+     */
+    rotateWithOffset(radians: number, offsetX: number, offsetY: number): void;
+    /**
+     * Sets the current local and world matrices to the identity matrix.
+     */
+    identity(): void;
+    /**
+     * Resets the entire stack state context, clearing matrices and step actions.
+     */
+    reset(): void;
+    /**
+     * Transforms a point from local coordinates to world coordinates.
+     * Uses the current world matrix to apply the transformation.
+     * @param x - Local x coordinate.
+     * @param y - Local y coordinate.
+     * @returns The transformed point in world coordinates.
+     */
+    localToWorld(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Transforms a point from world coordinates to local coordinates.
+     * Useful for hit testing against objects placed in world space.
+     * @param x - World x coordinate.
+     * @param y - World y coordinate.
+     * @returns The transformed point in local coordinates.
+     */
+    worldToLocal(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Extracts the global position (translation) from the current world matrix.
+     * @returns An object containing `x` and `y` global coordinates.
+     */
+    getGlobalPosition(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Extracts the global scale from the current world matrix.
+     * @returns An object containing `x` and `y` global scale factors.
+     */
+    getGlobalScale(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Extracts the global rotation (in radians) from the current world matrix.
+     * @returns The global rotation in radians.
+     */
+    getGlobalRotation(): number;
+    toCSSMatrix(): string;
+    /**
+     * Returns the current world matrix as Float32Array [a, b, c, d, tx, ty].
+     */
+    getTransform(): Float32Array;
+    /**
+     * Directly overwrites the current world matrix with the given 6-element 2D transform.
+     */
+    setTransform(f: Float32Array): void;
+    transformPoint(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Applies a transform options object to the current matrix state.
+     * Optionally saves the matrix first (saveTransform defaults to true).
+     */
+    applyTransform(transform: ITransformOptions, width?: number, height?: number): void;
+}

package/dist/particle.d.ts

@@ -1,11 +1,126 @@
-import Rapid from "./render";
-import { IParticleOptions, ITransformOptions } from "./interface";
-import { Vec2 } from "./math";
+import { Color } from './color';
+import { Vec2 } from './math';
+import { Rapid } from './render';
+import { Texture } from './texture';
+export type ParticleAttributeTypes = number | Vec2 | Color;
 /**
- * Particle emitter for creating and managing particle systems
+ * Describes an animated attribute: it transitions from `start` to `end`
+ * over the particle's lifetime, optionally with a per-second damping factor.
  */
-export declare class ParticleEmitter {
+export interface ParticleAttribute<T extends ParticleAttributeTypes> {
+    /** Starting value (scalar, range tuple, or fixed value). */
+    start?: T | [T, T];
+    /** Ending value. Defaults to `start` if omitted (no change over time). */
+    end?: T | [T, T];
+    /**
+     * Multiplicative damping applied each second.
+     * e.g. 0.9 means the value is multiplied by 0.9^deltaTime every frame.
+     */
+    damping?: number;
+    /**
+     * Explicit per-second delta override. If omitted it is derived from
+     * start/end/lifetime automatically.
+     */
+    delta?: T;
+}
+/** Internal resolved state of one animated attribute. */
+export interface ParticleAttributeData<T extends ParticleAttributeTypes> {
+    value: T;
+    delta?: T;
+    damping?: number;
+}
+export declare enum ParticleShape {
+    POINT = "point",
+    CIRCLE = "circle",
+    RECT = "rect"
+}
+export interface IParticleAnimation {
+    /** Directional speed along the rotation axis (pixels/sec). */
+    speed?: ParticleAttribute<number> | number;
+    /** Rotation angle in radians. */
+    rotation?: ParticleAttribute<number> | number;
+    /** Uniform scale. */
+    scale?: ParticleAttribute<number> | number;
+    /** Tint color (0-255 components, uses engine Color class). */
+    color?: ParticleAttribute<Color> | Color;
+    /** Additive velocity vector (pixels/sec). */
+    velocity?: ParticleAttribute<Vec2> | Vec2;
+    /** Acceleration vector added to velocity each second (pixels/sec²). */
+    acceleration?: ParticleAttribute<Vec2> | Vec2;
+}
+export interface IParticleOptions {
+    /** Texture(s) to pick from. Pass a weighted tuple `[Texture, weight][]` for weighted random. */
+    texture: Texture | Texture[] | [Texture, number][];
+    /** Particle lifetime in seconds, or a [min, max] range. */
+    life: number | [number, number];
+    /** Animation / per-attribute configuration. */
+    animation: IParticleAnimation;
+    /** Emit shape. */
+    emitShape?: ParticleShape;
+    /** Radius used when emitShape === CIRCLE. */
+    emitRadius?: number;
+    /** Dimensions used when emitShape === RECT. */
+    emitRect?: {
+        width: number;
+        height: number;
+    };
+    /** Maximum simultaneous particles (default: unlimited). */
+    maxParticles?: number;
+    /** Particles emitted per second (continuous) or per interval (when emitTime > 0). */
+    emitRate?: number;
+    /**
+     * If > 0, particles are emitted in bursts every `emitTime` seconds
+     * rather than continuously.
+     */
+    emitTime?: number;
+    /** Whether particles are positioned relative to the emitter (default: true). */
+    localSpace?: boolean;
+    /** World-space position of the emitter (used when localSpace is false). */
+    position?: Vec2;
+    origin?: Vec2;
+}
+export declare class Particle {
+    private life;
+    private maxLife;
+    private texture;
+    private options;
+    private position;
+    private datas;
     private rapid;
+    constructor(rapid: Rapid, options: IParticleOptions);
+    private processAttribute;
+    private updateNumberAttribute;
+    private updateVec2Attribute;
+    private updateColorAttribute;
+    private updateAttributes;
+    private getDelta;
+    /**
+     * Updates particle state.
+     * @param deltaTime - Seconds elapsed since last frame
+     * @returns `true` while the particle is alive, `false` when it should be removed
+     */
+    update(deltaTime: number): boolean;
+    /**
+     * Renders the particle using the Rapid engine's matrixStack + drawSprite.
+     * The emitter is responsible for calling save/restore around a batch of particles.
+     */
+    render(): void;
+    private initializePosition;
+}
+/**
+ * Creates and manages a pool of Particle instances.
+ *
+ * @example
+ * ```ts
+ * const emitter = new ParticleEmitter(rapid, { ... });
+ * emitter.start();
+ *
+ * // inside your game loop:
+ * emitter.update(dt);
+ * emitter.render();
+ * ```
+ */
+export declare class ParticleEmitter {
     private particles;
     private options;
     private emitting;
@@ -13,61 +128,56 @@ export declare class ParticleEmitter {
     private emitRate;
     private emitTime;
     private emitTimeCounter;
+    /** Whether spawned particles are positioned in local emitter space (default: true). */
     localSpace: boolean;
+    /** World position of the emitter. Used for both local-space transform and world-space spawn offset. */
     position: Vec2;
+    private rapid;
+    gameObject?: unknown;
     /**
-     * Creates a new particle emitter
-     * @param rapid - The Rapid renderer instance
+     * Creates a new particle emitter.
+     * @param rapid   - The Rapid renderer instance
      * @param options - Emitter configuration options
      */
     constructor(rapid: Rapid, options: IParticleOptions);
+    /** Replaces the emitter's texture at runtime. */
+    setTexture(texture: Texture): void;
     /**
-     * Gets the transform options
-     */
-    getTransform(): ITransformOptions;
-    /**
-     * Sets particle emission rate
-     * @param rate - Particles per second
+     * Creates a new emitter sharing the same options object.
+     * Particle state is NOT copied.
      */
+    clone(): ParticleEmitter;
+    /** Sets particles-per-second emission rate (continuous mode). */
     setEmitRate(rate: number): void;
-    /**
-     * Sets time interval between emissions
-     * @param time - Time interval in seconds
-     */
+    /** Sets the burst interval in seconds (0 = continuous). */
     setEmitTime(time: number): void;
-    /**
-     * Starts emitting particles
-     */
+    /** Starts continuous particle emission. */
     start(): void;
-    /**
-     * Stops emitting new particles but allows existing ones to complete their lifecycle
-     */
+    /** Stops new particle emission; existing particles finish their lifecycle. */
     stop(): void;
-    /**
-     * Clears all particles and resets the emitter
-     */
+    /** Removes all particles and resets timers. */
     clear(): void;
     /**
-     * Emits specified number of particles
-     * @param count - Number of particles to emit
+     * Spawns `count` particles immediately.
+     * Respects `maxParticles` if set.
      */
     emit(count: number): void;
     /**
-     * Updates particle emitter state
-     * @param deltaTime - Time in seconds since last update
+     * Updates the emitter and all live particles.
+     * @param deltaTime - Seconds elapsed since last frame
      */
     update(deltaTime: number): void;
     /**
-     * Renders all particles
+     * Renders all live particles.
+     * In local-space mode the emitter's own transform is applied around the batch.
      */
     render(): void;
-    /**
-     * Gets current particle count
-     */
+    /** Returns the current number of live particles. */
     getParticleCount(): number;
+    /** Returns `true` if the emitter is running or still has live particles. */
+    isActive(): boolean;
     /**
-     * Checks if the particle emitter is active (has particles or is emitting)
+     * Convenience: emit `emitRate` particles in one shot (fire-and-forget burst).
      */
-    isActive(): boolean;
     oneShot(): void;
 }