@forgeax/engine-render 0.1.33 → 0.1.35

package/src/record/recovery-pipeline.ts

@@ -173,7 +173,11 @@ function addRequest(input: {
   readonly vertexLayoutProjection?: VertexLayoutProjection;
   readonly vertexEntry?: string;
   readonly fragmentEntry?: string;
-  readonly layoutKindOverride?: 'pbr' | 'pbr-skin';
+  readonly layoutKindOverride?:
+    | 'pbr'
+    | 'pbr-skin'
+    | 'surface-direct-pbr'
+    | 'surface-direct-cluster-pbr';
   readonly preserveUndefinedVariant?: boolean;
   readonly variantAlreadyResolved?: boolean;
 }): void {
@@ -244,7 +248,7 @@ function addRequest(input: {
       undefined,
       undefined,
       projection,
-      undefined,
+      'immediate',
       input.layoutKindOverride,
       undefined,
       input.additionalColorFormats,
@@ -260,6 +264,7 @@ function addStandardMaterialRequests(input: {
   readonly internals: RenderSystemInternals;
   readonly pipelineState: PipelineState;
   readonly validated: readonly ValidatedRenderable[];
+  readonly dispatch: readonly DispatchEntry[];
   readonly standardLighting: StandardTopologyInputValue | undefined;
   readonly sampleCount: number;
   readonly isHdrTarget: boolean;
@@ -267,6 +272,13 @@ function addStandardMaterialRequests(input: {
   readonly reflectionFallbackAvailable: boolean;
 }): void {
   const pointsLinesProjection = deriveVertexLayoutProjection(DEFAULT_VERTEX_ATTRIBUTE_MAP);
+  const forwardPrograms = new Map<string, DispatchEntry>();
+  for (const candidate of input.dispatch) {
+    if (candidate.tags.LightMode !== 'Forward' || candidate.materialShaderId === undefined)
+      continue;
+    const key = `${candidate.renderableIndex}:${candidate.materialHandle}`;
+    if (!forwardPrograms.has(key)) forwardPrograms.set(key, candidate);
+  }
   for (const entry of input.validated) {
     if (entry.source.pointsLines !== undefined) {
       const pointsLinesMaterial = entry.source.material;
@@ -312,9 +324,14 @@ function addStandardMaterialRequests(input: {
     const unlitHasColor = unlitProjection === 'VERTEX_COLOR_AVAILABLE=true';
     for (const submesh of entry.mesh.submeshes) {
       const material = entry.source.materials[submesh.materialSlot] ?? entry.source.material;
+      const forwardProgram = forwardPrograms.get(
+        `${entry.renderableIndex}:${material.materialHandle ?? -1}`,
+      );
       const materialShaderId =
         entry.source.skin === undefined
-          ? (material.materialShaderId ?? 'forgeax::default-unlit')
+          ? (forwardProgram?.materialShaderId ??
+            material.materialShaderId ??
+            'forgeax::default-unlit')
           : SKIN_MATERIAL_SHADER_ID;
       const renderState = geometryRenderStateForPass(
         recoveryRenderState(materialShaderId, material, submesh.topology) as ReturnType<
@@ -370,6 +387,13 @@ function addStandardMaterialRequests(input: {
       const materialCapabilityVariantSet = isStandardPbrMaterialShader(materialShaderId)
         ? standardPbrCapabilityVariantSet
         : capabilityVariantSet;
+      const surfaceLayoutKind =
+        material.surfaceModel === 'single-layer-medium'
+          ? input.standardLighting?.kind === 'clustered' &&
+            input.internals.device.caps.storageBuffer
+            ? ('surface-direct-cluster-pbr' as const)
+            : ('surface-direct-pbr' as const)
+          : undefined;
       const requestedVariant = isSprite
         ? materialShaderId === 'forgeax::sprite' && entry.source.spriteInstances !== undefined
           ? SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET
@@ -398,6 +422,12 @@ function addStandardMaterialRequests(input: {
         indexFormat: entry.mesh.indexFormat,
         ...optionalVariant(reflectionFallbackVariant),
         passKind: 'forward',
+        ...(forwardProgram?.vertexEntry === undefined
+          ? {}
+          : { vertexEntry: forwardProgram.vertexEntry }),
+        ...(forwardProgram?.fragmentEntry === undefined
+          ? {}
+          : { fragmentEntry: forwardProgram.fragmentEntry }),
         sampleCount: input.sampleCount,
         ...optionalColorFormat(input.colorFormatOverride),
         ...(input.reflectionFallbackAvailable &&
@@ -405,6 +435,7 @@ function addStandardMaterialRequests(input: {
           ? { additionalColorFormats: ['rgba16float'] as const }
           : {}),
         vertexLayoutProjection: meshProjection,
+        ...(surfaceLayoutKind === undefined ? {} : { layoutKindOverride: surfaceLayoutKind }),
         preserveUndefinedVariant: isSprite && requestedVariant === undefined,
         variantAlreadyResolved:
           isSprite ||
@@ -610,6 +641,7 @@ export function prepareRecoveryPipelineReadiness(input: {
     internals: input.internals,
     pipelineState: input.pipelineState,
     validated: input.validated,
+    dispatch: input.dispatch,
     standardLighting: input.standardLighting,
     sampleCount,
     isHdrTarget,

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';
@@ -113,6 +113,11 @@ export interface ReflectionProbeRecordState {
 export interface MaterialShaderPipelineEntry {
   readonly pipeline: RhiRenderPipeline;
   readonly group2Contract: PipelineGroup2Contract;
+  /** Producer receipt for the exact artifact selected with this pipeline. */
+  readonly receipt?: {
+    readonly identity: string;
+    readonly generation: number;
+  };
 }
 
 import type {
@@ -198,6 +203,7 @@ export interface RenderSystemRuntime {
       | {
           readonly vertexColorAvailable?: boolean;
           readonly deformation?: 'rigid' | 'skin';
+          readonly variantSet?: string;
           readonly clustered?: boolean;
           readonly reflectionFallback?: boolean;
           readonly pass?: 'forward' | 'shadow' | 'depth';
@@ -221,7 +227,15 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    layoutKindOverride?:
+      | 'pbr'
+      | 'pbr-skin'
+      | 'gpu-driven-pbr'
+      | 'gpu-driven-skin'
+      | 'gpu-driven-cluster-pbr'
+      | 'gpu-driven-cluster-skin'
+      | 'surface-direct-pbr'
+      | 'surface-direct-cluster-pbr',
     /** Optional vertex entry override for receipt-owned scene-index passes. */
     vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
@@ -246,7 +260,15 @@ export interface RenderSystemRuntime {
     vertexLayout?: string,
     vertexLayoutProjection?: VertexLayoutProjection,
     shaderModuleMode?: RenderFeatureShaderModuleMode,
-    layoutKindOverride?: 'pbr' | 'pbr-skin' | 'gpu-driven-pbr' | 'gpu-driven-skin',
+    layoutKindOverride?:
+      | 'pbr'
+      | 'pbr-skin'
+      | 'gpu-driven-pbr'
+      | 'gpu-driven-skin'
+      | 'gpu-driven-cluster-pbr'
+      | 'gpu-driven-cluster-skin'
+      | 'surface-direct-pbr'
+      | 'surface-direct-cluster-pbr',
     /** Optional vertex entry override for receipt-owned scene-index passes. */
     vertexEntryPoint?: string,
     additionalColorFormats?: readonly GPUTextureFormat[],
@@ -413,6 +435,8 @@ export interface PipelineState {
   readonly probeInstancesBindGroupLayout?: BindGroupLayout;
   readonly identityInstanceBuffer: Buffer;
   readonly defaultSampler: Sampler;
+  /** Nearest/clamp sampler required by r32float Surface depth input. */
+  readonly surfaceMediumDepthSampler?: Sampler;
   readonly fallbackTextureView: TextureView;
   readonly unlitPipeline: RhiRenderPipeline | null;
   readonly standardPipeline: RhiRenderPipeline | null;
@@ -427,10 +451,16 @@ export interface PipelineState {
   readonly pbrPipelineLayout: PipelineLayout | null;
   /** Dedicated slot-3 layout for scene-index GPU-driven Standard PBR draws. */
   readonly gpuDrivenInstancesBindGroupLayout?: BindGroupLayout | null;
+  /** Direct Surface slot-3 ABI: instances + retained medium frame resources. */
+  readonly surfaceDirectInstancesBindGroupLayout?: BindGroupLayout | null;
   readonly gpuDrivenPbrPipelineLayout?: PipelineLayout | null;
   /** Device-owned shader modules paired with their exact Standard PBR receipts. */
   readonly gpuDrivenPbrPrograms?: ReadonlyMap<string, GpuDrivenPbrProgram>;
   readonly gpuDrivenPbrSkinPipelineLayout?: PipelineLayout | null;
+  /** Clustered group(2) layouts paired with the scene-index slot(3). */
+  readonly gpuDrivenClusterPbrPipelineLayout?: PipelineLayout | null;
+  readonly gpuDrivenClusterPbrSkinPipelineLayout?: PipelineLayout | null;
+  readonly gpuDrivenClusterMeshBindGroupLayout?: BindGroupLayout | null;
   readonly pbrProbePipelineLayout?: PipelineLayout | null;
   readonly hdrpPbrPipelineLayout: PipelineLayout | null;
   readonly hdrpMeshBindGroupLayout?: BindGroupLayout | null;
@@ -552,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;
@@ -579,6 +609,8 @@ export interface _StandardForwardSceneView {
   readonly gpuDrivenSceneMaterialBuffer?: Buffer;
   /** Concrete main-pass draw identities already claimed by the capable GPU lane. */
   readonly gpuDrivenDrawKeys?: ReadonlySet<string>;
+  /** Stable world identities used to construct the claimed draw keys. */
+  readonly gpuDrivenWorldKeys?: readonly number[];
   readonly gpuDrivenShadowViews?: ShadowViewStatePool;
   readonly gpuDrivenShadowBatchProjections?: ReadonlyMap<
     string,
@@ -601,7 +633,11 @@ export interface _StandardForwardSceneView {
   readonly pointsLines: PointsLinesRecordOwner | undefined;
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
   /** Record-stage proof callback; invoked only after a real draw command is encoded. */
-  readonly onRenderableDraw?: (entry: ValidatedRenderable) => void;
+  readonly onRenderableDraw?: (
+    entry: ValidatedRenderable,
+    submeshIndex?: number,
+    receipt?: { readonly lane: 'cpu' | 'gpu'; readonly ready: boolean },
+  ) => void;
   readonly reflectionProbes?: ReflectionProbeRecordState;
   materialUboPayloadCache?: {
     readonly materialSlots: readonly MaterialSnapshot[];

package/src/record/shadow-pass.ts

@@ -82,6 +82,8 @@ export interface GpuDrivenShadowBatch {
   readonly deformation: 'rigid' | 'skin';
   /** Complete binding for this batch, including opaque batches after custom casters. */
   readonly materialGroup: BindGroup;
+  /** Receipt-derived material BG for alpha-mask batches; opaque uses the pass singleton. */
+  readonly alphaMaskMaterialGroup?: BindGroup | undefined;
   readonly vertexBuffer: Buffer;
   readonly indexBuffer?: Buffer | undefined;
   readonly indexFormat?: 'uint16' | 'uint32' | undefined;
@@ -192,6 +194,7 @@ function ensureTypedShadowViewBg(
     );
   }
   const projectorAvailable = pipelineState.projectorAvailable !== false;
+  const lowLimitCloudBindings = !extendedLighting && !projectorAvailable;
   try {
     return getOrCreateFromChain(
       frameState.viewBindGroupCache,
@@ -209,6 +212,9 @@ function ensureTypedShadowViewBg(
             ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
             : []),
         pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
+        ...(lowLimitCloudBindings
+          ? []
+          : [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]),
       ],
       variant,
       () => {
@@ -287,6 +293,24 @@ function ensureTypedShadowViewBg(
                   },
                 ]
               : []),
+            ...(lowLimitCloudBindings
+              ? []
+              : [
+                  {
+                    binding: 16,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: pipelineState.defaultWhiteTextureView,
+                    },
+                  },
+                  {
+                    binding: 17,
+                    resource: {
+                      kind: 'sampler' as const,
+                      value: pipelineState.defaultSampler,
+                    },
+                  },
+                ]),
           ],
         });
         if (!created.ok) throw created.error;
@@ -786,6 +810,7 @@ function recordGpuDrivenShadowIfPublished(
       visibleBindGroup: projection.visibleBindGroup,
       deformation: projection.deformation,
       materialGroup,
+      ...(batch.key.admission === 'alpha-mask' ? { alphaMaskMaterialGroup: materialGroup } : {}),
       vertexBuffer: projection.mesh.vertexBuffer.handle,
       ...(batch.key.drawKind === 'indexed' && projection.mesh.indexBuffer !== null
         ? {
@@ -1849,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)
@@ -1931,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 = {
@@ -1970,7 +1993,11 @@ function ensureGpuDrivenCustomShadowMaterialBg(
   c: _InternalRenderPipelineContext,
   projection: GpuDrivenShadowBatchProjection,
 ): BindGroup {
-  const shaderId = projection.shadowArtifact.material;
+  const shaderId =
+    projection.shadowArtifact.specializationKey ?? projection.shadowArtifact.material;
+  const materialKey = `shadow-material-custom:${shaderId}:${projection.materialEntityKey}:${projection.material.materialHandle ?? -1}:${c.store.materialResourceEpoch}`;
+  const cached = c.materialBgAssemblyCache.get(materialKey);
+  if (cached !== undefined) return cached.bindGroup;
   const fallback = c.pipelineState.skylightFallback;
   if (fallback === null) {
     throw new RhiError({
@@ -1993,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/skybox-post-pass.ts

@@ -498,6 +498,7 @@ export function recordFxaaPass(
   resolve: ResolveContext,
   graphPass?: RhiRenderPassEncoder,
   paramsOverride?: Uint8Array,
+  graphOutputFormat?: GPUTextureFormat,
 ): void {
   const { runtime, pipelineState, encoder, camera, currentTexture } = c;
   // FXAA samples the graph-owned LDR target and writes the current surface.
@@ -570,9 +571,17 @@ export function recordFxaaPass(
       c.bindGroupCounts,
     );
 
-    const fxaaColorFormat = runtime.device.caps.storageBuffer
-      ? pipelineState.format
-      : pipelineState.colorAttachmentFormat;
+    // Typed graph passes own their attachment format.  In particular, the
+    // barrel/LUT split keeps FXAA in the graph-owned rgba16float domain before
+    // the final output encoding; falling back to the swapchain format here
+    // builds a BGRA pipeline against an RGBA16F attachment and invalidates the
+    // command buffer on WebGPU.
+    const fxaaColorFormat =
+      graphPass !== undefined && graphOutputFormat !== undefined
+        ? graphOutputFormat
+        : runtime.device.caps.storageBuffer
+          ? pipelineState.format
+          : pipelineState.colorAttachmentFormat;
     let fxaaPass = graphPass;
     if (fxaaPass === undefined) {
       const fxaaOutputView = runtime.device.createTextureView(currentTexture, {
@@ -594,7 +603,22 @@ export function recordFxaaPass(
         ) as never,
       );
     }
-    fxaaPass.setPipeline(pipelineState.perPassResources.fxaaPipeline);
+    let fxaaPipeline = pipelineState.perPassResources.fxaaPipeline;
+    if (graphPass !== undefined && graphOutputFormat !== undefined) {
+      const entry = runtime.lookupPostProcess?.(FXAA_POST_PROCESS_ID);
+      const rebuilt =
+        entry === undefined || runtime.getPostProcessPipeline === undefined
+          ? null
+          : runtime.getPostProcessPipeline(
+              FXAA_POST_PROCESS_ID,
+              fxaaBglLayout,
+              [graphOutputFormat],
+              entry,
+            );
+      if (rebuilt !== null) fxaaPipeline = rebuilt;
+    }
+    if (fxaaPipeline === null) return;
+    fxaaPass.setPipeline(fxaaPipeline);
     fxaaPass.setBindGroup(0, fxaaBg);
     fxaaPass.draw(3, 1, 0, 0);
     if (graphPass === undefined) fxaaPass.end();

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 };
+}