@forgeax/engine-render 0.1.24 → 0.1.25

package/dist/{chunk-YRUYGA4A.mjs → chunk-TCLDX7SZ.mjs}

@@ -1,12 +1,12 @@
 import { TRANSPARENT_SORT_MODE_LAYER_Z, TRANSPARENT_SORT_MODE_LAYER_Y } from './chunk-RXZ3RGOU.mjs';
-import { DEFAULT_CLUSTER_GRID, DEFAULT_STANDARD_PROFILE, createIblKernelCache, MAX_LIGHTS, CLUSTER_GRID_STRIDE_U32, LIGHT_INDEX_LIST_CAPACITY, createStandardClusterLayout } from './chunk-TFH5I7JJ.mjs';
-import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from './chunk-YKB5DQV7.mjs';
-import { GPU_SHADER_STAGE_COMPUTE, GPU_BUFFER_USAGE_STORAGE, GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM, createHdrpBindGroupLayoutDescriptor, IES_SLICE_WIDTH, IES_SLICE_HEIGHT, COOKIE_SLICE_SIZE, GPU_SHADER_STAGE_VERTEX, GPU_SHADER_STAGE_FRAGMENT, GPU_BUFFER_USAGE_INDEX, GPU_BUFFER_USAGE_VERTEX, pbrSkinMeshDynamicOffsets, worldEntityKey, buildPbrMaterialUserRegionEntries, buildBindGroupLayoutDescriptor, isStandardPbrMaterialShader, SHADOW_CASTER_SHADER_ID, shadowCasterVariantSet, COOKIE_MATRIX_BYTES, matchPass, createPbrSkinMeshBindGroupEntries, getOpaqueResourceIdentity, SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET, physicalTextureFields, isCanonicalStandardPbrMaterialShader, isStandardPbrSkinMaterialShader, SKIN_MATERIAL_SHADER_ID, PROBE_BLEND_RECORD_BYTE_SIZE, resolveRenderTargetMaterialSource, probeBlendRecordOffset, PROBE_BLEND_RECORD_STRIDE, materialBindGroupLayoutIdentity } from './chunk-KZFTK6DO.mjs';
-import { GPU_TEXTURE_USAGE_RENDER_ATTACHMENT, GPU_TEXTURE_USAGE_COPY_SRC, VertexColorVariantConflictError, EquirectProjectionFailedError, SHADOW_ATLAS_DEFAULT_LAYERS, SHADOW_ATLAS_DEFAULT_FACE_SIZE, ShadowAtlas, PointShadowAtlasUninitializedError, PointShadowAtlasBoundsViolationError, StandardClusterTransportUnavailableError, GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING, GPU_TEXTURE_USAGE_COPY_DST, GPU_TEXTURE_USAGE_TEXTURE_BINDING, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, StandardLightBudgetExceededError, RendererOperationError, StandardClusterIndexOverflowError, FXAA_POST_PROCESS_ID, VideoUploadUnsupportedError } from './chunk-RR5L4SRS.mjs';
+import { DEFAULT_CLUSTER_GRID, DEFAULT_STANDARD_PROFILE, createIblKernelCache, MAX_LIGHTS, CLUSTER_GRID_STRIDE_U32, LIGHT_INDEX_LIST_CAPACITY, createStandardClusterLayout } from './chunk-E34VL5VI.mjs';
+import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from './chunk-JSEDTZYS.mjs';
+import { GPU_SHADER_STAGE_COMPUTE, GPU_BUFFER_USAGE_STORAGE, GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM, createHdrpBindGroupLayoutDescriptor, IES_SLICE_WIDTH, IES_SLICE_HEIGHT, COOKIE_SLICE_SIZE, GPU_SHADER_STAGE_VERTEX, GPU_SHADER_STAGE_FRAGMENT, GPU_BUFFER_USAGE_INDEX, GPU_BUFFER_USAGE_VERTEX, worldEntityKey, instanceCollectionCacheKey, probeBlendRecordOffset, PROBE_BLEND_RECORD_STRIDE, pbrSkinMeshDynamicOffsets, buildPbrMaterialUserRegionEntries, buildBindGroupLayoutDescriptor, isStandardPbrMaterialShader, PROBE_BLEND_RECORD_BYTE_SIZE, SHADOW_CASTER_SHADER_ID, shadowCasterVariantSet, COOKIE_MATRIX_BYTES, matchPass, createPbrSkinMeshBindGroupEntries, getOpaqueResourceIdentity, SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET, physicalTextureFields, isCanonicalStandardPbrMaterialShader, isStandardPbrSkinMaterialShader, SKIN_MATERIAL_SHADER_ID, resolveRenderTargetMaterialSource, materialBindGroupLayoutIdentity } from './chunk-HKXTW355.mjs';
+import { GPU_TEXTURE_USAGE_RENDER_ATTACHMENT, GPU_TEXTURE_USAGE_COPY_SRC, VertexColorVariantConflictError, EquirectProjectionFailedError, SHADOW_ATLAS_DEFAULT_LAYERS, SHADOW_ATLAS_DEFAULT_FACE_SIZE, ShadowAtlas, PointShadowAtlasUninitializedError, PointShadowAtlasBoundsViolationError, StandardClusterTransportUnavailableError, GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING, GPU_TEXTURE_USAGE_COPY_DST, GPU_TEXTURE_USAGE_TEXTURE_BINDING, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, StandardLightBudgetExceededError, RendererOperationError, StandardClusterIndexOverflowError, FXAA_POST_PROCESS_ID, VideoUploadUnsupportedError } from './chunk-ZZ4YQ474.mjs';
 import { derive, ok, err as err$1, toShared, ASSET_ERROR_HINTS, deriveTextureLayout, handleSlot, KNOWN_PASS_KINDS, resolveMaterialTextureCoordinates } from '@forgeax/engine-types';
 import { ok as ok$1, err, RhiError } from '@forgeax/engine-rhi';
 import { mat3, vec3, mat4 } from '@forgeax/engine-math';
-import { deriveVertexLayoutProjection, deriveVertexBufferLayout } from '@forgeax/engine-geometry';
+import { deriveVertexLayoutProjection, deriveVertexBufferLayout, deriveVertexBufferLayoutFromProjection } from '@forgeax/engine-geometry';
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import { probeVideoHighPerfUpload, VIDEO_ELEMENT_PROVIDER_KEY } from '@forgeax/engine-graphics-extras';
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA, STANDARD_PIPELINE_PARAM_SCHEMA, DEFAULT_MSDF_TEXT_PARAM_SCHEMA, DEFAULT_SPRITE_PARAM_SCHEMA, DEFAULT_UNLIT_PARAM_SCHEMA } from '@forgeax/engine-shader';
@@ -283,18 +283,9 @@ function buildPipelineDescriptor(spec, modules) {
   const { attachments, geometry, renderState } = spec;
   const vertexBuffers = geometry.vertexLayoutProjection === void 0 ? deriveVertexBufferLayout(geometry.vertexLayout, {
     ...geometry.shaderUvSetCount !== void 0 ? { shaderUvSetCount: geometry.shaderUvSetCount } : {}
-  }) : geometry.vertexLayoutProjection.attributes.length === 0 ? [] : [
-    {
-      arrayStride: geometry.vertexLayoutProjection.arrayStride,
-      attributes: geometry.vertexLayoutProjection.attributes.map(
-        ({ shaderLocation, offset, format }) => ({
-          shaderLocation,
-          offset,
-          format
-        })
-      )
-    }
-  ];
+  }) : deriveVertexBufferLayoutFromProjection(geometry.vertexLayoutProjection, {
+    ...geometry.shaderUvSetCount !== void 0 ? { shaderUvSetCount: geometry.shaderUvSetCount } : {}
+  });
   const descriptor = {
     vertex: {
       module: modules.vertex,
@@ -4091,6 +4082,150 @@ var GpuTexture = class {
   }
 };
 
+// src/instances.ts
+var MATRIX_STRIDE = 16;
+function appendRange(ranges, start, end) {
+  if (start >= end) return;
+  let index = 0;
+  while (index < ranges.length) {
+    const existing = ranges[index];
+    if (existing === void 0 || existing.end >= start) break;
+    index += 1;
+  }
+  while (index < ranges.length) {
+    const existing = ranges[index];
+    if (existing === void 0 || existing.start > end) break;
+    start = Math.min(start, existing.start);
+    end = Math.max(end, existing.end);
+    ranges.splice(index, 1);
+  }
+  ranges.splice(index, 0, { start, end });
+}
+var InstanceProjectionStore = class {
+  nextId = 1;
+  identities = /* @__PURE__ */ new WeakMap();
+  records = /* @__PURE__ */ new Map();
+  project(world, entity, transforms) {
+    let entities = this.identities.get(world);
+    if (entities === void 0) {
+      entities = /* @__PURE__ */ new Map();
+      this.identities.set(world, entities);
+    }
+    let collectionId = entities.get(entity);
+    if (collectionId === void 0) {
+      collectionId = this.nextId++;
+      entities.set(entity, collectionId);
+    }
+    const previous = this.records.get(collectionId);
+    const unchanged = previous !== void 0 && previous.transforms.length === transforms.length && previous.transforms.every((value, index) => Object.is(value, transforms[index]));
+    const record = unchanged ? previous : {
+      collectionId,
+      world,
+      entity,
+      transforms: new Float32Array(transforms),
+      count: transforms.length / MATRIX_STRIDE,
+      revision: (previous?.revision ?? 0) + 1
+    };
+    this.records.set(collectionId, record);
+    return { ...this.info(record), transforms: record.transforms };
+  }
+  retain(ids) {
+    for (const [id, record] of this.records) {
+      if (ids.has(id)) continue;
+      this.identities.get(record.world)?.delete(record.entity);
+      this.records.delete(id);
+    }
+  }
+  /** Release one producer-owned collection when its render identity is removed. */
+  release(world, entity) {
+    const entities = this.identities.get(world);
+    const collectionId = entities?.get(entity);
+    if (collectionId === void 0) return;
+    entities?.delete(entity);
+    this.records.delete(collectionId);
+  }
+  dispose() {
+    this.records.clear();
+    this.identities = /* @__PURE__ */ new WeakMap();
+  }
+  /**
+   * Return detached residency facts for every live collection.
+   *
+   * @internal Joins CPU projection identity with the active device residency;
+   * callers only receive immutable PODs and never GPU handles.
+   */
+  _inspections(residency, frameNumber) {
+    return Object.freeze(
+      [...this.records.values()].map(
+        (record) => this.projectInspection(record, residency?.get(record.collectionId), frameNumber)
+      )
+    );
+  }
+  info(record) {
+    return Object.freeze({
+      collectionId: record.collectionId,
+      count: record.count,
+      revision: record.revision
+    });
+  }
+  projectInspection(record, residency, frameNumber) {
+    return Object.freeze({
+      ...this.info(record),
+      residentGeneration: residency?.residentGeneration,
+      lane: residency?.lane ?? "unresident",
+      uploadRanges: Object.freeze(
+        residency?.frameNumber === frameNumber ? residency.uploadRanges.map((range) => ({ ...range })) : []
+      ),
+      uploadedBytes: residency?.frameNumber === frameNumber ? residency.uploadedBytes : 0,
+      requestedBytes: residency?.requestedBytes ?? record.count * MATRIX_STRIDE * 4,
+      supportedBytes: residency?.supportedBytes,
+      backend: residency?.backend ?? "unknown",
+      owner: "renderer.instances",
+      error: residency?.error
+    });
+  }
+};
+function recordInstanceResidency(residency, input) {
+  const previous = residency.get(input.collectionId);
+  const sameFrame = previous !== void 0 && previous.frameNumber === input.frameNumber && previous.error === void 0;
+  const uploadRanges = sameFrame ? [...previous.uploadRanges].reduce(
+    (ranges, range) => {
+      appendRange(ranges, range.start, range.end);
+      return ranges;
+    },
+    input.uploadRanges.map((range) => ({ ...range }))
+  ) : input.uploadRanges.map((range) => ({ ...range }));
+  residency.set(input.collectionId, {
+    frameNumber: input.frameNumber,
+    residentGeneration: input.residentGeneration,
+    lane: input.lane,
+    uploadRanges,
+    uploadedBytes: sameFrame ? previous.uploadedBytes + input.uploadedBytes : input.uploadedBytes,
+    requestedBytes: input.requestedBytes,
+    supportedBytes: input.supportedBytes,
+    backend: input.backend,
+    error: void 0
+  });
+}
+function recordInstanceFailure(residency, input) {
+  residency.set(input.collectionId, {
+    frameNumber: -1,
+    residentGeneration: void 0,
+    lane: "unavailable",
+    uploadRanges: [],
+    uploadedBytes: 0,
+    requestedBytes: input.facts.requestedBytes,
+    supportedBytes: input.facts.supportedBytes,
+    backend: input.facts.backend,
+    error: {
+      code: input.code,
+      expected: input.expected,
+      hint: input.hint,
+      detail: { ...input.facts }
+    }
+  });
+}
+
 // src/ibl/skylight-bind-group.ts
 var FALLBACK_BYTES_PER_ROW = 256;
 function assembleMaterialWithSkylightEntries(materialEntries, skylight, transmission, textureInjections = []) {
@@ -5853,6 +5988,213 @@ function recordGeometryDraws(c, pass, matchedMaterials, materialSlotIndices, sam
     }
   }
 }
+function uploadInstanceRanges(c, inst, buffer, ranges, storageBacked, sourceOffsetInstances = 0) {
+  const strideBytes = (storageBacked ? INSTANCE_STORAGE_STRIDE_FLOATS : 16) * Float32Array.BYTES_PER_ELEMENT;
+  const uploadedRanges = [];
+  let uploadedBytes = 0;
+  for (const range of ranges) {
+    const start = Math.max(0, Math.min(inst.instanceCount, range.start));
+    const end = Math.max(start, Math.min(inst.instanceCount, range.end));
+    if (end <= start) continue;
+    const source = inst.transforms.subarray(
+      (sourceOffsetInstances + start) * 16,
+      (sourceOffsetInstances + end) * 16
+    );
+    const payload = storageBacked ? packInstanceStorageBuffer(source) : source;
+    const written = c.runtime.device.queue.writeBuffer(buffer, start * strideBytes, payload);
+    if (!written.ok) {
+      c.runtime.errorRegistry.fire(written.error);
+      return { ok: false, ranges: uploadedRanges, bytes: uploadedBytes };
+    }
+    uploadedRanges.push({ start, end });
+    uploadedBytes += payload.byteLength;
+  }
+  return { ok: true, ranges: uploadedRanges, bytes: uploadedBytes };
+}
+function reportInstanceResidency(c, inst, input) {
+  if (inst.collectionId === void 0 || c.frameState.instanceResidency === void 0) return;
+  recordInstanceResidency(c.frameState.instanceResidency, {
+    collectionId: inst.collectionId,
+    frameNumber: c.frameState.frameNumber,
+    residentGeneration: c.runtime.deviceScope.generation,
+    lane: input.lane,
+    requestedBytes: input.requestedBytes,
+    supportedBytes: input.supportedBytes,
+    uploadRanges: input.uploadRanges,
+    uploadedBytes: input.uploadedBytes,
+    backend: c.runtime.device.caps.backendKind
+  });
+}
+function reportInstanceFailure(c, inst, error, requestedBytes, supportedBytes) {
+  if (inst.collectionId === void 0 || c.frameState.instanceResidency === void 0) return;
+  recordInstanceFailure(c.frameState.instanceResidency, {
+    collectionId: inst.collectionId,
+    code: error.code,
+    expected: error.expected,
+    hint: error.hint,
+    facts: {
+      requestedBytes,
+      supportedBytes,
+      backend: c.runtime.device.caps.backendKind,
+      owner: "renderer.instances",
+      cause: error.code,
+      recovery: error.hint
+    }
+  });
+}
+function clearInstanceChunksForOwner(c, ownerKey) {
+  const chunks = c.frameState.instanceBufferChunks;
+  if (chunks === void 0) return;
+  const prefix = `${ownerKey}:`;
+  for (const [key, entry] of chunks.entries()) {
+    if (!key.startsWith(prefix)) continue;
+    if (!entry.buffer.isDestroyed) {
+      const destroyed = entry.buffer.destroy();
+      if (!destroyed.ok) c.runtime.errorRegistry.fire(destroyed.error);
+    }
+    chunks.delete(key);
+  }
+}
+function resolveStorageInstanceChunks(c, entry, inst, cap, probeBuffer, probeOffset) {
+  const { runtime, frameState } = c;
+  const strideBytes = INSTANCE_STORAGE_STRIDE_FLOATS * Float32Array.BYTES_PER_ELEMENT;
+  const chunkCapacity = Math.floor(cap / strideBytes);
+  if (chunkCapacity < 1) {
+    reportInstanceFailure(
+      c,
+      inst,
+      {
+        code: "limit-exceeded",
+        expected: `maxStorageBufferBindingSize (${cap}) >= ${strideBytes}`,
+        hint: "use a backend with storage-buffer bindings large enough for one InstanceData record"
+      },
+      inst.instanceCount * strideBytes,
+      cap
+    );
+    runtime.errorRegistry.fire(
+      new RhiError({
+        code: "limit-exceeded",
+        expected: `maxStorageBufferBindingSize (${cap}) >= ${strideBytes}`,
+        hint: "use a backend with storage-buffer bindings large enough for one InstanceData record",
+        detail: { maxStorageBufferBindingSize: cap, requestedBytes: strideBytes }
+      })
+    );
+    return null;
+  }
+  const ownerKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+  const chunks = frameState.instanceBufferChunks;
+  const activeKeys = /* @__PURE__ */ new Set();
+  const draws = [];
+  const uploadedRanges = [];
+  let uploadedBytes = 0;
+  for (let start = 0; start < inst.instanceCount; start += chunkCapacity) {
+    const end = Math.min(inst.instanceCount, start + chunkCapacity);
+    const count = end - start;
+    const chunkKey = `${ownerKey}:${start}`;
+    activeKeys.add(chunkKey);
+    const payloadBytes = count * strideBytes;
+    const previous = chunks?.get(chunkKey);
+    let active = previous !== void 0 && previous.uploadedArchVersion === inst.archVersion && previous.uploadedByteLength === payloadBytes ? previous : void 0;
+    let activeIsNew = false;
+    if (active === void 0) {
+      const created = runtime.device.createBuffer({
+        size: payloadBytes,
+        usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+        mappedAtCreation: false
+      });
+      if (!created.ok) {
+        runtime.errorRegistry.fire(created.error);
+        reportInstanceFailure(c, inst, created.error, inst.instanceCount * strideBytes, cap);
+        return null;
+      }
+      if (previous !== void 0 && !previous.buffer.isDestroyed) {
+        const destroyed = previous.buffer.destroy();
+        if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+      }
+      active = {
+        buffer: new GpuBuffer(runtime.device, created.value),
+        uploadedArchVersion: inst.archVersion,
+        uploadedByteLength: payloadBytes
+      };
+      activeIsNew = true;
+      chunks?.set(chunkKey, active);
+      if (chunks === void 0) frameState.transientInstanceBuffers.push(active);
+    }
+    if (active === void 0) return null;
+    const needsUpload = activeIsNew || active.uploadedRevision !== (inst.revision ?? inst.archVersion);
+    const rangesToUpload = [
+      {
+        start: 0,
+        end: count
+      }
+    ];
+    if (needsUpload && rangesToUpload.length > 0) {
+      const upload = uploadInstanceRanges(
+        c,
+        inst,
+        active.buffer.handle,
+        rangesToUpload,
+        true,
+        start
+      );
+      for (const range of upload.ranges) {
+        uploadedRanges.push({ start: range.start + start, end: range.end + start });
+      }
+      uploadedBytes += upload.bytes;
+      if (!upload.ok) {
+        reportInstanceFailure(
+          c,
+          inst,
+          {
+            code: "queue-write-buffer-failed",
+            expected: "the renderer-owned instance storage buffer accepts the complete instance payload",
+            hint: "retry after the active device is healthy or recover the renderer"
+          },
+          inst.instanceCount * strideBytes,
+          cap
+        );
+        return null;
+      }
+    }
+    if (needsUpload) {
+      {
+        const published = { ...active, uploadedRevision: inst.revision ?? inst.archVersion };
+        active = published;
+        chunks?.set(chunkKey, published);
+      }
+    }
+    const activeBuffer = active;
+    draws.push({
+      instanceBuffer: activeBuffer.buffer.handle,
+      instanceBindGroup: resolveGeometryInstancesBindGroup(
+        c,
+        activeBuffer.buffer.handle,
+        probeBuffer
+      ),
+      probeOffset,
+      instanceCount: count
+    });
+  }
+  if (chunks !== void 0) {
+    const prefix = `${ownerKey}:`;
+    for (const [key, stale] of chunks.entries()) {
+      if (!key.startsWith(prefix) || activeKeys.has(key)) continue;
+      if (!stale.buffer.isDestroyed) {
+        const destroyed = stale.buffer.destroy();
+        if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+      }
+      chunks.delete(key);
+    }
+  }
+  reportInstanceResidency(c, inst, {
+    lane: "chunked-storage",
+    requestedBytes: inst.instanceCount * strideBytes,
+    supportedBytes: cap,
+    uploadRanges: uploadedRanges,
+    uploadedBytes
+  });
+  return draws;
+}
 function resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, useProbeBlend) {
   const { runtime, pipelineState, frameState } = c;
   const inst = entry.source.instances;
@@ -5877,74 +6219,152 @@ function resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, useProbe
     ];
   }
   if (inst.instanceCount === 0) return [];
+  const entityCacheKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+  const revision = inst.revision ?? inst.archVersion;
+  const sameRevision = (cached) => cached.uploadedRevision === revision;
+  const fullRange = [{ start: 0, end: inst.instanceCount }];
   let instanceBuffer = pipelineState.identityInstanceBuffer;
   let instanceCount = 1;
   {
     const uniformFallback = runtime.device.caps.storageBuffer === false;
     let instanceBufferUsage = GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
     if (uniformFallback && inst.instanceCount > MAX_UNIFORM_INSTANCES) {
+      const ownerKey = instanceCollectionCacheKey(entry.source.worldId, inst);
+      const chunks = frameState.instanceBufferChunks;
+      const activeKeys = /* @__PURE__ */ new Set();
       const draws = [];
+      const uniformStrideBytes = 16 * Float32Array.BYTES_PER_ELEMENT;
+      const uploadedRanges = [];
+      let uploadedBytes = 0;
       for (let start = 0; start < inst.instanceCount; start += MAX_UNIFORM_INSTANCES) {
         const count = Math.min(MAX_UNIFORM_INSTANCES, inst.instanceCount - start);
-        const chunk = inst.transforms.subarray(start * 16, (start + count) * 16);
-        const bufRes = runtime.device.createBuffer({
-          size: INSTANCE_UBO_FULL_ARRAY_BYTES,
-          usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
-          mappedAtCreation: false
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-          return null;
+        const chunkKey = `${ownerKey}:${start}`;
+        activeKeys.add(chunkKey);
+        const payloadBytes = count * uniformStrideBytes;
+        const previous = chunks?.get(chunkKey);
+        let active = previous !== void 0 && previous.uploadedArchVersion === inst.archVersion && previous.uploadedByteLength === payloadBytes ? previous : void 0;
+        let activeIsNew = false;
+        if (active === void 0) {
+          const created = runtime.device.createBuffer({
+            size: INSTANCE_UBO_FULL_ARRAY_BYTES,
+            usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false
+          });
+          if (!created.ok) {
+            runtime.errorRegistry.fire(created.error);
+            reportInstanceFailure(
+              c,
+              inst,
+              created.error,
+              inst.instanceCount * uniformStrideBytes,
+              MAX_UNIFORM_INSTANCES * uniformStrideBytes
+            );
+            return null;
+          }
+          if (previous !== void 0 && !previous.buffer.isDestroyed) {
+            const destroyed = previous.buffer.destroy();
+            if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+          }
+          active = {
+            buffer: new GpuBuffer(runtime.device, created.value),
+            uploadedArchVersion: inst.archVersion,
+            uploadedByteLength: payloadBytes
+          };
+          activeIsNew = true;
+          chunks?.set(chunkKey, active);
+          if (chunks === void 0) frameState.transientInstanceBuffers.push(active);
         }
-        const buffer = new GpuBuffer(runtime.device, bufRes.value);
-        frameState.transientInstanceBuffers.push({
-          buffer,
-          uploadedArchVersion: inst.archVersion,
-          uploadedByteLength: chunk.byteLength
-        });
-        const writeRes = runtime.device.queue.writeBuffer(buffer.handle, 0, chunk);
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-          return null;
+        const needsUpload = activeIsNew || !sameRevision(active);
+        const rangesToUpload = [
+          {
+            start: 0,
+            end: count
+          }
+        ];
+        if (needsUpload && rangesToUpload.length > 0) {
+          const upload = uploadInstanceRanges(
+            c,
+            inst,
+            active.buffer.handle,
+            rangesToUpload,
+            false,
+            start
+          );
+          for (const range of upload.ranges) {
+            uploadedRanges.push({ start: range.start + start, end: range.end + start });
+          }
+          uploadedBytes += upload.bytes;
+          if (!upload.ok) {
+            reportInstanceFailure(
+              c,
+              inst,
+              {
+                code: "queue-write-buffer-failed",
+                expected: "the renderer-owned instance uniform buffer accepts the complete instance payload",
+                hint: "retry after the active device is healthy or recover the renderer"
+              },
+              inst.instanceCount * uniformStrideBytes,
+              MAX_UNIFORM_INSTANCES * uniformStrideBytes
+            );
+            return null;
+          }
+        }
+        if (needsUpload) {
+          const published = { ...active, uploadedRevision: revision };
+          active = published;
+          chunks?.set(chunkKey, published);
         }
         draws.push({
-          instanceBuffer: buffer.handle,
+          instanceBuffer: active.buffer.handle,
           instanceBindGroup: resolveGeometryInstancesBindGroup(
             c,
-            buffer.handle,
+            active.buffer.handle,
             probeBinding?.buffer
           ),
           probeOffset: probeBinding?.offset ?? -1,
           instanceCount: count
         });
       }
+      if (chunks !== void 0) {
+        const prefix = `${ownerKey}:`;
+        for (const [key, stale] of chunks.entries()) {
+          if (!key.startsWith(prefix) || activeKeys.has(key)) continue;
+          if (!stale.buffer.isDestroyed) {
+            const destroyed = stale.buffer.destroy();
+            if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+          }
+          chunks.delete(key);
+        }
+      }
+      reportInstanceResidency(c, inst, {
+        lane: "chunked-uniform",
+        requestedBytes: inst.instanceCount * uniformStrideBytes,
+        supportedBytes: MAX_UNIFORM_INSTANCES * uniformStrideBytes,
+        uploadRanges: uploadedRanges,
+        uploadedBytes
+      });
       return draws;
     }
     if (uniformFallback) {
       instanceBufferUsage = GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST;
     }
     {
-      const instancePayload = uniformFallback ? inst.transforms : packInstanceStorageBuffer(inst.transforms);
-      const requestedBytes = instancePayload.byteLength;
+      const requestedBytes = inst.instanceCount * (uniformFallback ? 16 : INSTANCE_STORAGE_STRIDE_FLOATS) * Float32Array.BYTES_PER_ELEMENT;
       const cap = runtime.device.limits.maxStorageBufferBindingSize;
       if (!uniformFallback && typeof cap === "number" && cap > 0 && requestedBytes > cap) {
-        runtime.errorRegistry.fire(
-          new RhiError({
-            code: "limit-exceeded",
-            expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-            hint: "reduce instance count to fit within device.limits.maxStorageBufferBindingSize, or split transforms across multiple Instances entries",
-            detail: {
-              maxStorageBufferBindingSize: cap,
-              requestedBytes
-            }
-          })
+        const chunked = resolveStorageInstanceChunks(
+          c,
+          entry,
+          inst,
+          cap,
+          probeBinding?.buffer,
+          probeBinding?.offset ?? -1
         );
-        return null;
+        return chunked;
       } else {
-        const cached = frameState.instanceBuffers.get(
-          worldEntityKey(entry.source.worldId, inst.cacheKey)
-        );
+        const cached = frameState.instanceBuffers.get(entityCacheKey);
         let active = null;
+        let activeIsNew = false;
         if (cached !== void 0 && cached.uploadedArchVersion === inst.archVersion && cached.uploadedByteLength === requestedBytes) {
           active = cached;
         } else if (requestedBytes > 0) {
@@ -5955,6 +6375,8 @@ function resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, useProbe
           });
           if (!bufRes.ok) {
             runtime.errorRegistry.fire(bufRes.error);
+            reportInstanceFailure(c, inst, bufRes.error, requestedBytes, cap);
+            return null;
           } else {
             if (cached !== void 0 && !cached.buffer.isDestroyed) {
               const r = cached.buffer.destroy();
@@ -5966,24 +6388,57 @@ function resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, useProbe
               uploadedArchVersion: inst.archVersion,
               uploadedByteLength: requestedBytes
             };
-            frameState.instanceBuffers.set(
-              worldEntityKey(entry.source.worldId, inst.cacheKey),
-              active
-            );
+            activeIsNew = true;
+            if (active !== null) {
+              frameState.instanceBuffers.set(entityCacheKey, active);
+            }
           }
         }
         if (active !== null) {
-          const writeRes = runtime.device.queue.writeBuffer(
-            active.buffer.handle,
-            0,
-            instancePayload
-          );
-          if (!writeRes.ok) {
-            runtime.errorRegistry.fire(writeRes.error);
-          } else {
-            instanceBuffer = active.buffer.handle;
-            instanceCount = Math.max(1, inst.instanceCount);
+          const needsUpload = activeIsNew || !sameRevision(active);
+          const ranges = [fullRange[0]];
+          let uploadRanges = [];
+          let uploadedBytes = 0;
+          if (needsUpload && ranges.length > 0) {
+            const upload = uploadInstanceRanges(
+              c,
+              inst,
+              active.buffer.handle,
+              ranges,
+              !uniformFallback
+            );
+            uploadRanges = upload.ranges;
+            uploadedBytes = upload.bytes;
+            if (!upload.ok) {
+              reportInstanceFailure(
+                c,
+                inst,
+                {
+                  code: "queue-write-buffer-failed",
+                  expected: "the renderer-owned instance buffer accepts the complete instance payloads",
+                  hint: "retry after the active device is healthy or recover the renderer"
+                },
+                requestedBytes,
+                uniformFallback ? MAX_UNIFORM_INSTANCES * Float32Array.BYTES_PER_ELEMENT * 16 : typeof cap === "number" ? cap : void 0
+              );
+              return null;
+            }
+          }
+          if (needsUpload) {
+            const published = { ...active, uploadedRevision: revision };
+            frameState.instanceBuffers.set(entityCacheKey, published);
+            active = published;
           }
+          instanceBuffer = active.buffer.handle;
+          instanceCount = Math.max(1, inst.instanceCount);
+          reportInstanceResidency(c, inst, {
+            lane: uniformFallback ? "direct-uniform" : "direct-storage",
+            requestedBytes,
+            supportedBytes: uniformFallback ? MAX_UNIFORM_INSTANCES * Float32Array.BYTES_PER_ELEMENT * 16 : typeof cap === "number" ? cap : void 0,
+            uploadRanges,
+            uploadedBytes
+          });
+          clearInstanceChunksForOwner(c, entityCacheKey);
         }
       }
     }
@@ -6521,7 +6976,7 @@ function recordSpriteEntityDraws(c, spritePass, matchedIndices, skylightResource
             new RhiError({
               code: "limit-exceeded",
               expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-              hint: "reduce instance count to fit within device.limits.maxStorageBufferBindingSize, or split transforms across multiple Instances entries",
+              hint: "reduce the sprite batch to fit within device.limits.maxStorageBufferBindingSize or use a storage-capable backend",
               detail: {
                 maxStorageBufferBindingSize: cap,
                 requestedBytes
@@ -6898,9 +7353,16 @@ function shadowShaderMap(c) {
         byMaterial = /* @__PURE__ */ new Map();
         shaders.set(entry.renderableIndex, byMaterial);
       }
+      const candidateSlots = c.materialSlotIndices[entry.renderableIndex] ?? c.materialSlotIndices.flat();
+      const materialSlot = candidateSlots.find(
+        (slot) => c.materialSlots[slot]?.materialHandle === entry.materialHandle
+      );
       byMaterial.set(entry.materialHandle, {
-        materialShaderId: entry.materialShaderId,
-        renderState: entry.renderState
+        materialHandle: entry.materialHandle,
+        materialShaderId: entry.materialShaderId === "forgeax::default-standard-pbr" ? SHADOW_CASTER_SHADER_ID : entry.materialShaderId,
+        renderState: entry.renderState,
+        materialSlot,
+        paramSnapshot: entry.paramSnapshot
       });
     }
   }
@@ -7131,67 +7593,23 @@ function recordShadowCasterDraws(c, shadowPass, shadowPipeline2, shadowMeshBindG
     } else {
       shadowPass.setBindGroup(2, shadowMeshBindGroup, [i * MESH_PER_ENTITY_STRIDE]);
     }
-    let shadowInstanceBuffer = pipelineState.identityInstanceBuffer;
-    let shadowInstanceCount = 1;
-    const shadowInst = entry.source.instances;
-    if (shadowInst?.instanceCount === 0) continue;
-    if (shadowInst !== void 0) {
-      const uniformFallback = runtime.device.caps.storageBuffer === false;
-      if (uniformFallback && shadowInst.instanceCount > MAX_UNIFORM_INSTANCES) {
-        shadowInstanceCount = shadowInst.instanceCount;
-        shadowInstanceBuffer = pipelineState.identityInstanceBuffer;
-      } else {
-        const bufUsage = uniformFallback ? GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
-        const instancePayload = uniformFallback ? shadowInst.transforms : packInstanceStorageBuffer(shadowInst.transforms);
-        const requestedBytes = instancePayload.byteLength;
-        const cached = c.frameState.instanceBuffers.get(
-          worldEntityKey(entry.source.worldId, shadowInst.cacheKey)
-        );
-        let active = null;
-        if (cached !== void 0 && cached.uploadedArchVersion === shadowInst.archVersion && cached.uploadedByteLength === requestedBytes) {
-          active = cached;
-        } else if (requestedBytes > 0) {
-          const bufRes = runtime.device.createBuffer({
-            size: requestedBytes,
-            usage: bufUsage,
-            mappedAtCreation: false
-          });
-          if (!bufRes.ok) {
-            runtime.errorRegistry.fire(bufRes.error);
-          } else {
-            if (cached !== void 0 && !cached.buffer.isDestroyed) {
-              const r = cached.buffer.destroy();
-              if (!r.ok) runtime.errorRegistry.fire(r.error);
-            }
-            const newBuffer = new GpuBuffer(runtime.device, bufRes.value);
-            active = {
-              buffer: newBuffer,
-              uploadedArchVersion: shadowInst.archVersion,
-              uploadedByteLength: requestedBytes
-            };
-            c.frameState.instanceBuffers.set(
-              worldEntityKey(entry.source.worldId, shadowInst.cacheKey),
-              active
-            );
-          }
-        }
-        if (active !== null) {
-          const writeRes = runtime.device.queue.writeBuffer(
-            active.buffer.handle,
-            0,
-            instancePayload
-          );
-          if (!writeRes.ok) {
-            runtime.errorRegistry.fire(writeRes.error);
-          } else {
-            shadowInstanceBuffer = active.buffer.handle;
-            shadowInstanceCount = Math.max(1, shadowInst.instanceCount);
-          }
+    const shadowInstanceDraws = resolveGeometryInstanceBuffer(
+      c,
+      entry,
+      [
+        {
+          instanceBuffer: pipelineState.identityInstanceBuffer,
+          instanceBindGroup: resolveGeometryInstancesBindGroup(
+            c,
+            pipelineState.identityInstanceBuffer
+          ),
+          instanceCount: 1,
+          probeOffset: -1
         }
-      }
-    }
-    const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);
-    shadowPass.setBindGroup(3, shadowInstancesBg);
+      ],
+      false
+    );
+    if (shadowInstanceDraws === null) continue;
     for (const sm of shadowSubmeshes) {
       if (sm.topology !== "triangle-list" && sm.topology !== "triangle-strip") {
         continue;
@@ -7221,10 +7639,13 @@ function recordShadowCasterDraws(c, shadowPass, shadowPipeline2, shadowMeshBindG
         shadowPass.setPipeline(entryShadowPipeline);
         shadowLastPipeline = entryShadowPipeline;
       }
-      if (entry.mesh.indexed) {
-        shadowPass.drawIndexed(sm.indexCount, shadowInstanceCount, sm.indexOffset, 0, 0);
-      } else {
-        shadowPass.draw(sm.vertexCount, shadowInstanceCount, 0, 0);
+      for (const instanceDraw of shadowInstanceDraws) {
+        shadowPass.setBindGroup(3, instanceDraw.instanceBindGroup);
+        if (entry.mesh.indexed) {
+          shadowPass.drawIndexed(sm.indexCount, instanceDraw.instanceCount, sm.indexOffset, 0, 0);
+        } else {
+          shadowPass.draw(sm.vertexCount, instanceDraw.instanceCount, 0, 0);
+        }
       }
     }
   }
@@ -9562,6 +9983,6 @@ function addTaaResolvePass(graph, current, currentTemporal, previousColor, previ
   });
 }
 
-export { BYTES_PER_DIRECT_LIGHT_SLOT, CAPTURE_VIEW_PROJS, CUBEMAP_FACE_VERTICES, CUBE_CAPTURE_VIEW_SLOT_BASE, DEFERRED_COLOR_FORMATS, DEPTH_MIN_PARAMS_BYTE_SIZE, FALLBACK_BYTES_PER_ROW, GpuBuffer, GpuTexture, MATERIAL_PER_ENTITY_STRIDE, MESH_SSBO_BYTES, POINTS_LINES_MATERIAL_SHADER_ID, POINTS_LINES_VIEW_BUFFER_SIZE, PREFILTER_MIP_LEVELS, PREFILTER_SIZE, PipelineSpecError, PostProcessError, REFLECTION_PROBE_VIEW_SLOT_BASE, SHADOW_CASTER_BUFFER_SIZE, TYPED_BLOOM_PASS_NAMES, VIEW_UNIFORM_BUFFER_SIZE, VIEW_UNIFORM_BYTES, VIEW_UNIFORM_SLOT_STRIDE, abortTemporalGpuSubmit, addReflectionFallbackObservationPass, addStandardSceneDataPass, addTaaResolvePass, addTypedBloomPasses, addTypedCompositePostEffects, addTypedFrameObservationPass, addTypedFullscreenPass, addTypedOutputTransformPass, addTypedScenePass, addTypedSkyboxPass, addTypedSsaoPasses, addTypedTemporalResolvePass, aggregateTemporalDemand, applyParamSnapshotToUbo, assembleMaterialWithSkylightEntries, assertStorageBufferCap, buildFoldDispatchPlan, buildFullscreenPostProcessPass, buildLinearLdrMaterialSpecTable, buildPerFrameBindGroups, buildSpecConstTable, cacheKeyOf, cleanPerEntityCache, colorFormatsForPassKind, commitTemporalGpuSubmit, computeProjectionMatrix, computeSplitLdrSprite, computeViewMatrix, configureSurface, createClusterBinScratch, createFullscreenBindGroup, createHdrpClusterMembershipBindGroupLayoutDescriptor, createIblPipelines, createPointsLinesLaneAdapter, createPointsLinesLaneContract, createRenderPipelineTarget, createSkylightFallback, createStandardSceneDataTarget, deriveRenderDataCubemap, deriveRenderDataMesh, deriveRenderDataTexture, describeTemporalDemand, driveLazyEquirectProjection, encodeDirectionalShadowPass, encodeMainPass, encodePointShadowPass, encodeSpotShadowPass, ensureMeshSsboCapacity, entryHasDepthRead, evaluateFoldBucketUniformCap, foldDispatchBuckets, geometryRenderStateForPass, geometryRenderStateForTopology, getOrBuildPipeline, getOrCreateHdrpBuffers, getOrCreateIblCache, getTemporalBindGroupResources, getTemporalGpuState, getTemporalParamsBuffer, hasPendingTemporalGpuSubmit, importRenderPipelineSurface, incrementFoldedDrawsMetric, isTemporalFullscreenBinding, passKindPolicyTable, postProcessShaderEntrySignature, postProcessShaderModuleLabel, postProcessShaderPipelineLabel, prepareFrameLighting, resetHdrpBuffers, residentTextureView, resolveOutputDither, resolveSkyboxActive, resolveSsaoParameters, resolveSurfaceFormatPair, resolveSurfaceProfile, retireTemporalGpuState, retireTemporalGpuStateAfterFence, runIblPrecompute, selectLazyEquirectHandle, selectSwapChainFormat, setIblComposedShaders, standardStorageVariantSet, standardTemporalLaneAdmission, standardTemporalPostOrder, standardTopologyVariantSet, temporalReadIndex, temporalWriteIndex, typedFrameClearColor, uploadMeshSsboBatch, variantSetFromDefines, variantSetFromVertexLayoutProjection, warnMultiSkybox, warnMultiSkylight, warnZeroLightStandard, writeHdrpClusterAndSsaoBuffers, writePointsLinesViewUbo, writeShadowCasterUniforms, writeShadowParamsBuffer, writeSpotModifierTextures, writeViewUbo };
-//# sourceMappingURL=chunk-YRUYGA4A.mjs.map
-//# sourceMappingURL=chunk-YRUYGA4A.mjs.map
+export { BYTES_PER_DIRECT_LIGHT_SLOT, CAPTURE_VIEW_PROJS, CUBEMAP_FACE_VERTICES, CUBE_CAPTURE_VIEW_SLOT_BASE, DEFERRED_COLOR_FORMATS, DEPTH_MIN_PARAMS_BYTE_SIZE, FALLBACK_BYTES_PER_ROW, GpuBuffer, GpuTexture, InstanceProjectionStore, MATERIAL_PER_ENTITY_STRIDE, MESH_SSBO_BYTES, POINTS_LINES_MATERIAL_SHADER_ID, POINTS_LINES_VIEW_BUFFER_SIZE, PREFILTER_MIP_LEVELS, PREFILTER_SIZE, PipelineSpecError, PostProcessError, REFLECTION_PROBE_VIEW_SLOT_BASE, SHADOW_CASTER_BUFFER_SIZE, TYPED_BLOOM_PASS_NAMES, VIEW_UNIFORM_BUFFER_SIZE, VIEW_UNIFORM_BYTES, VIEW_UNIFORM_SLOT_STRIDE, abortTemporalGpuSubmit, addReflectionFallbackObservationPass, addStandardSceneDataPass, addTaaResolvePass, addTypedBloomPasses, addTypedCompositePostEffects, addTypedFrameObservationPass, addTypedFullscreenPass, addTypedOutputTransformPass, addTypedScenePass, addTypedSkyboxPass, addTypedSsaoPasses, addTypedTemporalResolvePass, aggregateTemporalDemand, applyParamSnapshotToUbo, assembleMaterialWithSkylightEntries, assertStorageBufferCap, buildFoldDispatchPlan, buildFullscreenPostProcessPass, buildLinearLdrMaterialSpecTable, buildPerFrameBindGroups, buildSpecConstTable, cacheKeyOf, cleanPerEntityCache, colorFormatsForPassKind, commitTemporalGpuSubmit, computeProjectionMatrix, computeSplitLdrSprite, computeViewMatrix, configureSurface, createClusterBinScratch, createFullscreenBindGroup, createHdrpClusterMembershipBindGroupLayoutDescriptor, createIblPipelines, createPointsLinesLaneAdapter, createPointsLinesLaneContract, createRenderPipelineTarget, createSkylightFallback, createStandardSceneDataTarget, deriveRenderDataCubemap, deriveRenderDataMesh, deriveRenderDataTexture, describeTemporalDemand, driveLazyEquirectProjection, encodeDirectionalShadowPass, encodeMainPass, encodePointShadowPass, encodeSpotShadowPass, ensureMeshSsboCapacity, entryHasDepthRead, evaluateFoldBucketUniformCap, foldDispatchBuckets, geometryRenderStateForPass, geometryRenderStateForTopology, getOrBuildPipeline, getOrCreateHdrpBuffers, getOrCreateIblCache, getTemporalBindGroupResources, getTemporalGpuState, getTemporalParamsBuffer, hasPendingTemporalGpuSubmit, importRenderPipelineSurface, incrementFoldedDrawsMetric, isTemporalFullscreenBinding, passKindPolicyTable, postProcessShaderEntrySignature, postProcessShaderModuleLabel, postProcessShaderPipelineLabel, prepareFrameLighting, resetHdrpBuffers, residentTextureView, resolveGeometryInstanceBuffer, resolveOutputDither, resolveSkyboxActive, resolveSsaoParameters, resolveSurfaceFormatPair, resolveSurfaceProfile, retireTemporalGpuState, retireTemporalGpuStateAfterFence, runIblPrecompute, selectLazyEquirectHandle, selectSwapChainFormat, setIblComposedShaders, standardStorageVariantSet, standardTemporalLaneAdmission, standardTemporalPostOrder, standardTopologyVariantSet, temporalReadIndex, temporalWriteIndex, typedFrameClearColor, uploadMeshSsboBatch, variantSetFromDefines, variantSetFromVertexLayoutProjection, warnMultiSkybox, warnMultiSkylight, warnZeroLightStandard, writeHdrpClusterAndSsaoBuffers, writePointsLinesViewUbo, writeShadowCasterUniforms, writeShadowParamsBuffer, writeSpotModifierTextures, writeViewUbo };
+//# sourceMappingURL=chunk-TCLDX7SZ.mjs.map
+//# sourceMappingURL=chunk-TCLDX7SZ.mjs.map