@forgeax/engine-render 0.1.24 → 0.1.25

package/src/assembly/webgpu-renderer.ts

@@ -30,7 +30,6 @@ import { createRenderReadLease, type RenderReadLease } from '@forgeax/engine-ecs
 import {
   deriveVertexBufferLayout,
   deriveVertexBufferLayoutFromProjection,
-  type GpuVertexBufferLayoutEntry,
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
 import type {
@@ -176,7 +175,9 @@ import {
   makeShaderDeviceAdapter,
   normalizeMaterialShaderVariantSet,
   prepareMaterialShaders,
+  resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
   type ShaderDeviceAdapterInternal,
@@ -214,6 +215,17 @@ import {
 import { STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES } from './shader-prewarm-policy';
 import { buildReadyWebGPU } from './webgpu-ready';
 import { DEPTH_TEXTURE_FORMAT, HDR_COLOR_ATTACHMENT_FORMAT } from './webgpu-ready-contract';
+import {
+  BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS,
+  DEFAULT_VERTEX_ATTRS,
+  MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS,
+  PBR_SKIN_SENTINEL_ATTR_BUFFER,
+  POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS,
+  PREPARED_INSTANCE_VERTEX_ATTRS,
+  PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS,
+  TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS,
+  toGpuVertexBufferLayouts,
+} from './webgpu-vertex-layouts';
 
 export type { BundlerOptions } from './bundler-contract';
 export { assembleMaterialProjection } from './material/assembly';
@@ -231,7 +243,9 @@ export {
   allowsUnlitPreparedFallback,
   isSharedMaterialUserRegionCompatible,
   normalizeMaterialShaderVariantSet,
+  resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
   selectNoColorPbrVariant,
@@ -273,139 +287,6 @@ function adaptMipmapShaderModuleFactory(
 // Transform.world mat4 derivation (audio listener sync + picking read the
 // derived Transform.world from scripts).
 
-// feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4): a single
-// shared empty ArrayBuffer used by `buildPipelineContext` to synthesize the
-// 6-key VertexAttributeMap when no caller-supplied attributes are available
-// for the pbr-skin path. `deriveVertexBufferLayout` is the SSOT for the layout
-// (vertex-attribute-layout.ts) and reads only key presence -- value identity
-// never matters -- so a zero-byte ArrayBuffer per key produces the exact
-// 6-attribute / 72-byte stride layout that the @forgeax::pbr-skin shader's
-// @location(0..5) declarations expect.
-const PBR_SKIN_SENTINEL_ATTR_BUFFER = new ArrayBuffer(0);
-
-/** Default 4-attribute vertex layout used as fallback when meshAttributes is undefined. */
-const DEFAULT_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-};
-
-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),
-};
-
-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),
-};
-
-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[];
-
-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[];
-
-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[];
-
-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}`);
-  }
-}
-
-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),
-    })),
-  }));
-}
-
 /**
  * Bundler-layer injection accepted by `createRenderer` (and proxied by
  * `createApp`) as the optional third argument.
@@ -1954,15 +1835,19 @@ async function makeWebGPURenderer(
         vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance)
         ? getOrBuildPreparedMaterialPipelineLayout(materialShaderId)
         : null;
+    const materialShaderLookup =
+      materialShaderId === undefined
+        ? undefined
+        : getShader().findMaterialArtifact(materialShaderId);
+    const materialShaderSource = materialShaderLookup?.ok
+      ? materialShaderLookup.value.source
+      : undefined;
     const vertexInputContract =
       materialShaderId === undefined
         ? 'render-material'
-        : (() => {
-            const lookup = getShader().findMaterialArtifact(materialShaderId);
-            return lookup.ok
-              ? resolveMaterialShaderVertexInputContract(lookup.value.source)
-              : 'render-material';
-          })();
+        : materialShaderSource !== undefined
+          ? resolveMaterialShaderVertexInputContract(materialShaderSource)
+          : 'render-material';
     const currentState = currentPipelineState();
     const pipelineLayout =
       group0Layout !== null
@@ -1979,9 +1864,16 @@ async function makeWebGPURenderer(
                   ? perShaderLayout.pipelineLayout
                   : selectPipelineLayoutForVariant(currentState, variantSet, layoutKind);
     if (pipelineLayout === null) return null;
+    const currentMaterialUvSetCounts = currentMaterialShaderUvSetCounts();
     const resolvedUvSetCount =
       materialShaderId !== undefined
-        ? currentMaterialShaderUvSetCounts().get(materialShaderId)
+        ? (currentMaterialUvSetCounts.get(materialShaderId) ??
+          (materialShaderSource !== undefined
+            ? resolveMaterialShaderUvSetCount(
+                materialShaderSource,
+                currentMaterialUvSetCounts.get(materialShaderId),
+              )
+            : undefined))
         : undefined;
     const vertexBuffers: readonly GPUVertexBufferLayout[] =
       vertexInputContract === 'none'
@@ -2252,15 +2144,31 @@ async function makeWebGPURenderer(
       (currentState !== null ? currentState.colorAttachmentFormat : 'bgra8unorm-srgb');
     // feat-20260629 M4: auto-fill shaderUvSetCount from naga reflection
     // (stored in materialShaderUvSetCounts during prepareMaterialShaders).
-    const resolvedUvSetCount =
-      shaderUvSetCount ?? currentMaterialShaderUvSetCounts().get(materialShaderId);
-    const manifestEntry = findMaterialShaderManifestEntry(materialShaderId);
+    const pipelineShaderId = resolveMaterialShaderBackendArtifactKey(
+      materialShaderId,
+      internals.device.caps.backendKind,
+      assets.getMaterialArtifact(materialShaderId),
+    );
+    const materialShaderLookup = getShader().findMaterialArtifact(pipelineShaderId);
+    const materialShaderSource = materialShaderLookup.ok
+      ? materialShaderLookup.value.source
+      : undefined;
+    const currentMaterialUvSetCounts = currentMaterialShaderUvSetCounts();
+    const materialUvSetCount = resolveMaterialShaderUvSetCount(
+      materialShaderSource,
+      currentMaterialUvSetCounts.get(pipelineShaderId),
+    );
+    if (materialUvSetCount !== undefined) {
+      currentMaterialUvSetCounts.set(pipelineShaderId, materialUvSetCount);
+    }
+    const resolvedUvSetCount = shaderUvSetCount ?? materialUvSetCount;
+    const manifestEntry = findMaterialShaderManifestEntry(pipelineShaderId);
     // Sprite's omitted request is the boot-selected default artifact. The
     // explicit empty key remains the PER_INSTANCE_REGION=true request used by
     // SpriteInstances, so only that path is capability-rewritten here.
     const resolvedVariantSet =
       variantSet === undefined &&
-      (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
+      (pipelineShaderId === 'forgeax::sprite' || pipelineShaderId === 'forgeax::sprite-lit')
         ? undefined
         : resolveCachedMaterialShaderVariantSet(variantSet, manifestEntry);
     // The record stage also composes engine capability axes for user shaders.
@@ -2272,6 +2180,12 @@ async function makeWebGPURenderer(
     // A single-source manifest entry must stay on its canonical module key;
     // otherwise a synthesized capability axis races the prewarmed module.
     let effectiveVariantSet = normalizeMaterialShaderVariantSet(resolvedVariantSet, manifestEntry);
+    // Runtime-published authored materials are installed from their immutable
+    // cooked artifact, not from the build-time material-shader manifest. The
+    // published artifact identity already selects the backend-specific bytes;
+    // an absent manifest therefore means the source itself is the canonical
+    // pipeline module and must not carry a synthesized capability key.
+    if (manifestEntry === undefined) effectiveVariantSet = undefined;
     if (
       vertexLayoutProjection === undefined &&
       manifestEntry?.variants.some((variant) => 'VERTEX_COLOR_AVAILABLE' in variant.defines)
@@ -2294,7 +2208,7 @@ async function makeWebGPURenderer(
     }
     if (
       manifestEntry !== undefined &&
-      !materialShaderId.startsWith('forgeax::') &&
+      !pipelineShaderId.startsWith('forgeax::') &&
       effectiveVariantSet !== undefined &&
       effectiveVariantSet !== ''
     ) {
@@ -2323,7 +2237,7 @@ async function makeWebGPURenderer(
     const colorFormat: GPUTextureFormat = isHdr ? 'rgba16float' : ldrColorFormat;
     const isDepthOnlyPass = passKindPolicyTable[passKind]?.shape === 'depth-only';
     const spec: PipelineSpec = {
-      shader: { id: materialShaderId, passKind, variantSet: effectiveVariantSet },
+      shader: { id: pipelineShaderId, passKind, variantSet: effectiveVariantSet },
       attachments: {
         colorFormats:
           additionalColorFormats === undefined
@@ -2362,7 +2276,7 @@ async function makeWebGPURenderer(
     const cached = currentPipelineCacheState().materialShaderPipelineCache.get(cacheKey);
     if (cached !== undefined) return cached;
     if (pipelineState === null) return null;
-    const lookup = getShader().findMaterialArtifact(materialShaderId);
+    const lookup = getShader().findMaterialArtifact(pipelineShaderId);
     if (!lookup.ok) {
       if (shouldDeferMissingPreparedMaterialShader(vertexLayout)) {
         // Prepared VFX draws bind only their feature-owned groups. The
@@ -2377,7 +2291,7 @@ async function makeWebGPURenderer(
       // the standard pipeline from the engine-shipped PBR entry.
       if (
         renderState === undefined &&
-        !allowsUnlitPreparedFallback(depthFormatOverride, vertexLayout, materialShaderId)
+        !allowsUnlitPreparedFallback(depthFormatOverride, vertexLayout, pipelineShaderId)
       ) {
         // A prepared feature declares the vertex layout it owns. Falling back
         // to default-unlit here would pair that data with the unlit shader's
@@ -2392,7 +2306,7 @@ async function makeWebGPURenderer(
         return buildAndCachePipeline(
           cacheKey,
           unlitLookup.value,
-          `pbr-pipeline-prepared-${materialShaderId}`,
+          `pbr-pipeline-prepared-${pipelineShaderId}`,
           // Reuse the eagerly compiled engine unlit module. The adapter cache
           // is seeded under this label during renderer readiness; a new label
           // would keep color-only prepared passes in perpetual warm-up.
@@ -2420,7 +2334,7 @@ async function makeWebGPURenderer(
       return buildAndCachePipeline(
         cacheKey,
         { source: pbrEntry.wgsl, paramSchema: [] },
-        `pbr-pipeline-fallback-${materialShaderId}${isHdr ? '-hdr' : ''}`,
+        `pbr-pipeline-fallback-${pipelineShaderId}${isHdr ? '-hdr' : ''}`,
         // w16-b: module identity is the fallback PBR source, stable across
         // topology / renderState / HDR (all baked into the PSO) so every
         // variant reuses one compiled module.
@@ -2454,8 +2368,8 @@ async function makeWebGPURenderer(
         // layout resolution so buildPipelineContext derives the layout that
         // matches the compiled module. Skin keeps its
         // own id so the pbr-skin fail-fast (null layout) is preserved.
-        materialShaderId === SKIN_MATERIAL_SHADER_ID
-          ? materialShaderId
+        pipelineShaderId === SKIN_MATERIAL_SHADER_ID
+          ? pipelineShaderId
           : 'forgeax::default-standard-pbr',
         // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4):
         // forward meshAttributes through the fallback path so the pbr-skin
@@ -2489,7 +2403,7 @@ async function makeWebGPURenderer(
     if (effectiveVariantSet !== undefined) {
       const registry = getShader();
       for (const msEntry of registry.materialShaderManifestEntries()) {
-        if (msEntry.identifier === materialShaderId) {
+        if (msEntry.identifier === pipelineShaderId) {
           const variant = findVariantByKey(msEntry, effectiveVariantSet);
           if (variant) {
             // M3 / w12-w13: variant substitution carries the same source +
@@ -2516,7 +2430,7 @@ async function makeWebGPURenderer(
     return buildAndCachePipeline(
       cacheKey,
       shaderEntry,
-      `pbr-pipeline-${materialShaderId}${isHdr ? '-hdr' : ''}${passKindLabelSegment}`,
+      `pbr-pipeline-${pipelineShaderId}${isHdr ? '-hdr' : ''}${passKindLabelSegment}`,
       // feat-20260609 M4 / w31: when variantSet is non-empty, the module identity
       // includes the variant key so URP (STORAGE_BUFFER_AVAILABLE=true) and HDRP
       // (CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true) variants
@@ -2530,8 +2444,8 @@ async function makeWebGPURenderer(
       // empty-tail segment); module identity stays a function of the
       // exact variantSet string.
       effectiveVariantSet !== undefined
-        ? `module-${materialShaderId}#${effectiveVariantSet}`
-        : `module-${materialShaderId}`,
+        ? `module-${pipelineShaderId}#${effectiveVariantSet}`
+        : `module-${pipelineShaderId}`,
       isHdr,
       renderState,
       topology,
@@ -2547,7 +2461,7 @@ async function makeWebGPURenderer(
       // bug-20260611-skin-pipeline-layout: thread the registered materialShaderId
       // so buildPipelineContext can resolve LayoutKind='pbr-skin' for the skin
       // shader (2-entry mesh-array BGL).
-      materialShaderId,
+      pipelineShaderId,
       // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4):
       // forward meshAttributes so the pbr-skin path's vertex buffer layout
       // is derived via the SSOT (deriveVertexBufferLayout). For URP/HDRP
@@ -3009,6 +2923,24 @@ async function makeWebGPURenderer(
         featureDiagnostics: internals.featureHost?.diagnostics() ?? Object.freeze([]),
         frustumStats: Object.freeze({ ...renderSystem.frustumStats }),
         visibilityStats: Object.freeze({ ...renderSystem.visibilityStats }),
+        instanceCollections: Object.freeze(
+          renderSystem.instanceCollectionsInspection.map((collection) =>
+            Object.freeze({
+              ...collection,
+              uploadRanges: Object.freeze(
+                collection.uploadRanges.map((range) => Object.freeze({ ...range })),
+              ),
+              ...(collection.error === undefined
+                ? {}
+                : {
+                    error: Object.freeze({
+                      ...collection.error,
+                      detail: Object.freeze({ ...collection.error.detail }),
+                    }),
+                  }),
+            }),
+          ),
+        ),
         renderScene: renderSystem.renderScene,
         reflectionProbes: renderSystem.reflectionProbes,
         ssrDependencies: renderSystem.ssrDependencies,

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'> = {