retiam 0.0.0-stage → 1.0.0

package/dist/src/engine/_core/SceneInterface.d.ts

@@ -0,0 +1,55 @@
+import { RenderView } from '../camera/RenderView';
+import { GeometryComponent } from '../components/GeometryComponent';
+import { FragmentComponent } from '../components/FragmentComponent';
+import { RendererComponent } from '../components/RendererComponent';
+import { ComputeCommand } from '../compute/Compute';
+import { Entity } from './Entity';
+import { State } from './State';
+import { AABB } from '../math/AABB';
+import { RenderConfig } from '../render/RenderConfig';
+export interface SceneConfig {
+    width: number;
+    height: number;
+    clear_color: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /** Set to false to retain the previous frame's pixels. Defaults to true. */
+    autoClear?: boolean;
+    /** Normalized region [0.0 - 1.0] representing the area that will NOT be cleared. */
+    preserveArea?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface RenderCommand {
+    entity: Entity;
+    renderer: RendererComponent;
+    geometry: GeometryComponent;
+    fragment: FragmentComponent;
+    state: State;
+    stateIndex?: number;
+    state_bindgroup?: {
+        bindGroup: GPUBindGroup;
+        dynamicOffset: number;
+        offsets?: [number, number, number];
+    };
+    zIndex: number;
+    scissorBox?: AABB;
+    sortDepth?: number;
+    sortIndex?: number;
+}
+export interface SceneData {
+    texture: GPUTexture;
+    views: RenderView[];
+    render_queue: RenderCommand[];
+    compute_queue: ComputeCommand[];
+    config: SceneConfig;
+    renderConfig: RenderConfig;
+    isMoving: boolean;
+    accumulatedFrames: number;
+}

package/dist/src/engine/_core/SnapshotManager.d.ts

@@ -0,0 +1,56 @@
+import { Scene } from './Scene';
+export interface EntitySnapshot {
+    id: number;
+    visibility: boolean;
+    stateData: Float32Array;
+}
+export interface AnimationSnapshot {
+    type: string;
+    targetEntityId?: number;
+    elapsed: number;
+    duration: number;
+    delay: number;
+}
+export interface CameraSnapshot {
+    position: [number, number, number];
+    rotation: [number, number, number, number];
+    pitch: number;
+    yaw: number;
+    fov: number;
+    orthoScale: number;
+    aperture: number;
+    focusDist: number;
+    targetCenter?: [number, number, number];
+    targetRadius?: number;
+}
+export interface SceneSnapshot {
+    time: number;
+    label?: string;
+    camera: CameraSnapshot;
+    entities: EntitySnapshot[];
+    animations: AnimationSnapshot[];
+    isPaused: boolean;
+}
+/**
+ * Manages deterministic scene state checkpoints and snapshots.
+ * Allows instant restoration to user-defined checkpoint milestones during timeline seeking.
+ */
+export declare class SnapshotManager {
+    private snapshots;
+    /**
+     * Captures a complete, byte-accurate snapshot of the current scene state.
+     */
+    capture(scene: Scene, label?: string): SceneSnapshot;
+    /**
+     * Finds the latest checkpoint captured prior to or at targetTimeMs.
+     */
+    getLatestCheckpointBefore(targetTimeMs: number): SceneSnapshot | null;
+    /**
+     * Restores a scene instance to the exact state saved in a SceneSnapshot.
+     */
+    restore(scene: Scene, snapshot: SceneSnapshot): void;
+    /**
+     * Clears all stored checkpoints.
+     */
+    clear(): void;
+}

package/dist/src/engine/_core/State.d.ts

@@ -0,0 +1,106 @@
+import { Material } from './Material';
+import { Paint } from './Paint';
+import { Transform } from './Transform';
+/**
+ * Represents the unified styling, transform, and material state layout of an [[Entity]],
+ * mapped directly to a single contiguous GPU Float32 memory buffer block.
+ * Organizes sub-buffers: [[Paint]] (style/opacity), [[Transform]] (spatial location), and [[Material]] (shading).
+ */
+export declare class State {
+    /** Total byte length of a single state layout aligned to 16 bytes. */
+    static BYTELENGTH: number;
+    /** Total Float32 elements (fields) in the state buffer slice. */
+    static F32LENGTH: number;
+    /** Contiguous Float32 memory buffer block holding all state values. */
+    readonly data: Float32Array;
+    /** Aggregated Paint styling details instance. */
+    readonly paint: Paint;
+    /** Aggregated Transform spatial coordinates details instance. */
+    readonly transform: Transform;
+    /** Aggregated Material shading details instance. */
+    readonly material: Material;
+    /** Dynamic offset address mapping in WebGPU Uniform buffers [page number, slot index]. */
+    index: number[];
+    /**
+     * Creates a new State instance.
+     *
+     * @param data Optional pre-allocated Float32Array slice to map.
+     * @param copy If true, skip writing defaults.
+     */
+    constructor(data?: Float32Array, copy?: boolean);
+    /** General animation parameter / progress [0.0 - 1.0]. */
+    get t(): number;
+    set t(val: number);
+    /** Animation timeline start variable mapping. */
+    get t1(): number;
+    /** Animation timeline completion variable mapping. */
+    get t2(): number;
+    set t1(val: number);
+    set t2(val: number);
+    /** Sets local paint values. */
+    setPaint(paint: Paint): State;
+    /** Sets local transform values. */
+    setTransform(transform: Transform): State;
+    /** Sets local material values. */
+    setMaterial(material: Material): State;
+    static _globalVersion: number;
+    version: number;
+    get localVersion(): number;
+    /**
+     * Appends and evaluates a parent state layout combined with local overrides.
+     *
+     * @param state Child state overrides.
+     * @param state_in Parent state layout.
+     */
+    apply(state: State, state_in: State): void;
+    /** Size computation of the structure alignment in bytes. */
+    size(): number;
+    /** Flag all sub-buffers dirty, forcing VRAM updates. */
+    invalidate(): void;
+    /** Reset change update flags. */
+    updated(): void;
+    /** Copies raw Float data from another state. */
+    copyFrom(state: State): void;
+    /** Clones this State instance. */
+    copy(): State;
+    /** Synchronizes all paint, transform, and material values. */
+    set(state: State): void;
+    /** Explicit copy of raw floats. */
+    setData(state: State): State;
+    /** Applies a sequence of style/transform/material methods incrementally. */
+    applyMethods(methods: string[], ...args: any[]): State;
+    /**
+     * Inspects and executes a given paint/transform/material method by name.
+     *
+     * @param method Target method name.
+     * @param args Dynamic arguments list.
+     */
+    applyMethod(method: string, ...args: any[]): State;
+    /**
+     * Linearly interpolates between two state configurations over progress range [0.0 - 1.0].
+     *
+     * @param start Initial state.
+     * @param target Target state.
+     * @param t Progress interpolation factor.
+     * @param state Optional pre-allocated state to write results.
+     */
+    static interpolate(start: State, target: State, t: number, state?: State): State;
+    /**
+     * Analyzes and returns indices of fields that differ between start and target states.
+     * Used to optimize interpolations via selective masking.
+     *
+     * @param start Initial state.
+     * @param target Target state.
+     */
+    static getInterpolationMask(start: State, target: State): [number[], number[], number[]];
+    /**
+     * Performs interpolation only on the specified masked fields to optimize CPU overhead.
+     *
+     * @param mask Selected list of indices that differ.
+     * @param start Initial state.
+     * @param target Target state.
+     * @param t Progress factor.
+     * @param state Result destination state.
+     */
+    static interpolateWithMask(mask: [number[], number[], number[]], start: State, target: State, t: number, state?: State): State;
+}

package/dist/src/engine/_core/StateDataManager.d.ts

@@ -0,0 +1,61 @@
+import { State } from './State';
+/**
+ * GPU Buffer binding definitions for managing scene states.
+ */
+export interface UniformBuffer {
+    /** Layout representing global scene-level properties. */
+    global: GPUBufferBinding;
+    /** Layout representing individual entity states. */
+    state: GPUBufferBinding;
+}
+/**
+ * Unified state data manager backed by [[GlobalStateAllocator]].
+ * Manages continuous global storage buffer allocation for entity transforms, paints, and materials.
+ * @internal
+ */
+export declare class StateDataManager {
+    private allocator;
+    private device;
+    /**
+     * Creates a new StateDataManager.
+     *
+     * @param device Active GPUDevice.
+     * @param layout WebGPU Bind group layout descriptor.
+     */
+    constructor(device: GPUDevice, layout?: GPUBindGroupLayout);
+    /**
+     * Resets indices to start refilling from the beginning of the frame.
+     */
+    resetForNewFrame(): void;
+    /**
+     * Directly acquires the next pre-mapped State instance inside the GlobalStateAllocator.
+     * Any mutations on this State write directly into the storage buffer memory in-place (Zero-Copy).
+     *
+     * @param out Output object populated with stateIndex and globalBindGroup.
+     */
+    allocateDirect(out?: any): State;
+    /**
+     * Allocates a slot for an entity's State, copying data into the global storage buffer.
+     *
+     * @param state The entity's state to pack.
+     */
+    allocate(state: State, out?: {
+        stateIndex?: number;
+        bindGroup?: GPUBindGroup;
+        dynamicOffset?: number;
+        offsets?: [number, number, number];
+    }): {
+        stateIndex: number;
+        bindGroup: GPUBindGroup;
+        dynamicOffset: number;
+        offsets: [number, number, number];
+    };
+    /**
+     * Flushes all coalesced dirty state ranges to the GPU using command queue write operations.
+     */
+    uploadToGPU(): void;
+    /**
+     * Accessor for the global state bind group.
+     */
+    get globalBindGroup(): GPUBindGroup;
+}

package/dist/src/engine/_core/TextureManager.d.ts

@@ -0,0 +1,20 @@
+import { Entity } from './Entity';
+import { Renderer } from '../render/Renderer';
+/**
+ * Manages texture array synchronization between Scene entities and the Renderer.
+ */
+export declare class TextureManager {
+    texturesDirty: boolean;
+    videoDirty: boolean;
+    isBuildingTextures: boolean;
+    queuedTextureRebuild: boolean;
+    /**
+     * Checks if a texture array rebuild is needed and triggers non-blocking sync.
+     */
+    processPendingRebuild(entities: Entity[], renderer: Renderer, onInvalidate: () => void): void;
+    /**
+     * Traverses the scene graph to extract texture sources, passes them to the renderer,
+     * and maps the resulting GPU array indices back to entity materials.
+     */
+    syncTextureArrays(entities: Entity[], renderer: Renderer, isFullRebuild: boolean): Promise<void>;
+}

package/dist/src/engine/_core/Transform.d.ts

@@ -0,0 +1,344 @@
+import { Mat4 } from '../math/vector/Mat4';
+import { Quaternion } from '../math/vector/Quaternion';
+import { Vec3, Vec3Type } from '../math/vector/Vec3';
+import { TransformFunctions } from '../animation/AnimationFunctions';
+/**
+ * Represents the spatial transformation state of an [[Entity]], mapped directly to GPU-readable Float32 memory.
+ * Manages position, rotation, scaling, offsets, and timing variables (`t1`, `t2`) for animations.
+ */
+export declare class Transform implements TransformFunctions<Transform> {
+    /**
+     * Total byte length of a single transform structure in memory.
+     */
+    static BYTELENGTH: number;
+    /**
+     * Total number of Float32 elements (fields) in the raw buffer slice.
+     */
+    static F32LENGTH: number;
+    onChange?: () => void;
+    static _globalVersion: number;
+    private _updateFlag;
+    version: number;
+    /**
+     * Flag indicating whether the CPU-side data has changed and needs to be synchronized to the GPU.
+     */
+    get UPDATE_FLAG(): boolean;
+    set UPDATE_FLAG(val: boolean);
+    /**
+     * Buffer binding details for WebGPU alignment.
+     */
+    binding: GPUBufferBinding;
+    /**
+     * The raw Float32 array slice containing the transform matrix and variables.
+     */
+    readonly data: Float32Array;
+    /**
+     * The underlying 4x4 matrix mapping local space to parent/world space.
+     */
+    readonly _matrix: Mat4;
+    /**
+     * Local offset/anchor coordinate mapping.
+     */
+    readonly _offset: Vec3;
+    readonly _position: Vec3;
+    /**
+     * General animation progress/parameter variable slice (t) accessible in GPU shaders.
+     */
+    readonly _t: Float32Array;
+    /**
+     * Animation variable slice typically used for interpolations or drawing parameters (e.g., start time).
+     */
+    readonly _t1: Float32Array;
+    /**
+     * Animation variable slice typically used for interpolations or drawing parameters (e.g., completion time).
+     */
+    readonly _t2: Float32Array;
+    /**
+     * Bit mask field for entity categorization or state tracking.
+     */
+    readonly _bit_mask: Uint32Array;
+    /**
+     * Creates a new Transform instance mapped to a shared Float32Array slice.
+     *
+     * @param data The array slice representing this transform in memory.
+     * @param copy If true, skip setting default identity parameters.
+     */
+    constructor(data: Float32Array, copy?: boolean);
+    /**
+     * Initializes default values: matrix to identity, offset to zero, t1 to 0, and t2 to 1.
+     */
+    init(): void;
+    private bindMethods;
+    /**
+     * Gets or sets the local pivot offset (anchor point) of the entity.
+     */
+    get offset(): Vec3;
+    set offset(offset: Vec3Type);
+    /**
+     * Gets or sets the translation (position) components of the transformation matrix.
+     */
+    get position(): Vec3;
+    set position(p: Vec3Type);
+    /**
+     * Gets or sets the rotation component as a Quaternion.
+     */
+    get rotation(): Quaternion;
+    set rotation(q: Quaternion);
+    /**
+     * General animation parameter / progress [0.0 - 1.0] accessible in GPU shaders.
+     */
+    get t(): number;
+    set t(val: number);
+    /**
+     * The first animation variable (t1).
+     */
+    get t1(): number;
+    set t1(t: number);
+    /**
+     * The second animation variable (t2).
+     */
+    get t2(): number;
+    set t2(t: number);
+    get bit_mask(): number;
+    set bit_mask(bit_value: number);
+    /**
+     * Secondary metadata / custom state parameter (e.g. analytical contourStartIndex).
+     */
+    get pad2(): number;
+    set pad2(val: number);
+    get scaling(): Vec3;
+    set scaling(s: Vec3Type | number);
+    /** Reads the current X coordinate without allocating a Vec3 wrapper. */
+    get positionX(): number;
+    /** Sets the X coordinate without allocating a Vec3 wrapper. */
+    set positionX(x: number);
+    /** Reads the current Y coordinate without allocating a Vec3 wrapper. */
+    get positionY(): number;
+    /** Sets the Y coordinate without allocating a Vec3 wrapper. */
+    set positionY(y: number);
+    /** Reads the current Z coordinate without allocating a Vec3 wrapper. */
+    get positionZ(): number;
+    /** Sets the Z coordinate without allocating a Vec3 wrapper. */
+    set positionZ(z: number);
+    /**
+     * Returns the current position as a Vec3.
+     * Equivalent to the `position` getter but in method form for API symmetry.
+     */
+    getPosition(): Vec3;
+    /**
+     * Directly overwrites the position column in-place.
+     * Zero-allocations.
+     */
+    setPositionXYZ(x: number, y: number, z: number): Transform;
+    /**
+     * Directly compiles and overwrites the rotation matrix from a Quaternion.
+     * Preserves existing 3D reflections and scaling factors.
+     * Zero-allocations.
+     */
+    setRotationQuaternionXYZW(x: number, y: number, z: number, w: number): Transform;
+    /**
+     * Directly sets Euler rotations along X, Y, and Z axes (in radians).
+     */
+    setRotationXYZ(x: number, y: number, z: number): Transform;
+    /**
+     * Sets the general animation progress / parameter (t).
+     *
+     * @param t The animation parameter [0.0 - 1.0].
+     * @returns This Transform instance.
+     */
+    setT(t: number): Transform;
+    /**
+     * Sets the first animation variable (t1).
+     *
+     * @param t1 The animation start limit.
+     * @returns This Transform instance.
+     */
+    setT1(t1: number): Transform;
+    /**
+     * Sets the second animation variable (t2).
+     *
+     * @param t2 The animation end limit.
+     * @returns This Transform instance.
+     */
+    setT2(t2: number): Transform;
+    /**
+     * Sets the absolute translation coordinate.
+     */
+    move(p: Vec3Type): Transform;
+    /**
+     * Translates (shifts) the coordinate relative to its current orientation in local space.
+     *
+     * @param offset The distance vector to shift.
+     * @returns This Transform instance.
+     */
+    shift(offset: Vec3Type): Transform;
+    /**
+     * Translates (shifts) the coordinate relative to the world coordinate system.
+     *
+     * @param offset The distance vector to shift in world space.
+     * @returns This Transform instance.
+     */
+    shiftWorld(offset: Vec3Type): Transform;
+    /**
+     * Sets the absolute rotation of the matrix using a Quaternion, euler angles, or axis angle.
+     *
+     * @param angle Rotation angle details.
+     * @returns This Transform instance.
+     */
+    setRotation(angle: Quaternion | Vec3Type | number): Transform;
+    /**
+     * Returns the current rotation as a Quaternion.
+     * Equivalent to the `rotation` getter but in method form for API symmetry.
+     */
+    getRotation(): Quaternion;
+    /**
+     * @internal Accumulated Euler angle (radians) used internally by {@link setRotationX}.
+     * **Do not set this field directly** — doing so will desynchronize the quaternion.
+     * Use {@link setRotationX} instead.
+     */
+    rotation_x: number;
+    /**
+     * @internal Accumulated Euler angle (radians) used internally by {@link setRotationY}.
+     * **Do not set this field directly** — use {@link setRotationY} instead.
+     */
+    rotation_y: number;
+    /**
+     * @internal Accumulated Euler angle (radians) used internally by {@link setRotationZ}.
+     * **Do not set this field directly** — use {@link setRotationZ} instead.
+     */
+    rotation_z: number;
+    /**
+     * Sets rotation around the X-axis.
+     *
+     * @param angle Target angle in radians.
+     * @param anchor Optional local-space anchor to rotate around.
+     */
+    setRotationX(angle: number, anchor?: Vec3Type): Transform;
+    /**
+     * Sets rotation around the Y-axis.
+     *
+     * @param angle Target angle in radians.
+     * @param anchor Optional local-space anchor to rotate around.
+     */
+    setRotationY(angle: number, anchor?: Vec3Type): Transform;
+    /**
+     * Sets rotation around the Z-axis.
+     *
+     * @param angle Target angle in radians.
+     * @param anchor Optional local-space anchor to rotate around.
+     */
+    setRotationZ(angle: number, anchor?: Vec3Type): Transform;
+    /**
+     * Applies incremental local rotation.
+     *
+     * @param angle Incremental rotation details.
+     */
+    rotate(angle: Quaternion | Vec3Type | number, anchor?: Vec3Type): Transform;
+    /**
+     * Rotates the transform around its local X-axis.
+     *
+     * @param angle Angle to rotate in radians.
+     * @param anchor Optional local-space anchor to rotate around.
+     */
+    rotateX(angle: number, anchor?: Vec3Type): Transform;
+    /**
+     * Rotates the transform around its local Y-axis.
+     *
+     * @param angle Angle to rotate in radians.
+     * @param anchor Optional local-space anchor to rotate around.
+     */
+    rotateY(angle: number, anchor?: Vec3Type): Transform;
+    /**
+     * Rotates the transform around its local Z-axis.
+     *
+     * @param angle Angle to rotate in radians.
+     * @param anchor Optional local-space anchor to rotate around.
+     */
+    rotateZ(angle: number, anchor?: Vec3Type): Transform;
+    /**
+     * Applies incremental world rotation.
+     *
+     * @param angle Incremental rotation details in world space.
+     */
+    rotateWorld(angle: Quaternion | Vec3Type | number, anchorWorld?: Vec3Type): Transform;
+    /**
+     * Applies incremental world rotation around the X-axis.
+     * @param anchorWorld Optional world-space anchor to rotate around.
+     */
+    rotateWorldX(angle: number, anchorWorld?: Vec3Type): Transform;
+    /**
+     * Applies incremental world rotation around the Y-axis.
+     * @param anchorWorld Optional world-space anchor to rotate around.
+     */
+    rotateWorldY(angle: number, anchorWorld?: Vec3Type): Transform;
+    /**
+     * Applies incremental world rotation around the Z-axis.
+     * @param anchorWorld Optional world-space anchor to rotate around.
+     */
+    rotateWorldZ(angle: number, anchorWorld?: Vec3Type): Transform;
+    /**
+     * Sets absolute scale.
+     * Optionally scales around a specific local anchor point.
+     */
+    setScale(scale: Vec3Type | number, anchor?: Vec3Type): Transform;
+    /**
+     * Applies incremental scaling relative to local coordinates.
+     * Optionally scales around a specific local anchor point.
+     */
+    scale(factor: Vec3Type | number, anchor?: Vec3Type): Transform;
+    /**
+     * Applies incremental scaling relative to world axes.
+     * Optionally scales around a specific world-space anchor point.
+     */
+    scaleWorld(factor: Vec3Type | number, anchor?: Vec3Type): Transform;
+    /**
+     * Updates the offset to a new value, and counter-translates the matrix
+     * so that the absolute world position of the geometry remains perfectly stationary.
+     */
+    syncOffset(newOffset: Vec3Type): Transform;
+    /**
+     * Moves the local origin (offset) to the specified world coordinate,
+     * maintaining the object's exact visual position in the world.
+     * If the entity belongs to a parent hierarchy, pass the effective parent
+     * world matrix to correctly invert through all parent transformations.
+     *
+     * @param anchorWorld The world coordinate to become the new pivot.
+     * @param parentMatrix Optional parent effective world matrix.
+     */
+    setPivot(anchorWorld: Vec3Type, parentMatrix?: Mat4): Transform;
+    /**
+     * Returns the current offset as a Vec3.
+     * Equivalent to the `offset` getter but in method form for API symmetry.
+     */
+    getOffset(): Vec3;
+    /**
+     * Retrieves the scaling components of the transformation matrix as a Vec3.
+     */
+    getScale(): Vec3;
+    /** Reads the current X scale factor. Zero-allocations. */
+    getScaleX(): number;
+    /** Reads the current Y scale factor. Zero-allocations. */
+    getScaleY(): number;
+    /** Reads the current Z scale factor. Zero-allocations. */
+    getScaleZ(): number;
+    /**
+     * Returns the size (in bytes) of a single transform data layout.
+     */
+    static size(): number;
+    private static _scratchMat;
+    /**
+     * Combines a parent transform with a child transform.
+     * Correctly incorporates the parent's local offset into the hierarchical world matrix.
+     */
+    apply(childTransform: Transform, parentTransform: Transform): void;
+    /**
+     * Synchronizes raw data from another Transform instance.
+     *
+     * @param transform Source transform.
+     */
+    set(transform: Transform): void;
+    /**
+     * Clones this transform into a new separate memory buffer instance.
+     */
+    copy(): Transform;
+}

package/dist/src/engine/_core/UIManager.d.ts

@@ -0,0 +1,28 @@
+import { RenderView } from '../camera/RenderView';
+export interface PersistentRegion {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface UIConfig {
+    orthoScale?: number;
+    position?: [number, number, number];
+    clearDepth?: boolean;
+}
+/**
+ * Manages UI camera initialization and canvas persistence state.
+ */
+export declare class UIManager {
+    isPersistent: boolean;
+    persistentRegion?: PersistentRegion;
+    forceClearNext: boolean;
+    /**
+     * Initializes an orthographic camera dedicated to rendering UI layers over 3D scenes.
+     */
+    setupUICamera(uiView: RenderView | null, canvasWidth: number, canvasHeight: number, createViewFn: (w: number, h: number) => RenderView, config?: UIConfig): RenderView | null;
+    setPersistence(enable: boolean, onInvalidate: () => void): void;
+    setPersistentRegion(x: number, y: number, w: number, h: number, onInvalidate: () => void): void;
+    clearPersistentRegion(onInvalidate: () => void): void;
+    clearNextFrame(onInvalidate: () => void): void;
+}