murow 0.0.72 → 0.1.1

package/dist/webgpu/esm/index.js

@@ -3656,7 +3656,8 @@ var SSTAT_CB = 5;
 var SSTAT_BONE_OFFSET = 6;
 var prefabHandles = /* @__PURE__ */ new WeakMap();
 function isPrefab3D(value) {
-  return value.type === "gltf" || value.type === "grid";
+  const t = value.type;
+  return t === "gltf" || t === "grid" || t === "cube" || t === "composite";
 }
 function resolveTransform(opts) {
   const [px, py, pz] = opts.position ?? [0, 0, 0];
@@ -3690,8 +3691,8 @@ function computeBucketStats(bucket) {
 }
 var WebGPU3DRenderer = class extends Base3DRenderer {
   constructor(canvas, options) {
-    const resolvedMaxModels = options.maxModels ?? (options.prefabs ? options.prefabs.size + 16 : 32);
-    super(canvas, { ...options, maxModels: resolvedMaxModels });
+    const resolvedMaxInstances = options.maxInstances ?? (options.prefabs ? options.prefabs.size + 16 : 32);
+    super(canvas, { ...options, maxInstances: resolvedMaxInstances });
     this.resizeObserver = null;
     this.resizeCallbacks = [];
     // layer=0, sheetId=modelId
@@ -3717,6 +3718,8 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.skinnedStaticDirty = false;
     this.skinnedAnimStates = [];
     this.nextBoneOffset = 0;
+    /** Reusable bone-offset blocks per skinIndex. Pushed on remove, popped on add. Indexed by skinIndex (low cardinality), so a Map of lists is fine. */
+    this.freedBoneOffsets = /* @__PURE__ */ new Map();
     // Frustum planes (6 planes × 4 floats each), extracted from VP matrix
     this.frustumPlanes = new Float32Array(24);
     this.uniformData = new Float32Array(24);
@@ -3726,22 +3729,26 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this._prefabs = options.prefabs ?? null;
     const SKINNED_PARTS_PER_INSTANCE_DEFAULT_CAP = 3;
     const bucketStats = this._prefabs ? computeBucketStats(this._prefabs) : null;
-    const maxInstances = options.maxInstances ?? resolvedMaxModels;
-    this.maxSkinnedInstances = options.maxSkinnedInstances ?? (bucketStats ? maxInstances * Math.max(1, Math.min(bucketStats.maxSkinnedParts, SKINNED_PARTS_PER_INSTANCE_DEFAULT_CAP)) : 5e3);
+    this.maxSkinnedInstances = options.maxSkinnedInstances ?? (bucketStats ? resolvedMaxInstances * Math.max(1, Math.min(bucketStats.maxSkinnedParts, SKINNED_PARTS_PER_INSTANCE_DEFAULT_CAP)) : 5e3);
     this.maxBonesPerSkin = options.maxBonesPerSkin ?? (bucketStats ? Math.max(1, bucketStats.maxJointCount) : 64);
+    const cullDist = options.animationCullDistance ?? 50;
+    this.animationCullDistanceSq = cullDist * cullDist;
     this.maxTotalBones = this.maxSkinnedInstances * this.maxBonesPerSkin * 2;
     this.updatedBoneOffsets = new Uint8Array(this.maxTotalBones);
-    this.freeList = new FreeList3(resolvedMaxModels);
-    this.batcher = new SparseBatcher2(resolvedMaxModels);
-    this.dynamicData = new Float32Array(resolvedMaxModels * DYNAMIC_MESH_FLOATS);
-    this.staticData = new Float32Array(resolvedMaxModels * STATIC_MESH_FLOATS);
-    this.slotIndexData = new Uint32Array(resolvedMaxModels);
-    this.instanceModelIds = new Uint8Array(resolvedMaxModels);
+    this.boneOffsetRefcount = new Uint32Array(this.maxTotalBones);
+    this.boneOffsetSkinIndex = new Uint32Array(this.maxTotalBones);
+    this.freeList = new FreeList3(resolvedMaxInstances);
+    this.batcher = new SparseBatcher2(resolvedMaxInstances);
+    this.dynamicData = new Float32Array(resolvedMaxInstances * DYNAMIC_MESH_FLOATS);
+    this.staticData = new Float32Array(resolvedMaxInstances * STATIC_MESH_FLOATS);
+    this.slotIndexData = new Uint32Array(resolvedMaxInstances);
+    this.instanceModelIds = new Uint8Array(resolvedMaxInstances);
     const msi = this.maxSkinnedInstances;
     this.skinnedFreeList = new FreeList3(msi);
     this.skinnedBatcher = new SparseBatcher2(msi);
     this.skinnedDynamicData = new Float32Array(msi * DYNAMIC_MESH_FLOATS);
     this.skinnedStaticData = new Float32Array(msi * SKINNED_STATIC_MESH_FLOATS);
+    this.skinnedStaticDV = new DataView(this.skinnedStaticData.buffer);
     this.skinnedSlotIndexData = new Uint32Array(msi);
     this.skinnedInstanceModelIds = new Uint8Array(msi);
     this.skinnedInstanceBoneOffsets = new Uint32Array(msi);
@@ -3752,7 +3759,19 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.gpuInstDV = new DataView(this.gpuInstData.buffer);
   }
   async init() {
-    this.root = await tgpu6.init();
+    const adapter = await navigator.gpu.requestAdapter();
+    if (!adapter)
+      throw new Error("WebGPU3DRenderer: no GPU adapter available");
+    const a = adapter.limits;
+    const requiredLimits = {
+      maxBufferSize: a.maxBufferSize,
+      maxStorageBufferBindingSize: a.maxStorageBufferBindingSize,
+      maxStorageBuffersPerShaderStage: a.maxStorageBuffersPerShaderStage,
+      maxComputeWorkgroupStorageSize: a.maxComputeWorkgroupStorageSize,
+      maxComputeInvocationsPerWorkgroup: a.maxComputeInvocationsPerWorkgroup
+    };
+    const device = await adapter.requestDevice({ requiredLimits });
+    this.root = tgpu6.initFromDevice({ device });
     this.device = this.root.device;
     this.context = this.canvas.getContext("webgpu");
     this.format = navigator.gpu.getPreferredCanvasFormat();
@@ -3769,7 +3788,7 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       format: "depth24plus",
       usage: GPUTextureUsage.RENDER_ATTACHMENT
     });
-    this.meshLayout = createMeshLayout(this.maxModels);
+    this.meshLayout = createMeshLayout(this.maxInstances);
     const depthStencil = {
       format: "depth24plus",
       depthWriteEnabled: true,
@@ -3816,10 +3835,10 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       primitive,
       depthStencil
     });
-    this.dynamicBuffer = this.root.createBuffer(d.arrayOf(DynamicMesh, this.maxModels)).$usage("storage");
-    this.staticBuffer = this.root.createBuffer(d.arrayOf(StaticMesh, this.maxModels)).$usage("storage");
+    this.dynamicBuffer = this.root.createBuffer(d.arrayOf(DynamicMesh, this.maxInstances)).$usage("storage");
+    this.staticBuffer = this.root.createBuffer(d.arrayOf(StaticMesh, this.maxInstances)).$usage("storage");
     this.uniformBuffer = this.root.createBuffer(MeshUniforms).$usage("uniform");
-    this.slotIndexBuffer = this.root.createBuffer(d.arrayOf(d.u32, this.maxModels)).$usage("storage");
+    this.slotIndexBuffer = this.root.createBuffer(d.arrayOf(d.u32, this.maxInstances)).$usage("storage");
     this.rawDynamicBuffer = this.root.unwrap(this.dynamicBuffer);
     this.rawStaticBuffer = this.root.unwrap(this.staticBuffer);
     this.rawUniformBuffer = this.root.unwrap(this.uniformBuffer);
@@ -3921,6 +3940,9 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
           lineWidth: prefab.lineWidth
         });
         prefabHandles.set(prefab, model);
+      } else if (prefab.type === "cube") {
+        const model = this.createCube({ size: prefab.size });
+        prefabHandles.set(prefab, model);
       }
     }
   }
@@ -3985,6 +4007,36 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
   createCompute(name, options) {
     return new ComputeBuilder(name, options, this.root);
   }
+  /**
+   * 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) {
+    this.animationCullDistanceSq = distance * distance;
+  }
+  /** Current animation cull distance (in world units). See `setAnimationCullDistance`. */
+  get animationCullDistance() {
+    return Math.sqrt(this.animationCullDistanceSq);
+  }
+  /**
+   * 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() {
+    return this.maxSkinnedInstances;
+  }
   /**
    * Create a flat grid mesh on the XZ plane at Y=0.
    *
@@ -4016,6 +4068,245 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       indices: new Uint16Array(indices)
     });
   }
+  /**
+   * 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 = {}) {
+    const h = (opts.size ?? 1) / 2;
+    const positions = new Float32Array([
+      // +Z
+      -h,
+      -h,
+      h,
+      h,
+      -h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      h,
+      h,
+      // -Z
+      h,
+      -h,
+      -h,
+      -h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      h,
+      -h,
+      // +Y
+      -h,
+      h,
+      h,
+      h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      -h,
+      // -Y
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      -h,
+      -h,
+      h,
+      // +X
+      h,
+      -h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      h,
+      -h,
+      h,
+      -h,
+      h,
+      h,
+      h,
+      -h,
+      h,
+      h,
+      h,
+      // -X
+      -h,
+      -h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      h,
+      -h,
+      -h,
+      -h,
+      -h,
+      h,
+      h,
+      -h,
+      h,
+      -h
+    ]);
+    const normals = new Float32Array([
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0
+    ]);
+    return this.loadModel({ positions, normals });
+  }
   /**
    * Register a model. Returns a handle for addInstance().
    *
@@ -4331,18 +4622,22 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
    * with another instance (e.g., when spawning all parts of a character).
    */
   addInstance(opts) {
+    const userPrefabId = isPrefab3D(opts.model) ? opts.model.id : null;
+    if (isPrefab3D(opts.model) && opts.model.type === "composite") {
+      return this.addCompositeInstance(opts, opts.model);
+    }
     const modelOrGltf = isPrefab3D(opts.model) ? resolvePrefabHandle(opts.model) : opts.model;
     if ("parts" in modelOrGltf) {
-      return this.addGltfInstance(opts, modelOrGltf);
+      return this.addGltfInstance(opts, modelOrGltf, userPrefabId);
     }
     const modelHandle = modelOrGltf;
     const model = this.models[modelHandle.id];
     if (model?.skinned) {
-      return this.addSkinnedInstance(opts, modelHandle, model.skinIndex);
+      return this.addSkinnedInstance(opts, modelHandle, model.skinIndex, void 0, userPrefabId);
     }
     const slot = this.freeList.allocate();
     if (slot === -1)
-      throw new Error(`Max instances (${this.maxModels}) reached`);
+      throw new Error(`Max instances (${this.maxInstances}) reached`);
     const dynBase = slot * DYNAMIC_MESH_FLOATS;
     const statBase = slot * STATIC_MESH_FLOATS;
     const t = resolveTransform(opts);
@@ -4369,8 +4664,16 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.batcher.add(0, modelHandle.id, slot);
     const dynamicData = this.dynamicData;
     const staticData = this.staticData;
-    return {
+    const self = this;
+    let destroyed = false;
+    const posOut = [0, 0, 0];
+    const rotOut = [0, 0, 0];
+    const sclOut = [0, 0, 0];
+    const handle = {
+      slot,
+      modelId: modelHandle.id,
       skinned: false,
+      prefabId: userPrefabId,
       setPosition(nx, ny, nz) {
         dynamicData[dynBase + DYN_CURR_PX] = nx;
         dynamicData[dynBase + DYN_CURR_PY] = ny;
@@ -4385,10 +4688,47 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
         staticData[statBase + STAT_SX] = nx;
         staticData[statBase + STAT_SY] = ny;
         staticData[statBase + STAT_SZ] = nz;
+      },
+      teleport(nx, ny, nz) {
+        dynamicData[dynBase + DYN_PREV_PX] = nx;
+        dynamicData[dynBase + DYN_PREV_PY] = ny;
+        dynamicData[dynBase + DYN_PREV_PZ] = nz;
+        dynamicData[dynBase + DYN_CURR_PX] = nx;
+        dynamicData[dynBase + DYN_CURR_PY] = ny;
+        dynamicData[dynBase + DYN_CURR_PZ] = nz;
+      },
+      get position() {
+        posOut[0] = dynamicData[dynBase + DYN_CURR_PX];
+        posOut[1] = dynamicData[dynBase + DYN_CURR_PY];
+        posOut[2] = dynamicData[dynBase + DYN_CURR_PZ];
+        return posOut;
+      },
+      get rotation() {
+        rotOut[0] = dynamicData[dynBase + DYN_CURR_RX];
+        rotOut[1] = dynamicData[dynBase + DYN_CURR_RY];
+        rotOut[2] = dynamicData[dynBase + DYN_CURR_RZ];
+        return rotOut;
+      },
+      get scale() {
+        sclOut[0] = staticData[statBase + STAT_SX];
+        sclOut[1] = staticData[statBase + STAT_SY];
+        sclOut[2] = staticData[statBase + STAT_SZ];
+        return sclOut;
+      },
+      destroy() {
+        if (destroyed)
+          return;
+        destroyed = true;
+        self.batcher.remove(0, modelHandle.id, slot);
+        self.freeList.free(slot);
+        dynamicData.fill(0, dynBase, dynBase + DYNAMIC_MESH_FLOATS);
+        staticData.fill(0, statBase, statBase + STATIC_MESH_FLOATS);
+        self.staticDirty = true;
       }
     };
+    return handle;
   }
-  addGltfInstance(opts, gltf) {
+  addGltfInstance(opts, gltf, prefabId) {
     const childHandles = [];
     let firstSkinnedSlot;
     for (const part of gltf.parts) {
@@ -4396,7 +4736,7 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       const model = this.models[part.id];
       let handle;
       if (model?.skinned) {
-        handle = this.addSkinnedInstance(partOpts, part, model.skinIndex, firstSkinnedSlot);
+        handle = this.addSkinnedInstance(partOpts, part, model.skinIndex, firstSkinnedSlot, prefabId);
         if (firstSkinnedSlot === void 0)
           firstSkinnedSlot = handle.slot;
       } else {
@@ -4405,8 +4745,10 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       childHandles.push(handle);
     }
     const skinnedHandle = childHandles.find((h) => h.skinned);
+    const lead = childHandles[0];
     return {
       skinned: gltf.skinned,
+      prefabId,
       setPosition(x, y, z) {
         for (const h of childHandles)
           h.setPosition(x, y, z);
@@ -4419,15 +4761,131 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
         for (const h of childHandles)
           h.setScale(x, y, z);
       },
+      teleport(x, y, z) {
+        for (const h of childHandles)
+          h.teleport(x, y, z);
+      },
+      get position() {
+        return lead.position;
+      },
+      get rotation() {
+        return lead.rotation;
+      },
+      get scale() {
+        return lead.scale;
+      },
       play: skinnedHandle?.play ? (name, opts2) => {
         skinnedHandle.play(name, opts2);
       } : void 0,
       stop: skinnedHandle?.stop ? () => {
         skinnedHandle.stop();
-      } : void 0
+      } : void 0,
+      destroy() {
+        for (const h of childHandles)
+          h.destroy();
+      }
+    };
+  }
+  /**
+   * 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.
+   */
+  addCompositeInstance(opts, composite) {
+    const bucket = this._prefabs;
+    if (!bucket) {
+      throw new Error(
+        `addInstance: composite '${composite.id}' requires the renderer to be constructed with the bucket (\`prefabs\`).`
+      );
+    }
+    const basePos = opts.position ?? [0, 0, 0];
+    const baseRot = opts.rotation ?? [0, 0, 0];
+    const offsets = composite.parts.map((p) => ({
+      px: p.offset?.position?.[0] ?? 0,
+      py: p.offset?.position?.[1] ?? 0,
+      pz: p.offset?.position?.[2] ?? 0,
+      rx: p.offset?.rotation?.[0] ?? 0,
+      ry: p.offset?.rotation?.[1] ?? 0,
+      rz: p.offset?.rotation?.[2] ?? 0
+    }));
+    const childHandles = [];
+    const posOut = [basePos[0], basePos[1], basePos[2]];
+    const rotOut = [baseRot[0], baseRot[1], baseRot[2]];
+    const sclOut = [1, 1, 1];
+    const initialScale = opts.scale;
+    if (typeof initialScale === "number") {
+      sclOut[0] = sclOut[1] = sclOut[2] = initialScale;
+    } else if (initialScale) {
+      sclOut[0] = initialScale[0];
+      sclOut[1] = initialScale[1];
+      sclOut[2] = initialScale[2];
+    }
+    for (let i = 0; i < composite.parts.length; i++) {
+      const part = composite.parts[i];
+      const off = offsets[i];
+      const partPrefab = bucket.get(part.partId);
+      const partOpts = {
+        ...opts,
+        model: partPrefab,
+        position: [basePos[0] + off.px, basePos[1] + off.py, basePos[2] + off.pz],
+        rotation: [baseRot[0] + off.rx, baseRot[1] + off.ry, baseRot[2] + off.rz]
+      };
+      childHandles.push(this.addInstance(partOpts));
+    }
+    return {
+      skinned: childHandles.some((h) => h.skinned),
+      prefabId: composite.id,
+      setPosition(x, y, z) {
+        posOut[0] = x;
+        posOut[1] = y;
+        posOut[2] = z;
+        for (let i = 0; i < childHandles.length; i++) {
+          const o = offsets[i];
+          childHandles[i].setPosition(x + o.px, y + o.py, z + o.pz);
+        }
+      },
+      setRotation(x, y, z) {
+        rotOut[0] = x;
+        rotOut[1] = y;
+        rotOut[2] = z;
+        for (let i = 0; i < childHandles.length; i++) {
+          const o = offsets[i];
+          childHandles[i].setRotation(x + o.rx, y + o.ry, z + o.rz);
+        }
+      },
+      setScale(x, y, z) {
+        sclOut[0] = x;
+        sclOut[1] = y;
+        sclOut[2] = z;
+        for (const h of childHandles)
+          h.setScale(x, y, z);
+      },
+      teleport(x, y, z) {
+        posOut[0] = x;
+        posOut[1] = y;
+        posOut[2] = z;
+        for (let i = 0; i < childHandles.length; i++) {
+          const o = offsets[i];
+          childHandles[i].teleport(x + o.px, y + o.py, z + o.pz);
+        }
+      },
+      get position() {
+        return posOut;
+      },
+      get rotation() {
+        return rotOut;
+      },
+      get scale() {
+        return sclOut;
+      },
+      destroy() {
+        for (const h of childHandles)
+          h.destroy();
+      }
     };
   }
-  addSkinnedInstance(opts, modelHandle, skinIndex, linkedSlot) {
+  addSkinnedInstance(opts, modelHandle, skinIndex, linkedSlot, prefabId = null) {
     const slot = this.skinnedFreeList.allocate();
     if (slot === -1)
       throw new Error(`Max skinned instances (${this.maxSkinnedInstances}) reached`);
@@ -4438,11 +4896,27 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     if (linkedSlot !== void 0) {
       boneOffset = this.skinnedInstanceBoneOffsets[linkedSlot];
       animState = this.skinnedAnimStates[linkedSlot];
+      this.boneOffsetRefcount[boneOffset]++;
     } else {
-      boneOffset = this.nextBoneOffset + jointCount;
-      this.nextBoneOffset += jointCount * 2;
-      skinModel.animation.computeRestPose(this.boneMatrixData, boneOffset * 16);
-      this.boneMatrixDirty = true;
+      const pool = this.freedBoneOffsets.get(skinIndex);
+      if (pool && pool.length > 0) {
+        boneOffset = pool.pop();
+      } else {
+        boneOffset = this.nextBoneOffset + jointCount;
+        this.nextBoneOffset += jointCount * 2;
+      }
+      this.boneOffsetRefcount[boneOffset] = 1;
+      this.boneOffsetSkinIndex[boneOffset] = skinIndex;
+      const restOffsetFloats = boneOffset * 16;
+      const restLengthFloats = jointCount * 16;
+      skinModel.animation.computeRestPose(this.boneMatrixData, restOffsetFloats);
+      this.device.queue.writeBuffer(
+        this.rawBoneMatrixBuffer,
+        restOffsetFloats * 4,
+        this.boneMatrixData.buffer,
+        this.boneMatrixData.byteOffset + restOffsetFloats * 4,
+        restLengthFloats * 4
+      );
       animState = skinModel.animation.clipCount > 0 ? skinModel.animation.createState(0, 1, true) : null;
     }
     this.skinnedInstanceBoneOffsets[slot] = boneOffset;
@@ -4468,11 +4942,7 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.skinnedStaticData[statBase + SSTAT_CR] = t.cr;
     this.skinnedStaticData[statBase + SSTAT_CG] = t.cg;
     this.skinnedStaticData[statBase + SSTAT_CB] = t.cb;
-    new DataView(this.skinnedStaticData.buffer).setUint32(
-      (statBase + SSTAT_BONE_OFFSET) * 4,
-      boneOffset,
-      true
-    );
+    this.skinnedStaticDV.setUint32((statBase + SSTAT_BONE_OFFSET) * 4, boneOffset, true);
     this.skinnedStaticDirty = true;
     this.skinnedInstanceModelIds[slot] = modelHandle.id;
     this.skinnedBatcher.add(0, modelHandle.id, slot);
@@ -4480,10 +4950,18 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     const staticData = this.skinnedStaticData;
     const animStates = this.skinnedAnimStates;
     const animation = skinModel.animation;
+    const self = this;
+    const capturedBoneOffset = boneOffset;
+    const capturedSkinIndex = skinIndex;
+    let destroyed = false;
+    const posOut = [0, 0, 0];
+    const rotOut = [0, 0, 0];
+    const sclOut = [0, 0, 0];
     return {
       slot,
       modelId: modelHandle.id,
       skinned: true,
+      prefabId,
       setPosition(nx, ny, nz) {
         dynamicData[dynBase + DYN_CURR_PX] = nx;
         dynamicData[dynBase + DYN_CURR_PY] = ny;
@@ -4499,6 +4977,32 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
         staticData[statBase + SSTAT_SY] = ny;
         staticData[statBase + SSTAT_SZ] = nz;
       },
+      teleport(nx, ny, nz) {
+        dynamicData[dynBase + DYN_PREV_PX] = nx;
+        dynamicData[dynBase + DYN_PREV_PY] = ny;
+        dynamicData[dynBase + DYN_PREV_PZ] = nz;
+        dynamicData[dynBase + DYN_CURR_PX] = nx;
+        dynamicData[dynBase + DYN_CURR_PY] = ny;
+        dynamicData[dynBase + DYN_CURR_PZ] = nz;
+      },
+      get position() {
+        posOut[0] = dynamicData[dynBase + DYN_CURR_PX];
+        posOut[1] = dynamicData[dynBase + DYN_CURR_PY];
+        posOut[2] = dynamicData[dynBase + DYN_CURR_PZ];
+        return posOut;
+      },
+      get rotation() {
+        rotOut[0] = dynamicData[dynBase + DYN_CURR_RX];
+        rotOut[1] = dynamicData[dynBase + DYN_CURR_RY];
+        rotOut[2] = dynamicData[dynBase + DYN_CURR_RZ];
+        return rotOut;
+      },
+      get scale() {
+        sclOut[0] = staticData[statBase + SSTAT_SX];
+        sclOut[1] = staticData[statBase + SSTAT_SY];
+        sclOut[2] = staticData[statBase + SSTAT_SZ];
+        return sclOut;
+      },
       play(name, opts2) {
         const state = animStates[slot];
         if (state)
@@ -4508,6 +5012,25 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
         const state = animStates[slot];
         if (state)
           animation.stop(state);
+      },
+      destroy() {
+        if (destroyed)
+          return;
+        destroyed = true;
+        self.skinnedBatcher.remove(0, modelHandle.id, slot);
+        self.skinnedFreeList.free(slot);
+        dynamicData.fill(0, dynBase, dynBase + DYNAMIC_MESH_FLOATS);
+        staticData.fill(0, statBase, statBase + SKINNED_STATIC_MESH_FLOATS);
+        animStates[slot] = null;
+        self.skinnedStaticDirty = true;
+        if (--self.boneOffsetRefcount[capturedBoneOffset] === 0) {
+          let pool = self.freedBoneOffsets.get(capturedSkinIndex);
+          if (!pool) {
+            pool = [];
+            self.freedBoneOffsets.set(capturedSkinIndex, pool);
+          }
+          pool.push(capturedBoneOffset);
+        }
       }
     };
   }
@@ -4593,6 +5116,31 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.animJointLookupOffset = pb.jointLookupOffset;
     return true;
   }
+  /**
+   * 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.
+   */
+  shouldDispatchSkinning(slot, model, camX, camY, camZ, cullDistSq) {
+    const skinModel = model && model.skinIndex >= 0 ? this.skinnedModels[model.skinIndex] : null;
+    const baseRadius = skinModel?.boundingRadius ?? 10;
+    const base = slot * DYNAMIC_MESH_FLOATS;
+    const sBase = slot * SKINNED_STATIC_MESH_FLOATS;
+    const cx = this.skinnedDynamicData[base + DYN_CURR_PX];
+    const cy = this.skinnedDynamicData[base + DYN_CURR_PY];
+    const cz = this.skinnedDynamicData[base + DYN_CURR_PZ];
+    const sx = Math.abs(this.skinnedStaticData[sBase + SSTAT_SX]);
+    const sy = Math.abs(this.skinnedStaticData[sBase + SSTAT_SY]);
+    const sz = Math.abs(this.skinnedStaticData[sBase + SSTAT_SZ]);
+    const maxScale = sx > sy ? sx > sz ? sx : sz : sy > sz ? sy : sz;
+    if (!this.isInFrustum(cx, cy, cz, baseRadius * maxScale))
+      return false;
+    const dxv = cx - camX, dyv = cy - camY, dzv = cz - camZ;
+    if (dxv * dxv + dyv * dyv + dzv * dzv > cullDistSq)
+      return false;
+    return true;
+  }
   updateAnimations(deltaTime) {
     this.syncLazyAnimationChanges();
     if (this.animComputeNeedsRebuild && this.packedAnimData.clips.length > 0) {
@@ -4636,6 +5184,9 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.updatedBoneOffsets.fill(0);
     let count = 0;
     const dv = this.gpuInstDV;
+    const camPos = this.camera.position;
+    const camX = camPos[0], camY = camPos[1], camZ = camPos[2];
+    const cullDistSq = this.animationCullDistanceSq;
     for (let slot = 0; slot < this.maxSkinnedInstances; slot++) {
       const animState = this.skinnedAnimStates[slot];
       if (!animState)
@@ -4674,6 +5225,8 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       const modelId = this.skinnedInstanceModelIds[slot];
       const model = this.models[modelId];
       const skinIdx = model?.skinIndex ?? 0;
+      if (!this.shouldDispatchSkinning(slot, model, camX, camY, camZ, cullDistSq))
+        continue;
       const off = count * 32;
       dv.setInt32(off, animState.clipId, true);
       dv.setFloat32(off + 4, animState.time, true);
@@ -4718,14 +5271,12 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       }
     }
   }
+  /**
+   * Free an instance's renderer slot. Equivalent to `handle.destroy()` -
+   * kept as a convenience for direct lookup. Safe to call multiple times.
+   */
   removeInstance(handle) {
-    this.batcher.remove(0, handle.modelId, handle.slot);
-    this.freeList.free(handle.slot);
-    const dynBase = handle.slot * DYNAMIC_MESH_FLOATS;
-    const statBase = handle.slot * STATIC_MESH_FLOATS;
-    this.dynamicData.fill(0, dynBase, dynBase + DYNAMIC_MESH_FLOATS);
-    this.staticData.fill(0, statBase, statBase + STATIC_MESH_FLOATS);
-    this.staticDirty = true;
+    handle.destroy();
   }
   storePreviousState() {
     this.camera.storePrevious();