murow 0.0.72 → 0.0.73

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

@@ -25,6 +25,8 @@ export interface MeshInstanceHandle {
     setScale(x: number, y: number, z: number): void;
     play?(name: string, opts?: PlayOptions): void;
     stop?(): void;
+    /** Free this instance's renderer slot. Safe to call once per handle. */
+    destroy(): void;
 }
 /** A loaded glTF model — may contain multiple mesh parts that share a skeleton. */
 export interface GltfModel {
@@ -44,6 +46,8 @@ export interface InstanceHandle {
     play?(name: string, opts?: PlayOptions): void;
     stop?(): void;
     readonly skinned: boolean;
+    /** Free this instance's renderer slot(s). Safe to call once per handle. */
+    destroy(): void;
 }
 export interface MeshInstanceOptions {
     /**
@@ -75,11 +79,13 @@ export interface WebGPU3DRendererOptions extends Renderer3DOptions {
      */
     prefabs?: PrefabBucket3D;
     /**
-     * How many instances you intend to spawn. Used together with `prefabs` to
-     * size the skinned-instance budget. Ignored if `maxSkinnedInstances` is set
-     * explicitly. Defaults to `maxModels` when only `prefabs` is provided.
+     * Max distance (world units) at which skeletal animation is computed for
+     * skinned instances. Past this, instances still render but reuse their
+     * last bone matrices; their internal animation clocks keep ticking on
+     * CPU. See `renderer.setAnimationCullDistance` to change at runtime.
+     * Set to `Infinity` to disable. Default 50.
      */
-    maxInstances?: number;
+    animationCullDistance?: number;
 }
 export declare class WebGPU3DRenderer extends Base3DRenderer {
     private root;
@@ -136,12 +142,20 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
     private skinnedFreeList;
     private skinnedBatcher;
     private skinnedStaticDirty;
+    private skinnedStaticDV;
     private skinnedInstanceModelIds;
     private skinnedInstanceBoneOffsets;
     private skinnedAnimStates;
     private nextBoneOffset;
+    /** Reusable bone-offset blocks per skinIndex. Pushed on remove, popped on add. Indexed by skinIndex (low cardinality), so a Map of lists is fine. */
+    private freedBoneOffsets;
+    /** Per-bone-offset refcount. Linked multi-part instances share a block; freed when refcount hits 0. Indexed by boneOffset (< maxTotalBones). */
+    private boneOffsetRefcount;
+    /** Per-bone-offset skinIndex tag, so we can return the block to the right per-skin freelist on remove. */
+    private boneOffsetSkinIndex;
     private readonly maxSkinnedInstances;
     private readonly maxBonesPerSkin;
+    private animationCullDistanceSq;
     private rawSkinnedDynamicBuffer;
     private rawSkinnedStaticBuffer;
     private rawSkinnedUniformBuffer;
@@ -167,6 +181,30 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
      */
     onResize(callback: (width: number, height: number) => void): void;
     createCompute(name: string, options: ComputeOptions): ComputeBuilder;
+    /**
+     * Set the maximum distance (in world units) at which the renderer keeps
+     * computing skeletal animation. Skinned instances farther than this are
+     * still drawn, but with their last-computed bone matrices instead of
+     * fresh ones, which saves GPU compute work. Their internal animation
+     * clocks keep ticking on CPU, so when they come back into range they
+     * resume in sync.
+     *
+     * Lower values trade visual smoothness on distant characters for FPS.
+     * Pass `Infinity` to disable culling entirely (always animate).
+     *
+     * Safe to call any time; takes effect on the next frame.
+     *
+     * @param distance Max distance to animate at, in world units.
+     */
+    setAnimationCullDistance(distance: number): void;
+    /** Current animation cull distance (in world units). See `setAnimationCullDistance`. */
+    get animationCullDistance(): number;
+    /**
+     * Max skinned instances the renderer was sized for at construction.
+     * Independent budget from `maxInstances` since skinned characters use a
+     * separate set of GPU buffers. Read-only.
+     */
+    get maxSkinned(): number;
     /**
      * Create a flat grid mesh on the XZ plane at Y=0.
      *
@@ -180,6 +218,18 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
         step?: number;
         lineWidth?: number;
     }): ModelHandle;
+    /**
+     * Create a unit-cube mesh centered at the origin. Pass `size` to scale the
+     * edge length, or keep size = 1 and scale at the instance level.
+     *
+     * ```ts
+     * const cube = renderer.createCube();
+     * renderer.addInstance({ model: cube, color: [1, 0.5, 0.2], scale: 2 });
+     * ```
+     */
+    createCube(opts?: {
+        size?: number;
+    }): ModelHandle;
     /**
      * Register a model. Returns a handle for addInstance().
      *
@@ -229,6 +279,13 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
      */
     addInstance(opts: MeshInstanceOptions): InstanceHandle;
     private addGltfInstance;
+    /**
+     * Spawn a composite prefab by spawning each of its parts at the composed
+     * (instance + offset) transform. The returned handle broadcasts subsequent
+     * `setPosition` / `setRotation` to every child, keeping each child's
+     * baked offset applied on top of the new value.
+     */
+    private addCompositeInstance;
     private addSkinnedInstance;
     /**
      * Drain pending resyncs from the coordinator. Per affected skin: rebuild
@@ -248,8 +305,19 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
      * Update skeletal animations for all skinned instances. Call once per tick.
      */
     private updatedBoneOffsets;
+    /**
+     * Returns true if a skinned instance's bone-matrix compute should be
+     * dispatched this frame. Combines frustum culling (scaled bounding sphere)
+     * and a configurable distance cull from the camera. Callers pass the
+     * camera position + cullDistSq once outside the loop to avoid re-reading.
+     */
+    private shouldDispatchSkinning;
     private updateAnimations;
-    removeInstance(handle: MeshInstanceHandle): void;
+    /**
+     * Free an instance's renderer slot. Equivalent to `handle.destroy()` -
+     * kept as a convenience for direct lookup. Safe to call multiple times.
+     */
+    removeInstance(handle: InstanceHandle): void;
     storePreviousState(): void;
     render(alpha: number): void;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "murow",
-  "version": "0.0.72",
+  "version": "0.0.73",
   "description": "A lightweight TypeScript game engine for server-authoritative multiplayer games",
   "types": "dist/types/index.d.ts",
   "type": "module",