@forgeax/engine-render 0.1.24 → 0.1.25

package/src/components/instances.ts

@@ -1,206 +1,23 @@
-// @forgeax/engine-render - Instances component (per-entity instanced-draw transforms).
-//
-// Two sources, one component (feat-20260622-chunk-gpu-instancing-sprite-tilemap
-// / AC-09; charter P4 consistent abstraction + charter P1 progressive disclosure).
-// The `Instances` ECS component has exactly TWO sources of `transforms` data, and
-// AI users should hold the boundary explicitly to avoid misreading the ECS view:
-//
-//   Source 1 (EXPLICIT, the only source that lands in ECS) — AI user opt-in.
-//     The AI user hand-attaches `Instances { transforms }` onto an entity at
-//     spawn / set time for high-performance instanced draw. `world.get(e,
-//     Instances)` returns the AI user's payload verbatim (a `Float32Array`
-//     snapshot of column-major mat4 instances; stride = 16). This is the sole
-//     code path through which `Instances` ever appears on an entity.
-//
-//   Source 2 (TRANSPARENT, never written back into ECS) — engine record-stage
-//     fold. When the AI user spawns N independent sprite / tilemap-cell
-//     entities sharing the same (Layer.value, posZ, materialHandle) sort
-//     equivalence class, the engine record stage transparently folds the
-//     equivalent run into ONE `drawIndexed(indexCount, count)` using an
-//     INTERNAL transient buffer (see `render-system-record.ts` fold operator
-//     + `render.instancing.foldedDraws` metric, and the `RhiError
-//     'instancing-exceeds-uniform-cap'` fallback). The fold operator does
-//     NOT auto-inject `Instances` onto those entities — `world.get(e,
-//     Instances)` on a folded entity returns `Result.err` exactly as before.
-//     The ECS view is preserved bit-for-bit (per-cell / per-sprite entity
-//     retained, query / despawn / picking unchanged); the optimisation is
-//     invisible at the component layer (charter P4: consistent abstraction —
-//     the high-performance path is opt-in via Source 1, the default spawn
-//     shape stays untouched).
-//
-// AI user reading this header: do NOT expect engine-side fold to materialise
-// as an `Instances` row on your entity. Read the metric (foldedDraws) or the
-// RhiError code to observe fold behaviour; never gate logic on a runtime
-// `world.get(e, Instances)` lookup after spawn.
-//
-// Schema: 1 array<f32> field `transforms` carrying packed column-major mat4
-// instance transforms (16 f32 per instance, stride = 16). Stride is enforced
-// through a TWO-LAYER contract:
-//
-//   1. AI user set-site: spawn / `world.set` / `world.push` callers pass a
-//      `Float32Array` (or numeric array) whose `length` is a non-zero
-//      multiple of 16. The set site is the AI user's responsibility -- the
-//      engine cannot prove the column-major mat4 packing without the
-//      caller's intent.
-//   2. RenderSystem extract entry: `render-system-extract.ts` performs a
-//      defensive `transforms.length % 16 === 0` check on every
-//      `world.get(e, Instances).transforms` snapshot at frame extract time;
-//      violations route a structured `InstanceTransformsStrideMismatchError`
-//      (`code: 'instance-transforms-stride-mismatch'`,
-//      `detail: { actualLength, expectedStride: 16 }`) through the World
-//      Layer-3 ErrorHandler and the renderable is skipped (fail-fast: the
-//      malformed length never reaches the GPU upload path).
-//
-// feat-20260515-buffer-array-vocab-collapse M3 / w16 (decision §2.3 stride
-// responsibility migration): the legacy component-level
-// stride-declaration option (`{ transforms: 16 }` keyed on the retired
-// per-component stride defineComponent option key) was retired because:
-//   - The ECS layer no longer carries a per-component stride schema (M2 /
-//     w9 dropped the option from `DefineComponentOptions` -- the SSOT
-//     moved to the RenderSystem entry + AI user set site).
-//   - Centralising the check at the consumer (RenderSystem extract) rather
-//     than the producer (ECS write paths) lets the GPU upload path stay
-//     trust-the-snapshot; AI users get one structured error per offending
-//     frame rather than one per write.
-//
-// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w14:
-// migrated from the legacy `{ buffer: 'ref', count: 'u32' }` pair (which
-// cross-coupled with the now-deleted `AssetRegistry.createInstancedBuffer`
-// pipeline + the `InstancedBufferAsset` POD) to the ECS-managed array path.
-// Resize is a `world.push(e, Instances, 'transforms', value)` away (one f32
-// at a time) plus a future `world.grow` if a bulk-resize affordance is
-// added.
-//
-// Storage buffer cap-gate (D-5 OOS-08 follow-up):
-//   - The runtime RenderSystem consumer (`render-system-record.ts`) checks
-//     `device.caps.storageBuffer` before binding the per-entity transforms;
-//     `caps.storageBuffer === false` (backend lacking storage buffer support,
-//     e.g. rhi-wgpu webgl backend) routes a `RhiError` ('feature-not-enabled').
-//     A future loop owns the per-draw fallback path.
-//
-// Group transform chained semantics (charter proposition 5 mental migration):
-//   - When the same entity carries both `Transform` (entity_world) and
-//     `Instances` (per-instance local transforms), the vertex shader
-//     composes per instance:
-//
-//       world_position[i] = entity_world * instances_local[i] * vertex_position
-//
-//   - `Instances.transforms[i*16..i*16+15]` is interpreted as a local-space
-//     transform under the entity, exactly like a child entity's `Transform`
-//     under `ChildOf { parent }` in the hierarchy system. AI users reuse
-//     the `parent x local` intuition without a new concept. Set the
-//     entity's `Transform` to identity to make `instances_local[i]`
-//     directly world-space.
-//
-// 4-segment minimum contract (read this header before reaching for
-// the source body):
-//
-// ===== (a) single-component import + spawn example =====
-//
-//   import {
-//     createRenderer, HANDLE_CUBE,
-//     MeshFilter, MeshRenderer, Transform,
-//     Instances, type InstancesData,
-//   } from '@forgeax/engine-render';
-//
-//   // 1 entity rendering N instanced cubes (16N packed f32, column-major mat4):
-//   const transforms = new Float32Array(N * 16);
-//   // ... fill column-major mat4 columns per instance ...
-//   world.spawn(
-//     { component: MeshFilter,    data: { assetHandle: HANDLE_CUBE } },
-//     { component: MeshRenderer,  data: {} },
-//     { component: Instances,     data: { transforms } },
-//   );
-//
-// ===== (b) packed mat4 layout =====
-//
-//   const transforms = new Float32Array(N * 16); // column-major mat4 per instance
-//   // instance i occupies floats [i*16 .. i*16+15]:
-//   //   [m00 m10 m20 m30   <- column 0
-//   //    m01 m11 m21 m31   <- column 1
-//   //    m02 m12 m22 m32   <- column 2
-//   //    m03 m13 m23 m33]  <- column 3 (translation in m03/m13/m23)
-//
-// `transforms.length` MUST be a non-zero multiple of 16. AI users gate at
-// the set / push site; the RenderSystem extract entry holds the second
-// defensive (AC-06: detail carries `{ expectedStride: 16, actualLength }`).
-// The instance count is the live snapshot length / 16.
-//
-// ===== (c) error code consumption (typed property access, no message regex) =====
-//
-//   // Stride violation surfaces through the engine-ecs Layer-3 ErrorHandler
-//   // when extract reads a malformed snapshot:
-//   //   on('error', (err) => {
-//   //     if (err.code === 'instance-transforms-stride-mismatch') {
-//   //       // err.detail.expectedStride === 16
-//   //       // err.detail.actualLength === <user-supplied length>
-//   //     }
-//   //   });
-//   //
-//   // RenderSystem cap-gate (D-5) -> RhiError 'feature-not-enabled' on the
-//   // RhiErrorListenerRegistry channel:
-//   //   on('error', (err) => {
-//   //     if (err.code === 'feature-not-enabled') {
-//   //       console.warn(err.expected, err.hint);
-//   //     }
-//   //   });
-//
-// charter mapping: proposition 1 (single import surface
-// `import { Instances, type InstancesData } from '@forgeax/engine-render'`);
-// proposition 3 (machine-readable schema > prose:
-// `{ transforms: 'array<f32>' }` is the SSOT, stride 16 documented here +
-// enforced at the RenderSystem entry);
-// proposition 4 (explicit failure: stride violation routes a structured
-// EcsError, not a silent half-row); proposition 5 (consistent abstraction:
-// Instances mirrors Children -- both ride the array-vocab path).
-//
-// Anchors: requirements §AC-06 (stride 16 + RenderSystem upload path);
-// plan-strategy §2.3 (stride responsibility migration to RenderSystem entry
-// defensive + AI user set site) + §3.3 stride error path; plan-decisions
-// D-1 / D-5.
-// OOS-09 (no addChild Commands API) does not apply here; OOS-01 (no
-// dangling-entity sweep) does not apply (Instances stores f32 not entity).
-
 import { defineComponent } from '@forgeax/engine-ecs';
 
 /**
- * Per-entity instanced-draw transforms (ECS component).
- *
- * Carries a variable-length `array<f32>` of column-major mat4 instance
- * transforms (16 f32 per instance, stride = 16; documented above and
- * enforced at the RenderSystem extract entry, NOT at the ECS write paths).
- *
- * The runtime RenderSystem consumer materialises a fresh `Float32Array`
- * snapshot on every `world.get(e, Instances).transforms` access (D-4
- * no-cache), reads the live count from the snapshot's `length`, and
- * uploads the bytes to a per-entity GPU storage buffer in the record stage
- * (`render-system-record.ts`).
+ * World-owned local transforms for one explicit instanced renderable.
+ * Packed column-major mat4 values compose as entityWorld * instanceLocal.
+ * ECS owns copying, mutation and entity lifetime, including large arrays.
+ * Renderer extraction derives its own snapshot and GPU residency; neither
+ * authoring nor glTF SceneAsset lowering requires a Renderer identity.
  *
- * @example Spawn an entity rendering 10000 instanced cubes:
- *   const transforms = new Float32Array(10000 * 16);
- *   // ... fill column-major mat4 columns ...
- *   world.spawn(
- *     { component: MeshFilter,   data: { assetHandle: HANDLE_CUBE } },
- *     { component: MeshRenderer, data: { ... } },
- *     { component: Instances,    data: { transforms } },
- *   );
+ * @example
+ * const transforms = new Float32Array(20_000 * 16);
+ * for (let i = 0; i < 20_000; i++) {
+ *   transforms[i * 16] = transforms[i * 16 + 5] =
+ *     transforms[i * 16 + 10] = transforms[i * 16 + 15] = 1;
+ * }
+ * const entity = world.spawn({ component: Instances, data: { transforms } }).unwrap();
+ * world.set(entity, Instances, { transforms }).unwrap();
  */
 export const Instances = defineComponent('Instances', {
   transforms: { type: 'array<f32>' },
 });
 
-/**
- * Type-level hint for `data` at the `Instances` spawn site.
- *
- * The runtime ECS column shape for `array<f32>` accepts a `Float32Array`
- * payload at spawn / set time (the bytes are copied into the BufferPool
- * slot). The `transforms` field is documented as `Float32Array` here so
- * AI-user IDE autocomplete picks up the typed-array shape.
- *
- * @example
- *   import type { InstancesData } from '@forgeax/engine-render';
- *   const data: InstancesData = { transforms: new Float32Array(N * 16) };
- */
-export type InstancesData = {
-  readonly transforms: Float32Array;
-};
+export type InstancesData = { readonly transforms: Float32Array };

package/src/gpu-driven/production-raster.ts

@@ -49,7 +49,12 @@ import {
   projectedHeightForCandidate,
   type SubmissionPlan,
 } from './batch-topology';
-import { type GpuDrivenLodSelectionInspection, GpuDrivenView, selectGpuLodLane } from './view-gpu';
+import {
+  GPU_DRIVEN_VIEW_WGSL,
+  type GpuDrivenLodSelectionInspection,
+  GpuDrivenView,
+  selectGpuLodLane,
+} from './view-gpu';
 
 const VERTEX_STAGE = 0x1;
 const FRAGMENT_STAGE = 0x2;
@@ -1038,6 +1043,34 @@ export class GpuDrivenProduction {
     return new GpuDrivenProduction(device, shaderModuleFactory);
   }
 
+  /** Recovery has no frame retry: await generated programs before preparing the graph. */
+  static async forRecoveryDevice(
+    device: RhiDevice,
+    factory: PipelineBuilderShaderModuleFactory,
+    createShaderModule: (descriptor: {
+      code: string;
+      label?: string;
+    }) => Promise<Result<ShaderModule, RhiError>>,
+  ): Promise<Result<GpuDrivenProduction, RhiError>> {
+    const modules = new Map<string, ShaderModule>();
+    for (const descriptor of [
+      { label: 'gpu-driven-view', code: GPU_DRIVEN_VIEW_WGSL },
+      { label: 'gpu-driven-rigid-unlit', code: GPU_DRIVEN_RIGID_UNLIT_WGSL },
+    ]) {
+      const module = await createShaderModule(descriptor);
+      if (!module.ok) return module;
+      modules.set(descriptor.code, module.value);
+    }
+    return ok(
+      new GpuDrivenProduction(device, {
+        createShaderModule: (descriptor) => {
+          const module = modules.get(descriptor.code);
+          return module === undefined ? factory.createShaderModule(descriptor) : ok(module);
+        },
+      }),
+    );
+  }
+
   createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
     return {
       kind: 'scene-table',

package/src/gpu-scene.ts

@@ -225,6 +225,10 @@ export class GpuScene {
     drawTemplate: [],
     material: [],
   };
+  /** Transform rows whose previous value advances only after submit. */
+  private readonly pendingTemporalTransforms = new Set<number>();
+  /** Previous rows whose post-submit upload must be retried before the next draw. */
+  private readonly pendingTemporalUploads = new Set<number>();
 
   private constructor(
     private readonly device: RhiDevice,
@@ -273,31 +277,47 @@ export class GpuScene {
   }
 
   sync(delta: RenderSceneApplyResult): Result<GpuSceneSyncResult, RhiError> {
+    for (const transformIndex of this.pendingTemporalUploads) {
+      this.writesByTable.transform.push(transformIndex);
+    }
+    const pendingWrites = TABLE_NAMES.some((name) => this.writesByTable[name].length > 0);
     if (
       delta.createdSlots.length === 0 &&
       delta.updatedSlots.length === 0 &&
       delta.recreatedSlots.length === 0 &&
-      delta.removedSlots.length === 0
+      delta.removedSlots.length === 0 &&
+      !pendingWrites
     ) {
       this.noChangeFrames += 1;
       return ok({ ranges: 0, bytes: 0, grew: false, cleared: 0 });
     }
     const writesByTable = this.writesByTable;
-    for (const name of TABLE_NAMES) writesByTable[name].length = 0;
-    if (!this.identityUploaded) writesByTable.transform.push(0);
+    if (!this.identityUploaded && !writesByTable.transform.includes(0)) {
+      writesByTable.transform.push(0);
+    }
     let highestChangedSlot = -1;
-    for (const records of [delta.createdSlots, delta.recreatedSlots]) {
+    const contentUpdatedSlots = delta.contentUpdatedSlots ?? [];
+    const contentUpdatedSlotIds = new Set(contentUpdatedSlots.map((record) => record.slot));
+    const allocationResets = new Set<number>();
+    // RenderScene may recycle a released CPU slot for a different identity in
+    // the same delta. Clear the old GPU allocation before ensuring the new
+    // record; otherwise the later removal pass clears the newly allocated
+    // record and the next transform-only update sees no allocation.
+    for (const record of delta.removedSlots) {
+      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
+      this.clearSlot(record.slot, writesByTable);
+    }
+    for (const records of [delta.createdSlots, contentUpdatedSlots, delta.recreatedSlots]) {
       for (const record of records) {
+        const previous = this.allocations[record.slot];
         this.ensureAllocation(record, writesByTable);
+        if (previous !== this.allocations[record.slot]) allocationResets.add(record.slot);
         if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
       }
     }
     for (const record of delta.updatedSlots) {
       if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
     }
-    for (const record of delta.removedSlots) {
-      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
-    }
     const requiredCapacity = Math.max(
       highestChangedSlot + 1,
       this.instances.requiredCapacity(),
@@ -312,11 +332,18 @@ export class GpuScene {
     }
 
     for (const record of delta.createdSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of delta.updatedSlots) this.writeRootTransform(record, false, writesByTable);
+    for (const record of contentUpdatedSlots) {
+      this.writeSlot(record, allocationResets.has(record.slot), writesByTable);
+    }
+    for (const record of delta.updatedSlots) {
+      if (contentUpdatedSlotIds.has(record.slot)) continue;
+      this.writeRootTransform(record, false, writesByTable);
+    }
     for (const record of delta.recreatedSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of delta.removedSlots) this.clearSlot(record.slot, writesByTable);
     const uploaded = this.uploadRows(writesByTable);
     if (!uploaded.ok) return uploaded;
+    this.pendingTemporalUploads.clear();
+    for (const name of TABLE_NAMES) writesByTable[name].length = 0;
     this.identityUploaded = true;
     this.clearedSlots += delta.removedSlots.length;
     return ok({
@@ -329,27 +356,47 @@ export class GpuScene {
 
   /** Publish current transforms as previous only after a successful submit. */
   commitTemporalFrame(enabled = true): Result<void, RhiError> {
-    if (!enabled) return ok(undefined);
-    const nextTransform = this.tableBytes.transform.slice(0);
-    const next = new Uint8Array(nextTransform);
-    const current = this.transformBytes;
+    if (!enabled) {
+      this.pendingTemporalTransforms.clear();
+      this.pendingTemporalUploads.clear();
+      return ok(undefined);
+    }
+    if (this.pendingTemporalTransforms.size === 0) return ok(undefined);
     const currentOffset = offset(TRANSFORM, 'currentWorld');
     const previousOffset = offset(TRANSFORM, 'previousWorld');
-    for (let index = 0; index < this.capacity; index += 1) {
-      next.set(
-        current.subarray(
+    const ranges = coalesceSlots([...this.pendingTemporalTransforms]);
+    for (const range of ranges) {
+      for (let index = range.start; index < range.end; index += 1) {
+        this.pendingTemporalUploads.add(index);
+      }
+    }
+    for (const range of ranges) {
+      for (let index = range.start; index < range.end; index += 1) {
+        this.transformBytes.copyWithin(
+          index * TRANSFORM.stride + previousOffset,
           index * TRANSFORM.stride + currentOffset,
           index * TRANSFORM.stride + currentOffset + 64,
-        ),
-        index * TRANSFORM.stride + previousOffset,
+        );
+      }
+    }
+    for (const range of ranges) {
+      const firstOffset = range.start * TRANSFORM.stride;
+      const lastOffset = range.end * TRANSFORM.stride;
+      const uploaded = this.device.queue.writeBuffer(
+        this.buffers.transform,
+        firstOffset,
+        this.transformBytes.subarray(firstOffset, lastOffset),
       );
+      if (!uploaded.ok) return uploaded;
     }
-    const uploaded = this.device.queue.writeBuffer(this.buffers.transform, 0, next);
-    if (!uploaded.ok) return uploaded;
-    this.tableBytes.transform = nextTransform;
-    this.refreshTransformViews();
-    this.uploadRanges += 1;
-    this.uploadBytes += next.byteLength;
+    this.pendingTemporalTransforms.clear();
+    this.pendingTemporalUploads.clear();
+    const bytes = ranges.reduce(
+      (total, range) => total + (range.end - range.start) * TRANSFORM.stride,
+      0,
+    );
+    this.uploadRanges += ranges.length;
+    this.uploadBytes += bytes;
     return ok(undefined);
   }
 
@@ -359,6 +406,9 @@ export class GpuScene {
     this.transforms.reset(1);
     this.draws.reset();
     this.materials.reset();
+    this.pendingTemporalTransforms.clear();
+    this.pendingTemporalUploads.clear();
+    for (const name of TABLE_NAMES) this.writesByTable[name].length = 0;
     const writesByTable: Record<GpuSceneTableName, number[]> = {
       primitive: [],
       instance: [],
@@ -520,7 +570,8 @@ export class GpuScene {
         const localCurrentOffset = localOffset + offset(TRANSFORM, 'currentWorld');
         const localPreviousOffset = localOffset + offset(TRANSFORM, 'previousWorld');
         writeMat4(transform, localCurrentOffset, localWorld);
-        writeMat4(transform, localPreviousOffset, localWorld);
+        if (resetPrevious) writeMat4(transform, localPreviousOffset, localWorld);
+        else this.pendingTemporalTransforms.add(transformIndex);
         writes.transform.push(transformIndex);
       }
       writes.instance.push(instanceIndex);
@@ -631,14 +682,16 @@ export class GpuScene {
     const allocation = this.allocations[record.slot];
     if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     const transformOffset = allocation.transformStart * TRANSFORM.stride;
-    const currentOffset = transformOffset + offset(TRANSFORM, 'currentWorld');
     const previousOffset = transformOffset + offset(TRANSFORM, 'previousWorld');
     if (resetPrevious) {
       writeMat4(this.transformView, previousOffset, record.snapshot.transform.world);
-    } else {
-      this.transformBytes.copyWithin(previousOffset, currentOffset, currentOffset + 64);
     }
-    writeMat4(this.transformView, currentOffset, record.snapshot.transform.world);
+    writeMat4(
+      this.transformView,
+      transformOffset + offset(TRANSFORM, 'currentWorld'),
+      record.snapshot.transform.world,
+    );
+    if (!resetPrevious) this.pendingTemporalTransforms.add(allocation.transformStart);
     writes.transform.push(allocation.transformStart);
   }
 
@@ -743,6 +796,8 @@ export class GpuScene {
         TRANSFORM.stride,
       ).fill(0);
       writes.transform.push(transformIndex);
+      this.pendingTemporalTransforms.delete(transformIndex);
+      this.pendingTemporalUploads.delete(transformIndex);
     }
     for (let ordinal = 0; ordinal < allocation.drawCount; ordinal += 1) {
       const drawIndex = allocation.drawStart + ordinal;

package/src/index.ts

@@ -196,6 +196,7 @@ export type {
   ReflectionProbeSelectionInspection,
   TransmissionInspection,
 } from './inspection-types';
+export type { InstanceCollectionInspection } from './instances';
 export {
   type MaterialColorInput3,
   type MaterialColorInput4,

package/src/instance-buffer-cache.ts

@@ -23,12 +23,16 @@ import type { GpuBuffer } from './gpu-resource';
  * and routes dispose through the RHI shim's destroy bookkeeping SSOT. The
  * two `uploaded*` fields are the cache invalidation fingerprint -- when the
  * archetype version bumps or the byte length changes, the record stage
- * allocates a fresh GpuBuffer and replaces the entry.
+ * allocates a fresh GpuBuffer and replaces the entry. Explicit collection
+ * entries are keyed by renderer-owned collection id at the outer map; the
+ * legacy entity key remains only for sprite/fold snapshots.
  */
 export interface InstanceBufferCacheEntry {
   readonly buffer: GpuBuffer;
   readonly uploadedByteLength: number;
   readonly uploadedArchVersion: number;
+  /** Renderer-owned collection revision uploaded into this buffer. */
+  readonly uploadedRevision?: number;
 }
 
 function destroyInstanceBufferEntries(
@@ -85,6 +89,15 @@ export function disposeInstanceBuffers(
   map.clear();
 }
 
+/** Destroy the renderer-owned buffers used by internal large-instance chunks. */
+export function disposeInstanceBufferChunks(
+  map: Map<string, InstanceBufferCacheEntry>,
+  errorRegistry?: InstanceBufferCacheErrorSink,
+): void {
+  destroyInstanceBufferEntries(map.values(), errorRegistry);
+  map.clear();
+}
+
 /** Destroy transient uniform-fallback chunks allocated for the previous frame. */
 export function disposeTransientInstanceBuffers(
   entries: InstanceBufferCacheEntry[],