@forgeax/engine-render 0.1.23 → 0.1.25

package/src/assembly/material/__tests__/standard-layer-plan-projection.integration.test.ts

@@ -0,0 +1,18 @@
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { projectStandardSurfacePasses } from '../surface-projection.js';
+
+describe('StandardLayerPlan pass projection', () => {
+  it('keeps a physical Standard material on Forward and shadow passes', () => {
+    const plan = deriveStandardLayerPlan([
+      { name: 'clearcoat', type: 'f32' },
+      { name: 'clearcoatRoughness', type: 'f32' },
+    ]);
+    const passes = projectStandardSurfacePasses({
+      surfaceModule: 'game::surface',
+      values: {},
+      layerPlan: plan,
+    });
+    expect(passes.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+});

package/src/assembly/material/__tests__/surface-pass-projection.integration.test.ts

@@ -0,0 +1,62 @@
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  projectStandardSurfacePasses,
+  type StandardSurfaceProjectionOptions,
+} from '../surface-projection';
+
+type SurfaceFixture = StandardSurfaceProjectionOptions & {
+  readonly geometryVariant: 'rigid' | 'skinned' | 'instanced';
+  readonly lightingLane: 'direct' | 'clustered';
+  readonly alphaClip: boolean;
+};
+
+const fixture = (geometryVariant: SurfaceFixture['geometryVariant']): SurfaceFixture => ({
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  values: { ironColor: [0.42, 0.47, 0.5, 1] },
+  geometryVariant,
+  lightingLane: geometryVariant === 'instanced' ? 'clustered' : 'direct',
+  alphaClip: geometryVariant === 'skinned',
+});
+
+function tagsFor(pass: ReturnType<typeof projectStandardSurfacePasses>[number]) {
+  return pass.renderState?.tags as Record<string, string>;
+}
+
+describe('Standard Surface pass projection', () => {
+  it.each([
+    'rigid',
+    'skinned',
+    'instanced',
+  ] as const)('projects one %s Surface closure into every Standard pass', (geometryVariant) => {
+    const options = fixture(geometryVariant);
+    const passes = projectStandardSurfacePasses(options);
+
+    expect(passes.map((pass) => pass.name)).toEqual(['forward', 'deferred', 'shadow-caster']);
+    for (const pass of passes) {
+      expect(pass.program.moduleSlots?.surface).toBe(options.surfaceModule);
+      expect(tagsFor(pass)).toMatchObject({
+        SurfaceModule: options.surfaceModule,
+        GeometryVariant: geometryVariant,
+        LightingLane: options.lightingLane,
+        AlphaClip: options.alphaClip ? 'enabled' : 'disabled',
+      });
+    }
+  });
+
+  it('keeps base Standard on Deferred while physical Standard stays Forward-only', () => {
+    const base = projectStandardSurfacePasses({
+      ...fixture('rigid'),
+      layerPlan: deriveStandardLayerPlan([]),
+    });
+    const physical = projectStandardSurfacePasses({
+      ...fixture('rigid'),
+      layerPlan: deriveStandardLayerPlan([
+        { name: 'clearcoat', type: 'f32' },
+        { name: 'clearcoatRoughness', type: 'f32' },
+      ]),
+    });
+    expect(base.map((pass) => pass.name)).toEqual(['forward', 'deferred', 'shadow-caster']);
+    expect(physical.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+});

package/src/assembly/material/assembly.ts

@@ -1,5 +1,9 @@
-import type { CookedMaterialRecord } from '@forgeax/engine-pack/material-cook';
-import type { MaterialValue } from '@forgeax/engine-types';
+import {
+  type CookedMaterialRecord,
+  materialLayerPlanIdentity,
+} from '@forgeax/engine-pack/material-cook';
+import type { MaterialValue, StandardLayerPlan } from '@forgeax/engine-types';
+import { projectStandardLayerPlan } from './standard-layer-projection.js';
 
 export interface MaterialRenderPassProjection {
   readonly name: string;
@@ -18,6 +22,7 @@ export interface MaterialRenderProjection {
   readonly passes: readonly MaterialRenderPassProjection[];
   readonly runtimeValues: Readonly<Record<string, MaterialValue | null>>;
   readonly staticSelection: readonly string[];
+  readonly layerPlan: StandardLayerPlan;
 }
 
 function projectPass(
@@ -37,6 +42,16 @@ function projectPass(
 }
 
 export function assembleMaterialProjection(record: CookedMaterialRecord): MaterialRenderProjection {
+  const layerPlan = projectStandardLayerPlan(record.resolved.parameters, record.resolved.passes);
+  const expectedLayerPlanIdentity = materialLayerPlanIdentity(record);
+  if (
+    expectedLayerPlanIdentity !== undefined &&
+    record.receipt.derivedInterface.layerPlanIdentity !== expectedLayerPlanIdentity
+  ) {
+    throw new Error(
+      `Standard material layer-plan identity mismatch: expected ${expectedLayerPlanIdentity}, got ${record.receipt.derivedInterface.layerPlanIdentity ?? 'missing'}`,
+    );
+  }
   return {
     materialGuid: record.guid,
     specializationKey: record.specializationKey ?? record.receipt.identity.programIdentity,
@@ -44,5 +59,6 @@ export function assembleMaterialProjection(record: CookedMaterialRecord): Materi
     passes: record.resolved.passes.map((pass) => projectPass(record, pass)),
     runtimeValues: record.resolved.values,
     staticSelection: [],
+    layerPlan,
   };
 }

package/src/assembly/material/standard-layer-projection.ts

@@ -0,0 +1,16 @@
+import type { MaterialParameter, MaterialPass, StandardLayerPlan } from '@forgeax/engine-types';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+
+/**
+ * Renderer projection of the compiler-owned Standard layer contract.
+ *
+ * The renderer receives the prepared parameter/pass snapshot and never keeps
+ * a second parameter-name inventory. This function is intentionally pure so
+ * assembly and tests observe the same mode and pass family as cooking.
+ */
+export function projectStandardLayerPlan(
+  parameters: readonly MaterialParameter[],
+  passes: readonly MaterialPass[],
+): StandardLayerPlan {
+  return deriveStandardLayerPlan(parameters, passes);
+}

package/src/assembly/material/surface-projection.ts

@@ -0,0 +1,90 @@
+import { DEFAULT_STANDARD_SURFACE_MODULE } from '@forgeax/engine-shader';
+import type {
+  MaterialPass,
+  MaterialRenderState,
+  MaterialValue,
+  StandardLayerPlan,
+} from '@forgeax/engine-types';
+
+export const STANDARD_MATERIAL_MODULE = 'forgeax_material::standard';
+export { DEFAULT_STANDARD_SURFACE_MODULE };
+
+export type StandardSurfacePassName = 'forward' | 'deferred' | 'shadow-caster';
+export type StandardSurfaceGeometryVariant = 'rigid' | 'skinned' | 'instanced';
+export type StandardSurfaceLightingLane = 'direct' | 'clustered';
+export type StandardSurfaceKind = 'standard' | 'full-custom';
+
+export interface StandardSurfaceProjectionOptions {
+  readonly surfaceModule: string;
+  readonly values: Readonly<Record<string, MaterialValue | null>>;
+  readonly renderState?: MaterialRenderState;
+  readonly castShadow?: boolean;
+  readonly queue?: number;
+  readonly geometryVariant?: StandardSurfaceGeometryVariant;
+  readonly lightingLane?: StandardSurfaceLightingLane;
+  readonly alphaClip?: boolean;
+  readonly surfaceKind?: StandardSurfaceKind;
+  readonly declaredPasses?: readonly StandardSurfacePassName[];
+  readonly layerPlan?: StandardLayerPlan;
+}
+
+function pass(
+  name: StandardSurfacePassName,
+  options: StandardSurfaceProjectionOptions,
+  fragmentEntry: string,
+): MaterialPass {
+  const authoredState = options.renderState ?? {};
+  const authoredRecord = authoredState as Readonly<Record<string, unknown>>;
+  const tags = (authoredRecord.tags ?? {}) as Readonly<Record<string, string>>;
+  const lightMode =
+    name === 'shadow-caster' ? 'ShadowCaster' : name === 'forward' ? 'Forward' : 'Deferred';
+  return {
+    name,
+    program: {
+      module: STANDARD_MATERIAL_MODULE,
+      fragmentEntry,
+      moduleSlots: { surface: options.surfaceModule },
+    },
+    renderState: {
+      ...authoredState,
+      tags:
+        options.surfaceModule === DEFAULT_STANDARD_SURFACE_MODULE
+          ? { LightMode: lightMode, ...tags }
+          : {
+              ...tags,
+              LightMode: lightMode,
+              SurfaceModule: options.surfaceModule,
+              SurfaceKind: options.surfaceKind ?? 'standard',
+              GeometryVariant: options.geometryVariant ?? 'rigid',
+              LightingLane: options.lightingLane ?? 'direct',
+              AlphaClip: options.alphaClip === true ? 'enabled' : 'disabled',
+            },
+      ...(options.queue === undefined ? {} : { queue: options.queue }),
+    },
+  };
+}
+
+/** Project one custom or default Surface into the existing Standard pass family. */
+export function projectStandardSurfacePasses(
+  options: StandardSurfaceProjectionOptions,
+): [MaterialPass, ...MaterialPass[]] {
+  const authoredPasses = options.declaredPasses;
+  const passNames: StandardSurfacePassName[] =
+    options.surfaceKind === 'full-custom' && authoredPasses !== undefined
+      ? [...authoredPasses]
+      : (['forward'] as StandardSurfacePassName[]);
+  if (authoredPasses === undefined || options.surfaceKind !== 'full-custom') {
+    const blended = options.renderState?.blend !== undefined;
+    if (!blended && options.layerPlan?.mode !== 'physical') passNames.push('deferred');
+    if (options.castShadow !== false) passNames.push('shadow-caster');
+  }
+  const entries = passNames.map((name) =>
+    pass(
+      name,
+      options,
+      name === 'forward' ? 'fs_main' : name === 'deferred' ? 'fs_gbuffer' : 'fs_shadow',
+    ),
+  );
+  const passes = entries as [MaterialPass, ...MaterialPass[]];
+  return passes;
+}