@forgeax/engine-render 0.1.34 → 0.1.35

package/src/record/main-pass-sprite-draws.ts

@@ -1,8 +1,9 @@
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { resolveSpriteInstancesBuffer } from './sprite-instance-buffer';
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass sprite draws.
 // feat-20260704 M5/w31: further-split from main-pass.ts (AC-05 <=1500 lines/file).
 // recordSpritePass + sprite entity/transparent/instance-buffer helpers, moved verbatim.
 
-import type { World } from '@forgeax/engine-ecs';
 import {
   type BindGroup,
   type Buffer,
@@ -21,11 +22,7 @@ import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
 import { buildBeginRenderPassDescriptor, standardTopologyVariantSet } from '../pipeline-spec';
-import type {
-  DispatchEntry,
-  MaterialSnapshot,
-  SpriteInstancesSnapshot,
-} from '../render-system-extract';
+import type { DispatchEntry, MaterialSnapshot } from '../render-system-extract';
 import { resolveFoldInstanceBuffer } from './fold-instance-buffer';
 import { worldEntityKey } from './frame-snapshot';
 import { recordGeometryDraws, resolveGeometryInstancesBindGroup } from './main-pass-geometry';
@@ -37,55 +34,6 @@ import {
 import type { _InternalRenderPipelineContext } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 
-export type { SpriteInstancesSnapshot };
-
-/**
- * Build the interleaved sprite instance payload consumed by this record owner.
- * The extract stage validates the two packed arrays before they reach this
- * function, so the record path has one source of count-mismatch errors.
- */
-export function interleaveSpriteInstanceBuffer(
-  transforms: Float32Array,
-  regions: Float32Array,
-  includePrevious = false,
-): Float32Array {
-  const count = transforms.length / 16;
-  const stride = includePrevious ? 36 : 20;
-  const regionOffset = includePrevious ? 32 : 16;
-  const out = new Float32Array(count * stride);
-  for (let i = 0; i < count; i++) {
-    const dstBase = i * stride;
-    const transformBase = i * 16;
-    const regionBase = i * 4;
-    for (let k = 0; k < 16; k++) out[dstBase + k] = transforms[transformBase + k] ?? 0;
-    if (includePrevious) {
-      for (let k = 0; k < 16; k++) {
-        out[dstBase + 16 + k] = transforms[transformBase + k] ?? 0;
-      }
-    }
-    for (let k = 0; k < 4; k++) {
-      out[dstBase + regionOffset + k] = regions[regionBase + k] ?? 0;
-    }
-  }
-  return out;
-}
-
-/**
- * Check whether the existing per-entity sprite buffer still matches the
- * extract snapshot and interleaved byte count.
- */
-export function spriteInstancesCacheHit(
-  entry: InstanceBufferCacheEntry | undefined,
-  snapshot: SpriteInstancesSnapshot,
-  requestedBytes: number,
-): boolean {
-  return (
-    entry !== undefined &&
-    entry.uploadedArchVersion === snapshot.archVersion &&
-    entry.uploadedByteLength === requestedBytes
-  );
-}
-
 /**
  * Decide whether the LDR record needs the transparent sprite sub-pass. This
  * remains beside the sprite record owner so the frame stage and draw stage
@@ -144,7 +92,7 @@ export function recordSpritePass(
     materialSlot: number,
     submeshMaterial: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
     materialShaderId?: string,
   ) => BindGroup,
   graphPass?: RhiRenderPassEncoder,
@@ -382,7 +330,7 @@ function recordSpriteTransparentPbrDraws(
     slot: number,
     material: MaterialSnapshot,
     entityKey: number,
-    world: World,
+    world: RenderResourceScope,
     shader?: string,
   ) => BindGroup,
   meshGroup2: BindGroup | null,
@@ -455,7 +403,7 @@ function recordSpriteEntityDraws(
     materialSlot: number,
     material: MaterialSnapshot,
     entityKey: number,
-    materialWorld: World,
+    materialWorld: RenderResourceScope,
   ) => BindGroup,
   spritePH: RenderPipeline | null,
   spritePH_withRegion: RenderPipeline | null,
@@ -760,100 +708,6 @@ function recordSpriteEntityDraws(
   }
 }
 
-/**
- * feat-20260704 M3/w19: resolve the interleaved SpriteInstances (@group(3))
- * buffer + instanceCount for a sprite entity in the LDR blend sub-pass,
- * extracted verbatim from recordSpriteEntityDraws. Uploads the interleaved
- * mat4 + per-instance UV region transforms (cache-keyed on the snapshot); on
- * over-cap fires the structured limit-exceeded error and leaves the passed-in
- * fallback buffer/count. Returns the resolved (or unchanged) buffer + count.
- *
- * @internal
- */
-function resolveSpriteInstancesBuffer(
-  c: _InternalRenderPipelineContext,
-  spriteEntry: _InternalRenderPipelineContext['validatedOrdered'][number],
-  fallbackBuffer: Buffer,
-  fallbackCount: number,
-): { buffer: Buffer; count: number } {
-  const { runtime, frameState } = c;
-  let buffer = fallbackBuffer;
-  let count = fallbackCount;
-  const spriteInstancesSnap: SpriteInstancesSnapshot | undefined =
-    spriteEntry.source.spriteInstances;
-  if (spriteInstancesSnap !== undefined) {
-    const uniformFallback = runtime.device.caps.storageBuffer === false;
-    const interleaved = interleaveSpriteInstanceBuffer(
-      spriteInstancesSnap.transforms,
-      spriteInstancesSnap.regions,
-      !uniformFallback,
-    );
-    const requestedBytes = interleaved.byteLength;
-    const cap = runtime.device.limits.maxStorageBufferBindingSize;
-    if (typeof cap === 'number' && requestedBytes > cap) {
-      runtime.errorRegistry.fire(
-        new RhiError({
-          code: 'limit-exceeded',
-          expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
-          hint: 'reduce SpriteInstances instance count to fit within device.limits.maxStorageBufferBindingSize (144 bytes per instance: current mat4 64B + previous mat4 64B + region 16B)',
-          detail: {
-            maxStorageBufferBindingSize: cap,
-            requestedBytes,
-          },
-        }),
-      );
-    } else {
-      const cachedSpriteInst = frameState.instanceBuffers.get(
-        worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
-      );
-      let activeSpriteInst: InstanceBufferCacheEntry | null = null;
-      if (spriteInstancesCacheHit(cachedSpriteInst, spriteInstancesSnap, requestedBytes)) {
-        activeSpriteInst = cachedSpriteInst ?? null;
-      } else if (requestedBytes > 0) {
-        const bufRes = runtime.device.createBuffer({
-          size: requestedBytes,
-          usage:
-            (uniformFallback ? GPU_BUFFER_USAGE_UNIFORM : GPU_BUFFER_USAGE_STORAGE) |
-            GPU_BUFFER_USAGE_COPY_DST,
-          mappedAtCreation: false,
-        });
-        if (!bufRes.ok) {
-          runtime.errorRegistry.fire(bufRes.error);
-        } else {
-          if (cachedSpriteInst !== undefined && !cachedSpriteInst.buffer.isDestroyed) {
-            const r = cachedSpriteInst.buffer.destroy();
-            if (!r.ok) runtime.errorRegistry.fire(r.error);
-          }
-          const newBuf = new GpuBuffer(runtime.device, bufRes.value);
-          activeSpriteInst = {
-            buffer: newBuf,
-            uploadedArchVersion: spriteInstancesSnap.archVersion,
-            uploadedByteLength: requestedBytes,
-          };
-          frameState.instanceBuffers.set(
-            worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
-            activeSpriteInst,
-          );
-        }
-      }
-      if (activeSpriteInst !== null && requestedBytes > 0) {
-        const writeRes = runtime.device.queue.writeBuffer(
-          activeSpriteInst.buffer.handle,
-          0,
-          interleaved,
-        );
-        if (!writeRes.ok) {
-          runtime.errorRegistry.fire(writeRes.error);
-        } else {
-          buffer = activeSpriteInst.buffer.handle;
-          count = spriteInstancesSnap.instanceCount;
-        }
-      }
-    }
-  }
-  return { buffer, count };
-}
-
 function transparentPassColorFormat(
   c: _InternalRenderPipelineContext,
   pipelineState: _InternalRenderPipelineContext['pipelineState'] = c.pipelineState,

package/src/record/main-pass.ts

@@ -1,4 +1,3 @@
-import type { World } from '@forgeax/engine-ecs';
 import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import type { GraphResourceResolver } from '@forgeax/engine-render-graph';
 import {
@@ -19,6 +18,7 @@ import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { buildBeginRenderPassDescriptor, standardTopologyBindGroupReady } from '../pipeline-spec';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
 import type {
@@ -529,7 +529,7 @@ export function recordMainPass(
           identities: [
             getOpaqueResourceIdentity(skylightResources.irradianceSampler as object),
             getOpaqueResourceIdentity(skylightResources.prefilterSampler as object),
-            getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+            getOpaqueResourceIdentity(skylightResources.irradianceSampler as object),
           ],
         },
         resources: {
@@ -549,7 +549,9 @@ export function recordMainPass(
           },
           brdfLut: {
             viewIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutView as object),
-            samplerIdentity: getOpaqueResourceIdentity(skylightResources.brdfLutSampler as object),
+            samplerIdentity: getOpaqueResourceIdentity(
+              skylightResources.irradianceSampler as object,
+            ),
             deviceGeneration: runtime.deviceScope.generation,
           },
           intensityBufferIdentity: getOpaqueResourceIdentity(
@@ -590,7 +592,7 @@ export function recordMainPass(
     // which cannot render a PBR decal). Captures only frame-stable closure
     // state; the caller passes the per-submesh material snapshot + entityKey
     // (for video texture routing) and sets the dynamic UBO offset itself.
-    // Selection keys use the extracted frame index, never World.identity.
+    // Selection keys use the extracted frame index, never RenderResourceScope.identity.
     const hasProbeBindings = (c.reflectionProbes?.table.rows.length ?? 0) > 0;
     const worldIndices = hasProbeBindings
       ? new Map(
@@ -632,7 +634,6 @@ export function recordMainPass(
           skylightPrefilterView: skylightResources.prefilterView,
           prefilterSampler: row.sampler,
           brdfLutView: skylightResources.brdfLutView,
-          brdfLutSampler: skylightResources.brdfLutSampler,
           intensityBuffer: row.uniformBuffer,
         };
         return { resources: probeResources, probeIndex: row.index };
@@ -657,7 +658,7 @@ export function recordMainPass(
     const buildPerSubmeshMaterialBg = (
       submeshMaterial: MaterialSnapshot,
       entityKey: number,
-      materialWorld: World = world,
+      materialWorld: RenderResourceScope = world,
       materialShaderId: string | undefined = submeshMaterial.materialShaderId,
     ): BindGroup =>
       buildPerSubmeshMaterialBgImpl(
@@ -748,7 +749,7 @@ export function recordMainPass(
       materialSlot: number,
       material: MaterialSnapshot,
       entityKey: number,
-      materialWorld: World = world,
+      materialWorld: RenderResourceScope = world,
       materialShaderId: string | undefined = material.materialShaderId,
     ): BindGroup =>
       !hasProbeBindings &&

package/src/record/prepared-material-bindings.ts

@@ -1,5 +1,4 @@
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import type { BindGroupEntry, BindGroupLayout, Buffer } from '@forgeax/engine-rhi';
 import { err, ok } from '@forgeax/engine-rhi';
 import {
@@ -14,6 +13,8 @@ import { transmissionBackdropAvailable } from '../assembly/device-feature-admiss
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
+import type { RenderResourceScope } from '../publication/resource-scope';
+import { renderAssetByGuid } from '../publication/resource-scope';
 import {
   applyParamSchemaDefaultsToUbo,
   applyParamSnapshotToUbo,
@@ -28,7 +29,7 @@ export type PreparedResolverCaches = {
   readonly preparedGroup0Pipelines: WeakSet<object>;
   readonly preparedViewOnlyPipelines: WeakSet<object>;
   readonly preparedRenderMaterialPipelines: WeakSet<object>;
-  readonly preparedAssetHandles: WeakMap<World, Map<string, number>>;
+  readonly preparedAssetHandles: WeakMap<RenderResourceScope, Map<string, number>>;
 };
 
 export function createPreparedResolverCaches(): PreparedResolverCaches {
@@ -45,7 +46,7 @@ export function createPreparedResolverCaches(): PreparedResolverCaches {
 function preparedHandle<Brand extends string>(
   runtime: RenderSystemInternals,
   caches: PreparedResolverCaches,
-  world: World,
+  world: RenderResourceScope,
   guid: string,
   brand: Brand,
 ): Handle<Brand, 'shared'> | undefined {
@@ -57,6 +58,8 @@ function preparedHandle<Brand extends string>(
   const key = `${brand}:${guid.toLowerCase()}`;
   const cached = handles.get(key);
   if (cached !== undefined) return cached as Handle<Brand, 'shared'>;
+  if ('resolveAsset' in world)
+    return world.handleForGuid(guid) as Handle<Brand, 'shared'> | undefined;
   const asset = runtime.assets.lookup(guid);
   if (asset === undefined) return undefined;
   const handle = world.allocSharedRef(brand, asset);
@@ -67,7 +70,7 @@ function preparedHandle<Brand extends string>(
 export function preparedMaterialBindings(
   runtime: RenderSystemInternals,
   caches: PreparedResolverCaches,
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   materialShaderId: string,
   worldIndex: number,
   materialGuid: string,
@@ -75,7 +78,10 @@ export function preparedMaterialBindings(
   skylightResources?: SkylightBindGroupResources,
 ) {
   const world = worlds[worldIndex];
-  const material = runtime.assets.lookup(materialGuid) as MaterialAsset | undefined;
+  const material =
+    world === undefined
+      ? undefined
+      : renderAssetByGuid<MaterialAsset>(world, runtime.assets, materialGuid);
   const pipelineState = runtime.getPipelineState();
   if (world === undefined || material?.kind !== 'material' || pipelineState === null) {
     return err(new Error('prepared material asset is unavailable'));
@@ -203,7 +209,6 @@ export function preparedMaterialBindings(
       prefilterView: fallback.prefilterView,
       prefilterSampler: fallback.sampler,
       brdfLutView: fallback.brdfLutView,
-      brdfLutSampler: fallback.sampler,
       intensityBuffer: fallback.intensityBuffer,
     },
     transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)

package/src/record/render-context.ts

@@ -1,5 +1,4 @@
 import type { AssetRegistry, DynamicTextureStore } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
 import type { Profiler } from '@forgeax/engine-profiler';
 import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
@@ -58,6 +57,7 @@ import type { StandardProfile } from '../pipeline/standard-profile';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import type { PointsLinesInspection } from '../points-lines/inspection';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
+import type { RenderResourceScope } from '../publication/resource-scope';
 import type { ReflectionProbeTable } from '../reflection/gpu-table';
 import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { FrameObservationDomain } from '../render-contract';
@@ -582,7 +582,7 @@ export interface _StandardForwardSceneView {
   readonly skybox: SkyboxSnapshot | undefined;
   readonly profilePhase?: <T>(phase: RenderRecordPhase, action: () => T) => T;
   readonly directionalShadowCacheReuse: boolean;
-  readonly world: World;
+  readonly world: RenderResourceScope;
   readonly tonemapActive: boolean;
   readonly geometryColorView: TextureView | null;
   readonly geometryDepthView: TextureView | null;

package/src/record/shadow-pass.ts

@@ -1874,7 +1874,6 @@ function ensureSpotShadowMaterialBg(c: _InternalRenderPipelineContext): BindGrou
             prefilterView: fb.prefilterView,
             prefilterSampler: fb.sampler,
             brdfLutView: fb.brdfLutView,
-            brdfLutSampler: fb.sampler,
             intensityBuffer: fb.intensityBuffer,
           },
           transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)
@@ -1956,7 +1955,6 @@ function ensureGpuDrivenAlphaMaskMaterialBg(
     prefilterView: fallback.prefilterView,
     prefilterSampler: fallback.sampler,
     brdfLutView: fallback.brdfLutView,
-    brdfLutSampler: fallback.sampler,
     intensityBuffer: fallback.intensityBuffer,
   } satisfies import('../ibl/skylight-bind-group').SkylightBindGroupResources;
   const deps: PerSubmeshMaterialBgDeps = {
@@ -2022,7 +2020,6 @@ function ensureGpuDrivenCustomShadowMaterialBg(
     prefilterView: fallback.prefilterView,
     prefilterSampler: fallback.sampler,
     brdfLutView: fallback.brdfLutView,
-    brdfLutSampler: fallback.sampler,
     intensityBuffer: fallback.intensityBuffer,
   } satisfies import('../ibl/skylight-bind-group').SkylightBindGroupResources;
   const deps: PerSubmeshMaterialBgDeps = {

package/src/record/sprite-instance-buffer.ts

@@ -0,0 +1,155 @@
+import { type Buffer, RhiError } from '@forgeax/engine-rhi';
+import { GpuBuffer } from '../gpu-resource';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
+import type { SpriteInstancesSnapshot } from '../render-system-extract';
+import { worldEntityKey } from './frame-snapshot';
+import type { _InternalRenderPipelineContext } from './render-context';
+
+export type { SpriteInstancesSnapshot } from '../render-system-extract';
+
+/**
+ * Build the interleaved sprite instance payload consumed by this record owner.
+ * The extract stage validates the two packed arrays before they reach this
+ * function, so the record path has one source of count-mismatch errors.
+ */
+export function interleaveSpriteInstanceBuffer(
+  transforms: Float32Array,
+  regions: Float32Array,
+  includePrevious = false,
+): Float32Array {
+  const count = transforms.length / 16;
+  const stride = includePrevious ? 36 : 20;
+  const regionOffset = includePrevious ? 32 : 16;
+  const out = new Float32Array(count * stride);
+  for (let i = 0; i < count; i++) {
+    const dstBase = i * stride;
+    const transformBase = i * 16;
+    const regionBase = i * 4;
+    for (let k = 0; k < 16; k++) out[dstBase + k] = transforms[transformBase + k] ?? 0;
+    if (includePrevious) {
+      for (let k = 0; k < 16; k++) {
+        out[dstBase + 16 + k] = transforms[transformBase + k] ?? 0;
+      }
+    }
+    for (let k = 0; k < 4; k++) {
+      out[dstBase + regionOffset + k] = regions[regionBase + k] ?? 0;
+    }
+  }
+  return out;
+}
+
+/**
+ * Check whether the existing per-entity sprite buffer still matches the
+ * extract snapshot and interleaved byte count.
+ */
+export function spriteInstancesCacheHit(
+  entry: InstanceBufferCacheEntry | undefined,
+  snapshot: SpriteInstancesSnapshot,
+  requestedBytes: number,
+): boolean {
+  return (
+    entry !== undefined &&
+    entry.uploadedArchVersion === snapshot.archVersion &&
+    entry.uploadedByteLength === requestedBytes
+  );
+}
+
+/**
+ * feat-20260704 M3/w19: resolve the interleaved SpriteInstances (@group(3))
+ * buffer + instanceCount for a sprite entity in the LDR blend sub-pass,
+ * extracted verbatim from recordSpriteEntityDraws. Uploads the interleaved
+ * mat4 + per-instance UV region transforms (cache-keyed on the snapshot); on
+ * over-cap fires the structured limit-exceeded error and leaves the passed-in
+ * fallback buffer/count. Returns the resolved (or unchanged) buffer + count.
+ *
+ * @internal
+ */
+export function resolveSpriteInstancesBuffer(
+  c: Pick<_InternalRenderPipelineContext, 'runtime' | 'frameState'>,
+  spriteEntry: _InternalRenderPipelineContext['validatedOrdered'][number],
+  fallbackBuffer: Buffer,
+  fallbackCount: number,
+): { buffer: Buffer; count: number } {
+  const { runtime, frameState } = c;
+  let buffer = fallbackBuffer;
+  let count = fallbackCount;
+  const spriteInstancesSnap: SpriteInstancesSnapshot | undefined =
+    spriteEntry.source.spriteInstances;
+  if (spriteInstancesSnap !== undefined) {
+    if (spriteInstancesSnap.instanceCount === 0) return { buffer, count: 0 };
+    const uniformFallback = runtime.device.caps.storageBuffer === false;
+    const interleaved = interleaveSpriteInstanceBuffer(
+      spriteInstancesSnap.transforms,
+      spriteInstancesSnap.regions,
+      !uniformFallback,
+    );
+    const requestedBytes = interleaved.byteLength;
+    const cap = runtime.device.limits.maxStorageBufferBindingSize;
+    if (typeof cap === 'number' && requestedBytes > cap) {
+      runtime.errorRegistry.fire(
+        new RhiError({
+          code: 'limit-exceeded',
+          expected: `requestedBytes (${requestedBytes}) <= maxStorageBufferBindingSize (${cap})`,
+          hint: 'reduce SpriteInstances instance count to fit within device.limits.maxStorageBufferBindingSize (144 bytes per instance: current mat4 64B + previous mat4 64B + region 16B)',
+          detail: {
+            maxStorageBufferBindingSize: cap,
+            requestedBytes,
+          },
+        }),
+      );
+    } else {
+      const cachedSpriteInst = frameState.instanceBuffers.get(
+        worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
+      );
+      let activeSpriteInst: InstanceBufferCacheEntry | null = null;
+      if (spriteInstancesCacheHit(cachedSpriteInst, spriteInstancesSnap, requestedBytes)) {
+        activeSpriteInst = cachedSpriteInst ?? null;
+      } else if (requestedBytes > 0) {
+        const bufRes = runtime.device.createBuffer({
+          size: requestedBytes,
+          usage:
+            (uniformFallback ? GPU_BUFFER_USAGE_UNIFORM : GPU_BUFFER_USAGE_STORAGE) |
+            GPU_BUFFER_USAGE_COPY_DST,
+          mappedAtCreation: false,
+        });
+        if (!bufRes.ok) {
+          runtime.errorRegistry.fire(bufRes.error);
+        } else {
+          if (cachedSpriteInst !== undefined && !cachedSpriteInst.buffer.isDestroyed) {
+            const r = cachedSpriteInst.buffer.destroy();
+            if (!r.ok) runtime.errorRegistry.fire(r.error);
+          }
+          const newBuf = new GpuBuffer(runtime.device, bufRes.value);
+          activeSpriteInst = {
+            buffer: newBuf,
+            uploadedArchVersion: spriteInstancesSnap.archVersion,
+            uploadedByteLength: requestedBytes,
+          };
+          frameState.instanceBuffers.set(
+            worldEntityKey(spriteEntry.source.worldId, spriteInstancesSnap.cacheKey),
+            activeSpriteInst,
+          );
+        }
+      }
+      if (activeSpriteInst !== null && requestedBytes > 0) {
+        const writeRes = runtime.device.queue.writeBuffer(
+          activeSpriteInst.buffer.handle,
+          0,
+          interleaved,
+        );
+        if (!writeRes.ok) {
+          runtime.errorRegistry.fire(writeRes.error);
+        } else {
+          buffer = activeSpriteInst.buffer.handle;
+          count = spriteInstancesSnap.instanceCount;
+        }
+      }
+    }
+  }
+  return { buffer, count };
+}