@forgeax/engine-render 0.1.24 → 0.1.26

package/src/assembly/webgpu-vertex-layouts.ts

@@ -0,0 +1,132 @@
+import type { GpuVertexBufferLayoutEntry } from '@forgeax/engine-geometry';
+import type { VertexAttributeMap } from '@forgeax/engine-types';
+
+// feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4): a single
+// shared empty ArrayBuffer used by the pipeline builder to synthesize the
+// pbr-skin attribute map when no caller-supplied attributes are available.
+// `deriveVertexBufferLayout` is the SSOT for the layout and reads only key
+// presence, so a zero-byte buffer per key preserves the six-attribute stride.
+export const PBR_SKIN_SENTINEL_ATTR_BUFFER = new ArrayBuffer(0);
+
+/** Default 4-attribute vertex layout used as fallback when meshAttributes is undefined. */
+export const DEFAULT_VERTEX_ATTRS: VertexAttributeMap = {
+  position: new Float32Array(0),
+  normal: new Float32Array(0),
+  uv: new Float32Array(0),
+  tangent: new Float32Array(0),
+};
+
+export const PREPARED_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
+  position: new Float32Array(0),
+  normal: new Float32Array(0),
+  uv: new Float32Array(0),
+  tangent: new Float32Array(0),
+  uv1: new Float32Array(0),
+};
+
+export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
+  position: new Float32Array(0),
+  normal: new Float32Array(0),
+  uv: new Float32Array(0),
+  tangent: new Float32Array(0),
+  skinIndex: new Uint16Array(0),
+  skinWeight: new Float32Array(0),
+};
+
+export const POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 9 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
+      { shaderLocation: 2, offset: 5 * 4, format: 'float32x4' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+export const BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 31 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
+      { shaderLocation: 2, offset: 5 * 4, format: 'float32x2' as const },
+      { shaderLocation: 3, offset: 7 * 4, format: 'float32x4' as const },
+      { shaderLocation: 4, offset: 11 * 4, format: 'float32x4' as const },
+      { shaderLocation: 5, offset: 15 * 4, format: 'float32x4' as const },
+      { shaderLocation: 6, offset: 19 * 4, format: 'float32x4' as const },
+      { shaderLocation: 7, offset: 23 * 4, format: 'float32x4' as const },
+      { shaderLocation: 8, offset: 27 * 4, format: 'float32x4' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+export const TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 12 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
+      { shaderLocation: 2, offset: 6 * 4, format: 'float32x4' as const },
+      { shaderLocation: 3, offset: 10 * 4, format: 'float32x2' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+export const MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
+  {
+    arrayStride: 12 * 4,
+    stepMode: 'vertex' as const,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
+      { shaderLocation: 2, offset: 6 * 4, format: 'float32x2' as const },
+      { shaderLocation: 3, offset: 8 * 4, format: 'float32x4' as const },
+    ],
+  },
+  {
+    arrayStride: 28 * 4,
+    stepMode: 'instance' as const,
+    attributes: [
+      { shaderLocation: 4, offset: 0, format: 'float32x3' as const },
+      { shaderLocation: 5, offset: 3 * 4, format: 'float32x3' as const },
+      { shaderLocation: 6, offset: 6 * 4, format: 'float32x3' as const },
+      { shaderLocation: 7, offset: 9 * 4, format: 'float32x3' as const },
+      { shaderLocation: 8, offset: 12 * 4, format: 'float32x4' as const },
+      { shaderLocation: 9, offset: 16 * 4, format: 'float32x4' as const },
+      { shaderLocation: 10, offset: 20 * 4, format: 'float32x4' as const },
+      { shaderLocation: 11, offset: 24 * 4, format: 'float32x4' as const },
+    ],
+  },
+] satisfies readonly GPUVertexBufferLayout[];
+
+function toGpuVertexFormat(
+  format: GpuVertexBufferLayoutEntry['attributes'][number]['format'],
+): GPUVertexFormat {
+  switch (format) {
+    case 'float32x2':
+    case 'float32x3':
+    case 'float32x4':
+    case 'uint16x4':
+      return format;
+    default:
+      throw new Error(`Unsupported geometry vertex format: ${format}`);
+  }
+}
+
+export function toGpuVertexBufferLayouts(
+  entries: readonly GpuVertexBufferLayoutEntry[],
+): readonly GPUVertexBufferLayout[] {
+  return entries.map((entry) => ({
+    arrayStride: entry.arrayStride,
+    ...(entry.stepMode === undefined ? {} : { stepMode: entry.stepMode }),
+    attributes: entry.attributes.map((attribute) => ({
+      shaderLocation: attribute.shaderLocation,
+      offset: attribute.offset,
+      format: toGpuVertexFormat(attribute.format),
+    })),
+  }));
+}

package/src/assets/asset-decoders.ts

@@ -6,6 +6,8 @@ import {
   err,
   MATERIAL_TEXTURE_SLOTS,
   type MaterialAsset,
+  type MaterialChildAsset,
+  type MaterialRootAsset,
   ok,
   type RenderPipelineAsset,
   type SamplerAsset,
@@ -31,6 +33,12 @@ function validMaterial(value: unknown): value is MaterialAsset {
   }
   if (value.passes !== undefined && !Array.isArray(value.passes)) return false;
   if (value.parameters !== undefined && !Array.isArray(value.parameters)) return false;
+  if (
+    value.parent !== undefined &&
+    ['colorSpace', 'passes', 'parameters'].some((field) => Object.hasOwn(value, field))
+  ) {
+    return false;
+  }
   return value.values === undefined || record(value.values);
 }
 
@@ -60,16 +68,22 @@ function resolveMaterialWireRefs(
   if (refs.length === 0) return ok(value);
 
   let changed = false;
-  let parent = value.parent;
+  const wire = value as unknown as { readonly parent?: unknown };
+  let parent = wire.parent;
   if (typeof parent === 'number') {
     const resolved = resolveMaterialWireRef(parent, refs, 'parent', guid);
     if (!resolved.ok) return resolved;
-    parent = resolved.value as unknown as MaterialAsset['parent'];
+    parent = resolved.value;
     changed = true;
   }
 
   if (value.values === undefined) {
-    return changed ? ok({ ...value, ...(parent === undefined ? {} : { parent }) }) : ok(value);
+    if (!changed) return ok(value);
+    if (parent !== undefined) {
+      const child = value as MaterialChildAsset;
+      return ok({ ...child, parent: parent as unknown as MaterialChildAsset['parent'] });
+    }
+    return ok(value);
   }
 
   const textureFields = new Set(
@@ -105,7 +119,16 @@ function resolveMaterialWireRefs(
       values[field] = rewritten as unknown as NonNullable<MaterialAsset['values']>[string];
     }
   }
-  return ok(changed ? { ...value, ...(parent === undefined ? {} : { parent }), values } : value);
+  if (!changed) return ok(value);
+  if (parent !== undefined) {
+    const child = value as MaterialChildAsset;
+    return ok({
+      ...child,
+      parent: parent as unknown as MaterialChildAsset['parent'],
+      values,
+    });
+  }
+  return ok({ ...value, values } as MaterialRootAsset);
 }
 
 export const materialContribution: AssetDecoderContribution<MaterialAsset, 'material'> = {

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/extract/contracts.ts

@@ -1,3 +1,4 @@
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
 // Shared render-extract snapshot contracts.
 //
 // The extract orchestrator owns traversal and policy; this leaf owns the
@@ -658,6 +659,7 @@ export interface MaterialSnapshot {
    * discriminator (M4-T06).
    */
   readonly materialShaderId?: string | undefined;
+  readonly materialProgramKeys?: Readonly<Record<string, string>> | undefined;
   /**
    * Stable source handle for the material asset. Record uses this only for
    * same-frame assembly reuse; GPU bind-group validity still comes from the
@@ -763,12 +765,9 @@ export interface MaterialSnapshot {
    * from the legacy `shadingModel` discriminant (feat-20260625 M2 D-3,
    * finalised in w15; `shadingModel` field removed in tweak-20260701 M1).
    *
-   * Extract derives this from the first pass's `renderState.blend !==
-   * undefined` (post-feat-20260626-collapse: blend presence is the
-   * single SSOT for "this material is transparent on the geometry
-   * pipeline cache key"). Multi-pass materials whose mix of opaque +
-   * transparent passes need finer routing should split into separate
-   * MaterialAsset entries (the normal forgeax pattern).
+   * This describes the primary-pass snapshot for consumers that need a
+   * material summary. Actual draw routing and the LDR split read the selected
+   * DispatchEntry.renderState, so mixed opaque/transparent Passes remain valid.
    *
    * Type is `boolean | undefined` (derived): `undefined` means "no
    * passes / unknown"; consumers must read `=== true` / `!== true` to
@@ -961,6 +960,7 @@ export interface ExtractFramesOwner {
 }
 
 export interface PreparedExtractContext {
+  readonly materialContext?: MaterialCookProgramContext | undefined;
   readonly assets: AssetRegistry | null | undefined;
   readonly pipelineState: ExtractPipelineSurface | null | undefined;
   readonly materialSnapshotCache: MaterialSnapshotCache | undefined;

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',