murow 0.0.72 → 0.1.1

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

@@ -20,11 +20,32 @@ export interface MeshInstanceHandle {
     readonly slot: number;
     readonly modelId: number;
     readonly skinned: boolean;
+    /** Source prefab id, or `null` if spawned from a raw model handle. */
+    readonly prefabId: string | null;
     setPosition(x: number, y: number, z: number): void;
     setRotation(x: number, y: number, z: number): void;
     setScale(x: number, y: number, z: number): void;
+    /**
+     * Set position WITHOUT GPU interpolation from the previous frame.
+     * Writes both PREV and CURR to the same value, so the next render
+     * produces no lerp slide. Use after teleports, network snapshot
+     * snaps, or any time the entity should appear at the new location
+     * immediately rather than smoothly moving toward it.
+     */
+    teleport(x: number, y: number, z: number): void;
+    /**
+     * Logical current position (what `setPosition` last wrote, not the interpolated render value).
+     * Returns a per-handle reusable tuple — do not retain across subsequent gets on the same handle.
+     */
+    readonly position: readonly [number, number, number];
+    /** Logical current rotation in radians. Reusable tuple; see `position`. */
+    readonly rotation: readonly [number, number, number];
+    /** Logical current scale. Reusable tuple; see `position`. */
+    readonly scale: readonly [number, number, number];
     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 {
@@ -41,9 +62,30 @@ 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;
+    /**
+     * Set position WITHOUT GPU interpolation from the previous frame.
+     * Writes both PREV and CURR to the same value, so the next render
+     * produces no lerp slide. Use after teleports, network snapshot
+     * snaps, or any time the entity should appear at the new location
+     * immediately.
+     */
+    teleport(x: number, y: number, z: number): void;
+    /**
+     * Logical current position (what `setPosition` last wrote, not the interpolated render value).
+     * Returns a per-handle reusable tuple — do not retain across subsequent gets on the same handle.
+     */
+    readonly position: readonly [number, number, number];
+    /** Logical current rotation in radians. Reusable tuple; see `position`. */
+    readonly rotation: readonly [number, number, number];
+    /** Logical current scale. Reusable tuple; see `position`. */
+    readonly scale: readonly [number, number, number];
     play?(name: string, opts?: PlayOptions): void;
     stop?(): void;
     readonly skinned: boolean;
+    /** Source prefab id, or `null` if spawned from a raw model handle. */
+    readonly prefabId: string | null;
+    /** Free this instance's renderer slot(s). Safe to call once per handle. */
+    destroy(): void;
 }
 export interface MeshInstanceOptions {
     /**
@@ -75,11 +117,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 +180,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 +219,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 +256,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 +317,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 +343,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.1.1",
   "description": "A lightweight TypeScript game engine for server-authoritative multiplayer games",
   "types": "dist/types/index.d.ts",
   "type": "module",
@@ -112,6 +112,11 @@
       "types": "./dist/webgpu/types/index.d.ts",
       "import": "./dist/webgpu/esm/index.js",
       "require": "./dist/webgpu/cjs/index.js"
+    },
+    "./netcode": {
+      "types": "./dist/netcode/types/index.d.ts",
+      "import": "./dist/netcode/esm/index.js",
+      "require": "./dist/netcode/cjs/index.js"
     }
   },
   "optionalDependencies": {