@forgeax/engine-render 0.1.24 → 0.1.26

package/src/materials.ts

@@ -8,7 +8,11 @@ import type {
   MaterialRenderState,
   MaterialValue,
 } from '@forgeax/engine-types';
-import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import { deriveStandardLayerPlan, standardSurfaceParameters } from '@forgeax/engine-types';
+import {
+  DEFAULT_STANDARD_SURFACE_MODULE,
+  projectStandardSurfacePasses,
+} from './assembly/material/surface-projection';
 
 export type MaterialTransmissionValidationReason =
   | 'non-finite'
@@ -58,7 +62,6 @@ export const SPRITE_PREMULTIPLIED_ALPHA_BLEND: GPUBlendState = {
   alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
 };
 
-const STANDARD_MODULE = 'forgeax_material::standard';
 const UNLIT_MODULE = 'forgeax_material::unlit';
 const SPRITE_MODULE = 'forgeax_material::sprite';
 
@@ -389,6 +392,70 @@ interface StandardOpts {
   readonly queue?: number;
 }
 
+/** Built-in Standard authoring surface with engine-owned parameter defaults. */
+export interface DefaultStandardOptions extends StandardOpts {
+  readonly surfaceModule?: never;
+  readonly parameters?: never;
+  readonly values?: never;
+}
+
+/** Import-first Standard Surface authoring; the root parameter contract stays caller-owned. */
+export interface CustomStandardSurfaceOptions {
+  readonly surfaceModule: string;
+  readonly parameters: readonly MaterialParameter[];
+  readonly values: Readonly<Record<string, MaterialValue>>;
+  readonly colorSpace?: MaterialColorSpace;
+  readonly renderState?: MaterialRenderState;
+  readonly castShadow?: boolean;
+  readonly queue?: number;
+  readonly baseColor?: never;
+  readonly metallic?: never;
+  readonly roughness?: never;
+  readonly metallicChannel?: never;
+  readonly roughnessChannel?: never;
+  readonly clearcoat?: never;
+  readonly clearcoatRoughness?: never;
+  readonly clearcoatTexture?: never;
+  readonly clearcoatRoughnessTexture?: never;
+  readonly clearcoatNormalTexture?: never;
+  readonly clearcoatNormalScale?: never;
+  readonly anisotropyStrength?: never;
+  readonly anisotropyRotation?: never;
+  readonly anisotropyTexture?: never;
+  readonly sheenColor?: never;
+  readonly sheenRoughness?: never;
+  readonly sheenColorTexture?: never;
+  readonly sheenRoughnessTexture?: never;
+  readonly iridescence?: never;
+  readonly iridescenceIor?: never;
+  readonly iridescenceThicknessMinimum?: never;
+  readonly iridescenceThicknessMaximum?: never;
+  readonly iridescenceTexture?: never;
+  readonly iridescenceThicknessTexture?: never;
+  readonly specular?: never;
+  readonly specularColor?: never;
+  readonly specularTexture?: never;
+  readonly specularColorTexture?: never;
+  readonly emissive?: never;
+  readonly emissiveIntensity?: never;
+  readonly emissiveTexture?: never;
+  readonly baseColorTexture?: never;
+  readonly metallicRoughnessTexture?: never;
+  readonly normalTexture?: never;
+  readonly occlusionTexture?: never;
+  readonly occlusionStrength?: never;
+  readonly alphaCutoff?: never;
+  readonly transmission?: never;
+  readonly transmissionTexture?: never;
+  readonly ior?: never;
+  readonly thickness?: never;
+  readonly thicknessTexture?: never;
+  readonly attenuationColor?: never;
+  readonly attenuationDistance?: never;
+}
+
+export type StandardOptions = DefaultStandardOptions | CustomStandardSurfaceOptions;
+
 function validateChannel(
   name: 'metallicChannel' | 'roughnessChannel',
   value: number | undefined,
@@ -413,7 +480,7 @@ function validateFiniteRange(
   }
 }
 
-function standard(opts: StandardOpts): MaterialAsset {
+function standardDefault(opts: DefaultStandardOptions): MaterialAsset {
   const occlusionStrength = opts.occlusionStrength ?? 1;
   if (occlusionStrength < 0 || occlusionStrength > 1) {
     throw new Error(
@@ -511,21 +578,23 @@ function standard(opts: StandardOpts): MaterialAsset {
   if (opts.attenuationDistance !== undefined) values.attenuationDistance = opts.attenuationDistance;
   const forwardRenderState =
     transmission > 0 ? { ...(opts.renderState ?? {}), depthWriteEnabled: false } : opts.renderState;
-  const parameters = standardParameters('linear', opts);
+  const parameters = standardSurfaceParameters(standardParameters('linear', opts));
   const declaredNames = new Set(parameters.map((parameter) => parameter.name));
   for (const name of Object.keys(values)) {
     if (!declaredNames.has(name)) delete values[name];
   }
-  const physical = deriveStandardLayerPlan(parameters).mode === 'physical';
-  const passes: [MaterialPass, ...MaterialPass[]] = [
-    pass('forward', STANDARD_MODULE, forwardRenderState, 'fs_main', opts.queue),
-  ];
-  if (!physical && transmission === 0) {
-    passes.push(pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue));
-  }
-  if (opts.castShadow !== false) {
-    passes.push(pass('shadow-caster', STANDARD_MODULE, shadowCasterRenderState(opts.renderState)));
-  }
+  const layerPlan = deriveStandardLayerPlan(parameters);
+  const projected = projectStandardSurfacePasses({
+    surfaceModule: DEFAULT_STANDARD_SURFACE_MODULE,
+    values,
+    ...(forwardRenderState === undefined ? {} : { renderState: forwardRenderState }),
+    ...(opts.castShadow === undefined ? {} : { castShadow: opts.castShadow }),
+    ...(opts.queue === undefined ? {} : { queue: opts.queue }),
+    layerPlan,
+  });
+  const passes = (
+    transmission > 0 ? projected.filter((entry) => entry.name !== 'deferred') : projected
+  ) as [MaterialPass, ...MaterialPass[]];
   return {
     kind: 'material',
     colorSpace: 'linear',
@@ -535,6 +604,32 @@ function standard(opts: StandardOpts): MaterialAsset {
   };
 }
 
+function standardCustom(opts: CustomStandardSurfaceOptions): MaterialAsset {
+  const layerPlan = deriveStandardLayerPlan(
+    opts.parameters.filter((parameter) => parameter.optional !== true),
+  );
+  return {
+    kind: 'material',
+    ...(opts.colorSpace === undefined || opts.colorSpace === 'srgb'
+      ? {}
+      : { colorSpace: opts.colorSpace }),
+    passes: projectStandardSurfacePasses({
+      surfaceModule: opts.surfaceModule,
+      values: opts.values,
+      ...(opts.renderState === undefined ? {} : { renderState: opts.renderState }),
+      ...(opts.castShadow === undefined ? {} : { castShadow: opts.castShadow }),
+      ...(opts.queue === undefined ? {} : { queue: opts.queue }),
+      layerPlan,
+    }),
+    parameters: standardSurfaceParameters(opts.parameters),
+    values: opts.values,
+  };
+}
+
+export function standard(options: StandardOptions): MaterialAsset {
+  return options.surfaceModule === undefined ? standardDefault(options) : standardCustom(options);
+}
+
 export const Materials = { unlit, standard, srgb } as const;
 
 export { SPRITE_MODULE };

package/src/pipeline-builder.ts

@@ -277,7 +277,13 @@ export function buildPipelineForMaterialShader(
   const vsEntry = vertexEntry ?? (passKind === 'temporal' ? 'vs_temporal' : 'vs_main');
   const fsEntry =
     fragmentEntry ??
-    (passKind === 'temporal' ? 'fs_temporal' : passKind === 'deferred' ? 'fs_gbuffer' : 'fs_main');
+    (passKind === 'temporal'
+      ? 'fs_temporal'
+      : passKind === 'deferred'
+        ? 'fs_gbuffer'
+        : passKind === 'shadow-caster'
+          ? 'fs_shadow'
+          : 'fs_main');
 
   let source = entry.source;
   if (defines !== undefined && Object.keys(defines).length > 0) {
@@ -345,15 +351,13 @@ export function buildPipelineForMaterialShader(
       vertex: {
         module: shaderModule,
         entryPoint: vsEntry,
-        buffers:
-          ctx.layoutKind === 'pbr-skin'
-            ? [...ctx.vertexBuffers]
-            : [
-                {
-                  arrayStride: 12 * 4,
-                  attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as const }],
-                },
-              ],
+        // Surface-backed Standard shadow entries evaluate the same material
+        // surface as Forward/Deferred, so their vertex stage consumes normal,
+        // UV, and tangent inputs in addition to position. Keep the complete
+        // derived mesh layout here; extra attributes remain legal for legacy
+        // position-only custom casters, while trimming to position would make
+        // the built-in Surface shadow shader fail WebGPU validation.
+        buffers: [...ctx.vertexBuffers],
       },
       // Vertex-only depth pass writes `fragment: undefined` (GPU derives
       // depth from gl_Position.z). A custom ShadowCaster shader with a

package/src/pipeline-spec-types.ts

@@ -10,6 +10,8 @@ export interface PipelineSpec {
     readonly id: string;
     readonly passKind: string;
     readonly variantSet: string | undefined;
+    readonly vertexEntry?: string;
+    readonly fragmentEntry?: string;
   };
   readonly attachments: {
     readonly colorFormats: readonly GPUTextureFormat[];

package/src/pipeline-spec.ts

@@ -19,6 +19,7 @@
 
 import {
   deriveVertexBufferLayout,
+  deriveVertexBufferLayoutFromProjection,
   deriveVertexLayoutProjection,
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
@@ -247,7 +248,11 @@ export function cacheKeyOf(spec: PipelineSpec): string {
       stripSegment,
       `vl:${vlDigest}`,
       renderStateHash(renderState),
-    ].join(':') + uvSetCountSegment
+    ].join(':') +
+    uvSetCountSegment +
+    (shader.vertexEntry === undefined && shader.fragmentEntry === undefined
+      ? ''
+      : `:entries:${JSON.stringify([shader.vertexEntry ?? null, shader.fragmentEntry ?? null])}`)
   );
 }
 
@@ -407,25 +412,16 @@ export function buildPipelineDescriptor(
             ? { shaderUvSetCount: geometry.shaderUvSetCount }
             : {}),
         })
-      : geometry.vertexLayoutProjection.attributes.length === 0
-        ? []
-        : [
-            {
-              arrayStride: geometry.vertexLayoutProjection.arrayStride,
-              attributes: geometry.vertexLayoutProjection.attributes.map(
-                ({ shaderLocation, offset, format }) => ({
-                  shaderLocation,
-                  offset,
-                  format,
-                }),
-              ),
-            },
-          ];
+      : deriveVertexBufferLayoutFromProjection(geometry.vertexLayoutProjection, {
+          ...(geometry.shaderUvSetCount !== undefined
+            ? { shaderUvSetCount: geometry.shaderUvSetCount }
+            : {}),
+        });
 
   const descriptor: Record<string, unknown> = {
     vertex: {
       module: modules.vertex,
-      entryPoint: modules.vertexEntryPoint ?? 'vs_main',
+      entryPoint: spec.shader.vertexEntry ?? modules.vertexEntryPoint ?? 'vs_main',
       buffers: vertexBuffers,
     },
   };
@@ -434,7 +430,7 @@ export function buildPipelineDescriptor(
   if (attachments.colorFormats.length > 0) {
     descriptor.fragment = {
       module: modules.fragment,
-      entryPoint: modules.fragmentEntryPoint ?? 'fs_main',
+      entryPoint: spec.shader.fragmentEntry ?? modules.fragmentEntryPoint ?? 'fs_main',
       targets: attachments.colorFormats.map((fmt) => {
         const target: Record<string, unknown> = { format: fmt };
         if (renderState?.blend !== undefined) {

package/src/record/frame-snapshot.ts

@@ -18,6 +18,7 @@ import type { DirectionalShadowQuality } from '../components/directional-shadow-
 import type { EnvironmentGeneration } from '../environment/generation';
 import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import type { GpuBuffer } from '../gpu-resource';
+import type { InstanceCollectionId, InstanceResidency } from '../instances';
 import type { IblBindingInspection } from '../mesh-material-bindings';
 import type { StandardLightingInspection } from '../pipeline/standard-lighting/inspection';
 import type { PointShadowInspection } from '../point-shadow-inspection';
@@ -52,6 +53,17 @@ export function worldEntityKey(worldId: number, entityKey: number): number {
   return worldId * 4294967296 + entityKey; // 2^32 = 4294967296
 }
 
+/** Per-renderer projection identity, with entity keys for sprite/fold snapshots. */
+export function instanceCollectionCacheKey(
+  worldId: number,
+  instance: { readonly cacheKey: number; readonly collectionId?: number },
+): number {
+  // Keep collection entries in a disjoint numeric namespace from the shared
+  // legacy sprite/fold cache. Fold keys occupy -1..-(2^32), while ordinary
+  // world/entity keys are non-negative; this range starts below both.
+  return -(0x1_0000_0000 + worldEntityKey(worldId, instance.collectionId ?? instance.cacheKey));
+}
+
 /**
  * Cross-frame cache entry for a material bind group whose source material and
  * all resolved GPU resources are stable. The material snapshot identity is
@@ -289,8 +301,9 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
  * Owned by the `createRenderSystem` closure; advanced once per
  * `recordFrame` invocation. The `instanceBuffers` map holds the per-entity
  * GPU storage buffers for Instances-bearing entities (cache key = the
- * packed Entity u32 surfaced via `InstancesSnapshot.cacheKey`); entries
- * are recreated when the `archVersion` bumps or `byteLength` changes.
+ * renderer-owned collection id, with the packed Entity u32 retained only for
+ * legacy snapshots); entries are recreated when the `archVersion` bumps or
+ * `byteLength` changes.
  *
  * feat-20260518-pbr-direct-lighting-mvp M3 / w14 (AC-17 a): the
  * `warnedZeroLightStandard` flag latches the first-frame warning that
@@ -390,6 +403,10 @@ export interface RenderFrameState {
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
+  /** Renderer-owned collection owner used for record-stage residency facts. */
+  readonly instanceResidency?: Map<InstanceCollectionId, InstanceResidency>;
+  /** Stable buffers for renderer-owned collections split by device cap. */
+  readonly instanceBufferChunks?: Map<string, InstanceBufferCacheEntry>;
   /** Per-object ProbeBlendRecord buffers; upload is one atomic 160B write. */
   readonly probeBlendBuffers: Map<number, ProbeBlendBufferCacheEntry>;
   /** One renderer-owned record array; each object selects its 256B-aligned lane. */

package/src/record/frame.ts

@@ -1,3 +1,4 @@
+import { uploadMaterialUniforms } from './material-uniforms';
 // @forgeax/engine-runtime - RenderSystem record stage: frame.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
@@ -86,6 +87,7 @@ import {
   type DispatchCounts,
   type FrameObservationSource,
   getTextureIdentity,
+  instanceCollectionCacheKey,
   makeZeroCameraFallbackSnapshot,
   type ReflectionFallbackReadbackRequest,
   type RenderFrameState,
@@ -1924,7 +1926,11 @@ export function recordFrame(
     // the swap-chain fallback uses its raw storage view. The encoder and
     // sprite PSO must use the same resolved format because WebGPU requires
     // attachment and pipeline target formats to match.
-    const splitLdrSprite = computeSplitLdrSprite(validatedOrdered, tonemapActive);
+    const splitLdrSprite = computeSplitLdrSprite(
+      validatedOrdered,
+      tonemapActive,
+      transparentDispatch,
+    );
     let ldrSpritePassView: TextureView | null = null;
     if (splitLdrSprite) {
       const unormViewRes = internals.device.createTextureView(currentTexture, {});
@@ -2154,6 +2160,7 @@ export function recordFrame(
       directionalShadowCacheReuse: directionalShadowCache.reuse,
       ...(profilePhase !== undefined ? { profilePhase } : {}),
     };
+    uploadMaterialUniforms(passCtx);
     const fallbackReadbackRequest = createReflectionFallbackReadbackRequest(internals, frameState);
     if (fallbackReadbackRequest !== undefined) {
       frameState.reflectionFallbackReadback = fallbackReadbackRequest;
@@ -2993,8 +3000,14 @@ function cleanPerFrameCaches(
   // composites matching the write-side keys of #1-#3 — cross-world false eviction
   // is prevented because worldEntityKey(0, k) !== worldEntityKey(1, k).
   const validatedEntityKeys = new Set<number>(retainedEntityKeys);
+  const validatedInstanceKeys = new Set<number>(retainedEntityKeys);
   for (const v of validated) {
-    validatedEntityKeys.add(worldEntityKey(v.source.worldId, v.source.entityKey));
+    const entityKey = worldEntityKey(v.source.worldId, v.source.entityKey);
+    validatedEntityKeys.add(entityKey);
+    validatedInstanceKeys.add(entityKey);
+    if (v.source.instances !== undefined) {
+      validatedInstanceKeys.add(instanceCollectionCacheKey(v.source.worldId, v.source.instances));
+    }
   }
 
   // Clean per-entity material BG cache: drop outer-Map entries whose
@@ -3018,7 +3031,7 @@ function cleanPerFrameCaches(
   // material-handle-based and cross-world collision is semantically
   // correct (same material renders in same fold bucket).
   for (const [key, entry] of frameState.instanceBuffers.entries()) {
-    if (!validatedEntityKeys.has(key)) {
+    if (!validatedInstanceKeys.has(key)) {
       if (!entry.buffer.isDestroyed) {
         const r = entry.buffer.destroy();
         if (!r.ok) internals.errorRegistry.fire(r.error);
@@ -3027,6 +3040,28 @@ function cleanPerFrameCaches(
     }
   }
 
+  if (frameState.instanceResidency !== undefined) {
+    const liveCollections = new Set(validated.map((entry) => entry.source.instances?.collectionId));
+    for (const id of frameState.instanceResidency.keys()) {
+      if (!liveCollections.has(id)) frameState.instanceResidency.delete(id);
+    }
+  }
+
+  // Chunk keys are `${worldEntityKey}:${chunkStart}`. Keep the key opaque to
+  // the authoring API, but retain the numeric owner prefix for eviction.
+  if (frameState.instanceBufferChunks !== undefined) {
+    for (const [key, entry] of frameState.instanceBufferChunks.entries()) {
+      const separator = key.indexOf(':');
+      const ownerKey = separator < 0 ? Number.NaN : Number(key.slice(0, separator));
+      if (validatedInstanceKeys.has(ownerKey)) continue;
+      if (!entry.buffer.isDestroyed) {
+        const r = entry.buffer.destroy();
+        if (!r.ok) internals.errorRegistry.fire(r.error);
+      }
+      frameState.instanceBufferChunks.delete(key);
+    }
+  }
+
   if (frameState.morphBuffers !== undefined) {
     for (const [key, entry] of frameState.morphBuffers.entries()) {
       if (validatedEntityKeys.has(key)) continue;