murow 0.0.70 → 0.0.71

package/dist/webgpu/types/2d/animation.d.ts

@@ -0,0 +1,97 @@
+/**
+ * AnimationController — frame-by-frame spritesheet animation.
+ *
+ * Manages animation clips (sequences of sprite frames with per-frame durations)
+ * and updates sprite handles to show the current frame. Zero allocations in the
+ * update loop — all clip data is pre-allocated typed arrays.
+ *
+ * ECS-independent: works with any system that can call update() per entity.
+ *
+ * Usage:
+ * ```ts
+ * const anim = new AnimationController();
+ *
+ * const runClip = anim.loadClip({
+ *     name: 'run',
+ *     frames: [0, 1, 2, 3],
+ *     durations: [100, 100, 100, 100],
+ *     loop: true,
+ * });
+ *
+ * const state = anim.createState(runClip);
+ * // Each tick:
+ * anim.update(state, deltaTime, spriteHandle);
+ * ```
+ */
+export interface AnimationClip {
+    readonly id: number;
+    readonly name: string;
+    readonly frames: Uint16Array;
+    readonly durations: Float32Array;
+    readonly frameCount: number;
+    readonly totalDuration: number;
+    readonly loop: boolean;
+}
+export interface AnimationState {
+    clipId: number;
+    frame: number;
+    time: number;
+    speed: number;
+    playing: boolean;
+}
+export interface AnimationClipConfig {
+    name: string;
+    frames: number[];
+    durations: number[];
+    loop: boolean;
+}
+/**
+ * Minimal interface for what update() needs to set on a sprite.
+ * Matches SpriteAccessor but doesn't import it — stays decoupled.
+ */
+export interface Animatable {
+    setSpriteId?(id: number): void;
+}
+export declare class AnimationController {
+    private clips;
+    private clipsByName;
+    /**
+     * Register an animation clip. Returns the clip ID.
+     */
+    loadClip(config: AnimationClipConfig): number;
+    /**
+     * Get a clip by name.
+     */
+    getClipId(name: string): number;
+    /**
+     * Get a clip by ID.
+     */
+    getClip(id: number): AnimationClip;
+    /**
+     * Create a new animation state for an entity. This is the per-entity data
+     * that tracks playback progress. Store it however you like (flat array, component, etc).
+     */
+    createState(clipId: number, speed?: number, playing?: boolean): AnimationState;
+    /**
+     * Advance an animation state by deltaTime (in seconds).
+     * Returns the current sprite frame ID, or -1 if not playing.
+     * Zero allocations.
+     */
+    update(state: AnimationState, deltaTime: number): number;
+    /**
+     * Play a different clip on an existing state. Resets frame and time.
+     */
+    play(state: AnimationState, clipId: number, speed?: number): void;
+    /**
+     * Stop playback.
+     */
+    stop(state: AnimationState): void;
+    /**
+     * Resume playback.
+     */
+    resume(state: AnimationState): void;
+    /**
+     * Number of loaded clips.
+     */
+    get clipCount(): number;
+}

package/dist/webgpu/types/2d/renderer.d.ts

@@ -0,0 +1,55 @@
+import { Base2DRenderer } from 'murow/renderer/base-2d-renderer';
+import type { Renderer2DOptions, SpriteHandle, SpriteOptions, SpritesheetHandle, SpritesheetSource } from 'murow/renderer';
+import { Camera2D } from '../camera/camera-2d';
+import { GeometryBuilder, type GeometryOptions } from '../geometry/geometry-builder';
+import { ComputeBuilder, type ComputeOptions } from '../compute/compute-builder';
+export declare class WebGPU2DRenderer extends Base2DRenderer {
+    private root;
+    private _device;
+    private context;
+    private _format;
+    get device(): GPUDevice;
+    get format(): GPUTextureFormat;
+    private spriteLayout;
+    private textureLayout;
+    private dynamicData;
+    private staticData;
+    private freeList;
+    private batcher;
+    private staticDirty;
+    private dynamicBuffer;
+    private staticBuffer;
+    private uniformBuffer;
+    private slotIndexBuffer;
+    private slotIndexData;
+    private rawPipeline;
+    private rawSpriteBindGroup;
+    private rawTextureLayout;
+    private rawDynamicBuffer;
+    private rawStaticBuffer;
+    private rawUniformBuffer;
+    private rawSlotIndexBuffer;
+    private sheetBindGroups;
+    private sheets;
+    private nextSheetId;
+    readonly camera: Camera2D;
+    private uniformData;
+    private resizeObserver;
+    private resizeCallbacks;
+    constructor(canvas: HTMLCanvasElement, options: Renderer2DOptions);
+    init(): Promise<void>;
+    private setupResizeObserver;
+    /**
+     * Register a callback that fires when the canvas resizes.
+     * Receives the new width and height in physical pixels.
+     */
+    onResize(callback: (width: number, height: number) => void): void;
+    loadSpritesheet(source: SpritesheetSource): Promise<SpritesheetHandle>;
+    addSprite(opts: SpriteOptions): SpriteHandle;
+    removeSprite(sprite: SpriteHandle): void;
+    storePreviousState(): void;
+    createGeometry(name: string, options: GeometryOptions): GeometryBuilder;
+    createCompute(name: string, options: ComputeOptions): ComputeBuilder;
+    render(alpha: number): void;
+    destroy(): void;
+}

package/dist/webgpu/types/2d/shader.d.ts

@@ -0,0 +1,61 @@
+import * as d from 'typegpu/data';
+export declare function createSpriteLayout(maxSprites: number): import("typegpu").TgpuBindGroupLayout<{
+    uniforms: {
+        uniform: d.WgslStruct<{
+            viewProjection: d.Mat3x3f;
+            alpha: d.F32;
+            resolution: d.Vec2f;
+        }>;
+    };
+    dynamicInstances: {
+        storage: d.WgslArray<d.WgslStruct<{
+            prevX: d.F32;
+            prevY: d.F32;
+            currX: d.F32;
+            currY: d.F32;
+            prevRotation: d.F32;
+            currRotation: d.F32;
+        }>>;
+    };
+    staticInstances: {
+        storage: d.WgslArray<d.WgslStruct<{
+            scaleX: d.F32;
+            scaleY: d.F32;
+            uvMinX: d.F32;
+            uvMinY: d.F32;
+            uvMaxX: d.F32;
+            uvMaxY: d.F32;
+            layer: d.F32;
+            flipX: d.F32;
+            flipY: d.F32;
+            opacity: d.F32;
+            tintR: d.F32;
+            tintG: d.F32;
+            tintB: d.F32;
+            tintA: d.F32;
+        }>>;
+    };
+    slotIndices: {
+        storage: d.WgslArray<d.U32>;
+    };
+}>;
+export declare function createTextureLayout(): import("typegpu").TgpuBindGroupLayout<{
+    spriteTex: {
+        texture: d.WgslTexture2d<d.F32>;
+    };
+    spriteSampler: {
+        sampler: "filtering";
+    };
+}>;
+export type SpriteDataLayout = ReturnType<typeof createSpriteLayout>;
+export type SpriteTextureLayout = ReturnType<typeof createTextureLayout>;
+export declare function createSpriteVertex(spriteLayout: SpriteDataLayout, _textureLayout: SpriteTextureLayout): import("typegpu").TgpuVertexFn<{}, {
+    vUv: d.Vec2f;
+    vTint: d.Vec4f;
+    vOpacity: d.F32;
+}>;
+export declare function createSpriteFragment(_spriteLayout: SpriteDataLayout, textureLayout: SpriteTextureLayout): import("typegpu").TgpuFragmentFn<{
+    vUv: d.Vec2f;
+    vTint: d.Vec4f;
+    vOpacity: d.F32;
+}, d.Vec4f>;

package/dist/webgpu/types/2d/sprite-accessor.d.ts

@@ -0,0 +1,47 @@
+import type { SpriteHandle } from "murow/renderer/types";
+export declare class SpriteAccessor implements SpriteHandle {
+    private dynamicData;
+    private staticData;
+    private dynamicBase;
+    private staticBase;
+    private _slot;
+    private _sheetId;
+    private _onStaticDirty;
+    constructor(dynamicData: Float32Array, staticData: Float32Array, slot: number, sheetId: number, onStaticDirty: () => void);
+    get slot(): number;
+    get sheetId(): number;
+    get x(): number;
+    set x(v: number);
+    get y(): number;
+    set y(v: number);
+    get prevX(): number;
+    get prevY(): number;
+    get rotation(): number;
+    set rotation(v: number);
+    get prevRotation(): number;
+    /**
+     * Store current position/rotation as previous (called before tick).
+     */
+    storePrevious(): void;
+    get scaleX(): number;
+    set scaleX(v: number);
+    get scaleY(): number;
+    set scaleY(v: number);
+    get layer(): number;
+    set layer(v: number);
+    get flipX(): boolean;
+    set flipX(v: boolean);
+    get flipY(): boolean;
+    set flipY(v: boolean);
+    get opacity(): number;
+    set opacity(v: number);
+    get tintR(): number;
+    get tintG(): number;
+    get tintB(): number;
+    get tintA(): number;
+    setTint(r: number, g: number, b: number, a?: number): void;
+    get uvMinX(): number;
+    get uvMinY(): number;
+    get uvMaxX(): number;
+    get uvMaxY(): number;
+}

package/dist/webgpu/types/3d/gltf-skin-parser.d.ts

@@ -0,0 +1,101 @@
+export interface SkinData {
+    jointCount: number;
+    /** Node indices for each joint (into the glTF node array). */
+    jointNodeIndices: Uint16Array;
+    /** Inverse bind matrices — jointCount * 16 floats (column-major mat4). */
+    inverseBindMatrices: Float32Array;
+    /** Parent joint index for each joint (-1 for roots). Index into *this* joint list, not the node array. */
+    parentJointIndices: Int16Array;
+    /** World matrix of the skeleton root (non-joint ancestors of root joints). Column-major mat4, 16 floats. Null if identity. */
+    skeletonRootMatrix: Float32Array | null;
+}
+export interface AnimationChannel {
+    /** Index into the skin's joint list (not node index). */
+    jointIndex: number;
+    path: 'translation' | 'rotation' | 'scale';
+    timestamps: Float32Array;
+    /** vec3 for translation/scale, vec4 (quaternion xyzw) for rotation. */
+    values: Float32Array;
+    interpolation: 'LINEAR' | 'STEP';
+}
+export interface AnimationClipData {
+    name: string;
+    duration: number;
+    channels: AnimationChannel[];
+}
+export interface PrimitiveSkinAttributes {
+    /** Joint indices — vertexCount * 4. */
+    joints: Uint16Array;
+    /** Joint weights — vertexCount * 4. */
+    weights: Float32Array;
+}
+export type AccessorReader = (accessorIndex: number) => {
+    data: Float32Array | Uint16Array | Uint32Array | Uint8Array;
+    count: number;
+    elementSize: number;
+};
+/**
+ * Parse skin data from a glTF skin definition.
+ */
+export declare function parseSkin(gltf: any, skinIndex: number, getAccessorData: AccessorReader): SkinData;
+/**
+ * Parse animation clips that target joints in a skin.
+ */
+export declare function parseAnimations(gltf: any, skinData: SkinData, getAccessorData: AccessorReader): AnimationClipData[];
+/**
+ * Extract JOINTS_0 and WEIGHTS_0 from a glTF primitive.
+ * Returns null if the primitive has no skinning attributes.
+ */
+export declare function parsePrimitiveSkinAttributes(primitive: any, getAccessorData: AccessorReader): PrimitiveSkinAttributes | null;
+/**
+ * Get a node's local TRS as [tx, ty, tz, qx, qy, qz, qw, sx, sy, sz].
+ */
+export declare function getNodeTRS(node: any): Float32Array;
+/** Packed GPU-ready animation data for all skins/clips loaded so far. */
+export interface PackedAnimationData {
+    /** Flat channel descriptors: [jointIndex, pathAndInterp, keyframeCount, dataOffset] per channel */
+    channels: {
+        jointIndex: number;
+        pathAndInterp: number;
+        keyframeCount: number;
+        dataOffset: number;
+    }[];
+    /** Flat keyframe data: timestamps then values for each channel */
+    keyframeData: number[];
+    /** Clip descriptors: [channelStart, channelCount, duration, loop] */
+    clips: {
+        channelStart: number;
+        channelCount: number;
+        duration: number;
+        looping: number;
+    }[];
+    /** Per-skin entries */
+    skins: {
+        jointCount: number;
+        parentOffset: number;
+        topoOffset: number;
+        ibmOffset: number;
+        restTRSOffset: number;
+        skelRootMatIndex: number;
+        clipOffset: number;
+        jointLookupStart: number;
+    }[];
+    /** Flat parent joint indices (i32), all skins concatenated */
+    parentIndices: number[];
+    /** Flat topological order (u32), all skins concatenated */
+    topoOrder: number[];
+    /** Flat inverse bind matrices (mat4x4, 16 floats each), all skins concatenated */
+    ibmData: number[];
+    /** Flat rest pose TRS (10 floats per joint), all skins concatenated */
+    restTRS: number[];
+    /** Skeleton root matrices (16 floats each), one per skin */
+    skelRootMats: number[];
+    /** Per-joint channel lookup: [clipIdx * maxJoints * 2 + joint * 2] = (channelStart, channelCount) */
+    jointChannelLookup: number[];
+}
+export declare function createPackedAnimationData(): PackedAnimationData;
+/**
+ * Pack a skin + its animations into the flat GPU buffers.
+ * Returns the skin index within the packed data.
+ */
+export declare function packSkinAndAnimations(packed: PackedAnimationData, skinData: SkinData, clips: AnimationClipData[], gltfNodes: any[]): number;

package/dist/webgpu/types/3d/morph-animation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * MorphAnimation — keyframe-based vertex animation for 3D meshes.
+ *
+ * Stores multiple vertex position snapshots (morph targets) per model.
+ * Each instance has a float `morphTime` that determines which two keyframes
+ * to blend and by how much. The blending happens CPU-side by writing
+ * interpolated positions into the model's vertex buffer.
+ *
+ * This is simpler than GPU-side blending (no shader changes needed) and
+ * works well for small-to-medium meshes with few keyframes.
+ *
+ * Usage:
+ * ```ts
+ * const morph = new MorphAnimation();
+ *
+ * // Load keyframes (each is a flat Float32Array of positions)
+ * const clipId = morph.loadClip({
+ *     name: 'walk',
+ *     keyframes: [frame0Positions, frame1Positions, frame2Positions],
+ *     durations: [100, 100, 100],
+ *     loop: true,
+ * });
+ *
+ * const state = morph.createState(clipId);
+ *
+ * // Each tick: advance time, get interpolated positions
+ * morph.update(state, deltaTime, outputPositions);
+ * ```
+ */
+export interface MorphClip {
+    readonly id: number;
+    readonly name: string;
+    readonly keyframes: Float32Array[];
+    readonly durations: Float32Array;
+    readonly frameCount: number;
+    readonly totalDuration: number;
+    readonly loop: boolean;
+    readonly vertexCount: number;
+}
+export interface MorphState {
+    clipId: number;
+    time: number;
+    speed: number;
+    playing: boolean;
+}
+export interface MorphClipConfig {
+    name: string;
+    keyframes: Float32Array[];
+    durations: number[];
+    loop: boolean;
+}
+export declare class MorphAnimation {
+    private clips;
+    private clipsByName;
+    loadClip(config: MorphClipConfig): number;
+    getClipId(name: string): number;
+    getClip(id: number): MorphClip;
+    createState(clipId: number, speed?: number, playing?: boolean): MorphState;
+    /**
+     * Advance time and write interpolated vertex positions into `output`.
+     * Output must be a Float32Array of vertexCount * 3 floats.
+     * Zero allocations.
+     */
+    update(state: MorphState, deltaTime: number, output: Float32Array): void;
+    play(state: MorphState, clipId: number, speed?: number): void;
+    stop(state: MorphState): void;
+    resume(state: MorphState): void;
+    get clipCount(): number;
+}

package/dist/webgpu/types/3d/morph-animation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/webgpu/types/3d/renderer.d.ts

@@ -0,0 +1,216 @@
+import { Base3DRenderer } from 'murow/renderer/base-3d-renderer';
+import type { Renderer3DOptions } from 'murow/renderer/types';
+import { ComputeBuilder, type ComputeOptions } from '../compute/compute-builder';
+import { Camera3D } from '../camera/camera-3d';
+import { type PlayOptions } from './skeletal-animation';
+export interface ModelData {
+    positions: Float32Array;
+    normals?: Float32Array;
+    uvs?: Float32Array;
+    indices?: Uint16Array | Uint32Array;
+    texture?: ImageBitmap;
+}
+export interface ModelHandle {
+    readonly id: number;
+    readonly vertexCount: number;
+    readonly indexCount: number;
+    readonly skinned: boolean;
+}
+export interface MeshInstanceHandle {
+    readonly slot: number;
+    readonly modelId: number;
+    readonly skinned: boolean;
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+    play?(name: string, opts?: PlayOptions): void;
+    stop?(): void;
+}
+/** A loaded glTF model — may contain multiple mesh parts that share a skeleton. */
+export interface GltfModel {
+    readonly parts: ModelHandle[];
+    readonly totalVertexCount: number;
+    readonly skinned: boolean;
+    /** Animation clip names available on this model (empty if not skinned). */
+    readonly animations: string[];
+    /** Source URL this model was loaded from. */
+    readonly src: string;
+}
+/** Handle to a spawned instance (single primitive or multi-part glTF). */
+export interface InstanceHandle {
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+    play?(name: string, opts?: PlayOptions): void;
+    stop?(): void;
+    readonly skinned: boolean;
+}
+export interface MeshInstanceOptions {
+    model: ModelHandle | GltfModel;
+    x?: number;
+    y?: number;
+    z?: number;
+    rotX?: number;
+    rotY?: number;
+    rotZ?: number;
+    scaleX?: number;
+    scaleY?: number;
+    scaleZ?: number;
+    color?: [number, number, number];
+}
+export interface WebGPU3DRendererOptions extends Renderer3DOptions {
+    maxSkinnedInstances?: number;
+    maxBonesPerSkin?: number;
+}
+export declare class WebGPU3DRenderer extends Base3DRenderer {
+    private root;
+    private device;
+    private context;
+    private resizeObserver;
+    private resizeCallbacks;
+    private format;
+    private meshLayout;
+    private dynamicData;
+    private staticData;
+    private slotIndexData;
+    private freeList;
+    private batcher;
+    private staticDirty;
+    private instanceModelIds;
+    private dynamicBuffer;
+    private staticBuffer;
+    private uniformBuffer;
+    private slotIndexBuffer;
+    private rawPipeline;
+    private rawBindGroup;
+    private rawDynamicBuffer;
+    private rawStaticBuffer;
+    private rawUniformBuffer;
+    private rawSlotIndexBuffer;
+    private depthTexture;
+    private rawTexturedPipeline;
+    private models;
+    private nextModelId;
+    private skinnedModels;
+    private skinnedMeshLayout;
+    private rawSkinnedPipeline;
+    private rawSkinnedTexturedPipeline;
+    private rawSkinnedBindGroup;
+    private boneMatrixData;
+    private rawBoneMatrixBuffer;
+    private boneMatrixDirty;
+    private readonly maxTotalBones;
+    private packedAnimData;
+    private animComputeKernel;
+    private animComputeNeedsRebuild;
+    private animClipTableOffset;
+    private animChannelTableOffset;
+    private animJointLookupOffset;
+    private gpuAnimInstanceStates;
+    private gpuInstData;
+    private gpuInstDV;
+    private skinnedDynamicData;
+    private skinnedStaticData;
+    private skinnedSlotIndexData;
+    private skinnedFreeList;
+    private skinnedBatcher;
+    private skinnedStaticDirty;
+    private skinnedInstanceModelIds;
+    private skinnedInstanceBoneOffsets;
+    private skinnedAnimStates;
+    private nextBoneOffset;
+    private readonly maxSkinnedInstances;
+    private readonly maxBonesPerSkin;
+    private rawSkinnedDynamicBuffer;
+    private rawSkinnedStaticBuffer;
+    private rawSkinnedUniformBuffer;
+    private rawSkinnedSlotIndexBuffer;
+    private frustumPlanes;
+    readonly camera: Camera3D;
+    private uniformData;
+    private lastRenderTime;
+    constructor(canvas: HTMLCanvasElement, options: WebGPU3DRendererOptions);
+    init(): Promise<void>;
+    private setupResizeObserver;
+    /**
+     * Register a callback that fires when the canvas resizes.
+     * Receives the new width and height in physical pixels.
+     */
+    onResize(callback: (width: number, height: number) => void): void;
+    createCompute(name: string, options: ComputeOptions): ComputeBuilder;
+    /**
+     * Create a flat grid mesh on the XZ plane at Y=0.
+     *
+     * ```ts
+     * const grid = renderer.createGrid({ size: 20, step: 1, lineWidth: 0.005 });
+     * renderer.addInstance({ model: grid, color: [0.3, 0.3, 0.3] });
+     * ```
+     */
+    createGrid(opts?: {
+        size?: number;
+        step?: number;
+        lineWidth?: number;
+    }): ModelHandle;
+    /**
+     * Register a model. Returns a handle for addInstance().
+     *
+     * ```ts
+     * const hero = renderer.loadModel({
+     *     positions: new Float32Array([...]),
+     *     normals: new Float32Array([...]),  // optional — auto-computed from faces
+     *     uvs: new Float32Array([...]),       // optional
+     *     indices: new Uint16Array([...]),    // optional
+     *     texture: myImageBitmap,             // optional
+     * });
+     * ```
+     */
+    loadModel(data: ModelData): ModelHandle;
+    /**
+     * Register a skinned model with joint/weight vertex data.
+     * Called internally by loadGltf when a skin is detected.
+     */
+    private loadSkinnedModel;
+    /**
+     * Auto-compute flat normals from triangle faces.
+     */
+    private computeNormals;
+    /**
+     * Load a glTF/GLB model from a URL. Returns one ModelHandle per primitive.
+     * Most models have multiple primitives (body parts, material groups, etc.).
+     *
+     * ```ts
+     * const model = await renderer.loadGltf('assets/hero.glb');
+     * const instance = renderer.addInstance({ model, x: 0, y: 0, z: 0 });
+     * instance.playAnimation?.('walk');
+     * ```
+     */
+    loadGltf(url: string, opts?: {
+        animations?: string[];
+    }): Promise<GltfModel>;
+    /**
+     * Add an instance. For skinned models, pass `linkedTo` to share bone matrices
+     * with another instance (e.g., when spawning all parts of a character).
+     */
+    addInstance(opts: MeshInstanceOptions): InstanceHandle;
+    private addGltfInstance;
+    private addSkinnedInstance;
+    /**
+     * Update skeletal animations for all skinned instances. Call once per tick.
+     */
+    private updatedBoneOffsets;
+    private updateAnimations;
+    removeInstance(handle: MeshInstanceHandle): void;
+    storePreviousState(): void;
+    render(alpha: number): void;
+    /**
+     * Extract 6 frustum planes from a column-major VP matrix.
+     * Each plane is [a, b, c, d] where ax + by + cz + d >= 0 means inside.
+     */
+    private extractFrustumPlanes;
+    /**
+     * Test if a bounding sphere is inside or intersects the frustum.
+     * Returns true if visible (should be drawn).
+     */
+    private isInFrustum;
+    destroy(): void;
+}