@forgeax/engine-shader 0.1.24 → 0.1.25

package/README.md

@@ -22,6 +22,82 @@ second manifest or registry.
 > Runtime 只查找已发布的 content-addressed artifact；恢复沿 producer、cook
 > 与 catalog 的 owner 边界进行，不在 app 侧复制 shader artifact。
 
+## Standard Surface contract
+
+Standard material 的作者只需要通过 `#import` 使用
+[`surface_v1.wgsl`](./src/surface_v1.wgsl)，并实现唯一的
+`evaluate_surface(SurfaceInput) -> SurfaceData`。`SurfaceData` 是 Standard
+BRDF 的输入，不是最终颜色；Engine-owned Standard pass family 负责顶点、光照、
+阴影、Forward/Deferred、G-buffer、雾和输出。内建默认值位于
+[`default_standard_surface.wgsl`](./src/default_standard_surface.wgsl)。
+
+### Minimal authoring shape
+
+`SurfaceData` is deliberately base-only. Its frozen field order is:
+
+| Order | Field | Meaning |
+|:--:|:--|:--|
+| 1 | `baseColor: vec3<f32>` | Base reflectance color |
+| 2 | `normalWS: vec3<f32>` | World-space shading normal |
+| 3 | `metallic: f32` | Metallic factor |
+| 4 | `roughness: f32` | Roughness factor |
+| 5 | `emissive: vec3<f32>` | Emissive contribution |
+| 6 | `occlusion: f32` | Ambient occlusion factor |
+| 7 | `opacity: f32` | Surface opacity |
+| 8 | `alphaClipThreshold: f32` | Alpha-test threshold |
+
+```wgsl
+#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}
+
+fn evaluate_surface(input: SurfaceInput) -> SurfaceData {
+  return SurfaceData(
+    vec3<f32>(0.45, 0.18, 0.06), input.geometricNormalWS, 0.8, 0.42,
+    vec3<f32>(0.0), 1.0, 1.0, 0.5,
+  );
+}
+```
+
+The matching TypeScript entry is also import-first: the caller names the
+compiled Surface module and supplies only its parameters and values. The
+Engine still owns stage entry points, bindings, BRDF composition, and pass
+projection.
+
+```ts
+import { Materials } from '@forgeax/engine-render';
+
+const rustedIron = Materials.standard({
+  surfaceModule: 'game_3d::rusted_iron_surface',
+  parameters: [
+    { name: 'ironColor', type: 'color' },
+    { name: 'rustDark', type: 'color' },
+    { name: 'rustBright', type: 'color' },
+    { name: 'noiseScale', type: 'f32', default: 1.85 },
+  ],
+  values: {
+    ironColor: [0.4, 0.45, 0.47, 1],
+    rustDark: [0.42, 0.085, 0.018, 1],
+    rustBright: [0.95, 0.34, 0.055, 1],
+    noiseScale: 1.85,
+  },
+});
+```
+
+For the complete source-to-runtime example, see the
+[`game-3d` rusted-iron fixture](../../templates/game-3d/README.md#import-first-surface-material-example).
+
+> [!CAUTION]
+> Surface is a base-facts function only. Do not add `clearcoat`,
+> `clearcoatRoughness`, other physical-layer fields, stage entries, resource
+> bindings, Engine entry points, or vertex-position mutation. Physical layers
+> and pass admission remain Engine-owned.
+
+渐进导航：`Materials.standard()` → `moduleSlots.surface` → build-time
+`#import` composition / reflection → Pack cook → runtime GUID readiness。
+Surface source 不声明 stage entry、`@group/@binding` 或 vertex mutation；参数
+资源由同一 `MaterialAsset.parameters` contract 派生。编译或 cook 失败时读取
+`code`、`detail`、`hint`，修复 authored source 或 producer 后重新 cook，不在
+runtime 读取 raw WGSL 或创建 app-local artifact。
+
 > [!IMPORTANT]
 > A custom material starts as WGSL source plus one `MaterialAsset` contract. The build manifest publishes the composed module and the material cook publishes the resolved record, artifact bytes, references, and receipt. Runtime resolves those facts from the catalog; application code does not install or duplicate shader artifacts. The recovery route is always source or cook repair.
 
@@ -101,10 +177,19 @@ code-specific `detail` and `hint`:
 | `shader-module-not-found` | The published module is absent | Add it to the build source catalog and rebuild |
 | `material-specialization-not-cooked` | No runtime artifact exists for the selection | Run the cook path and publish its record |
 | `material-specialization-stale-generation` | A dependency changed after cooking | Wait for dependencies to settle and re-cook |
+| `material-surface-slot-missing` | Standard pass has no `surface` module slot | Add the slot to the authored pass and re-cook |
+| `material-surface-abi-mismatch` | Surface export does not match `surface_v1` | Repair `evaluate_surface` signature and re-cook |
+| `material-surface-forbidden-interface` | Surface declares a stage, resource, or vertex mutation | Remove the forbidden interface and re-cook |
+| `material-physical-contract-invalid` | A root physical layer is incomplete or unsupported | Repair the root parameter fragment before composing or cooking |
 
 Never hide one of these errors by creating an app-local artifact or changing a
 demo's material shape.
 
+For the canonical error detail and executable recovery fields, use
+[`material/errors.ts`](../types/src/material/errors.ts). The producer recovery
+path is `inspect -> repair authored source -> cold-cook -> verify publication`;
+runtime does not reinterpret a Surface error.
+
 ## Temporal-v1 accessor
 
 `forgeax_scene_temporal` is the single WGSL accessor ABI for the
@@ -178,3 +263,15 @@ layout.
 - [`@forgeax/engine-types` MaterialAsset](../types/README.md#materialasset-route)
 - [`@forgeax/engine-pack` cook contract](../pack/README.md#materialasset-cook-contract)
 - [`MaterialAsset migration`](https://github.com/ForgeaXGame/forgeax-engine-harness/blob/main/docs/material-asset-migration.md)
+
+## Surface authoring checklist
+
+- [x] Import `forgeax_material::surface_v1` and return the eight-field `SurfaceData`.
+- [x] Read generated material parameters through `forgeax_material::parameters`.
+- [x] Keep vertex, light, BRDF, pass, binding, and output ownership in Engine modules.
+- [x] Let the root parameter contract determine physical layers and pass admission.
+- [ ] Add an engine entry point or resource binding to a Surface module.
+
+The final unchecked item is intentionally forbidden. If an effect needs its own
+entry points or render targets, declare an explicit full-custom material and
+publish its pass/lane provenance instead of disguising it as a Standard Surface.

package/dist/index.d.ts

@@ -16,13 +16,21 @@ export declare const BUILTIN_MATERIAL_MODULES: {
     readonly unlit: "forgeax_material::unlit";
     readonly sprite: "forgeax_material::sprite";
 };
+/**
+ * The engine-owned Standard Surface selected by a built-in Standard material.
+ * Keep this explicit in the authored pass so the build-time cooker sees the
+ * same slot contract as Materials.standard().
+ */
+export declare const DEFAULT_STANDARD_SURFACE_MODULE: "forgeax_material::default_standard_surface";
 /** Stable build-time module id for the temporal-v1 accessor owner. */
 export declare const SCENE_DATA_TEMPORAL_V1_SHADER_MODULE: "forgeax_scene_temporal";
 /**
  * Material modules whose shader source and parameter contract are owned by
  * the Engine. They live in the runtime ShaderRegistry, so a Pack containing
  * one of these materials carries authored values only and does not require a
- * project material-cook artifact.
+ * project material-cook artifact. A Standard pass with a project Surface slot
+ * is deliberately excluded: its root composition is project-owned and must
+ * arrive with a cooked material publication.
  */
 export declare const ENGINE_MATERIAL_MODULES: readonly ["forgeax::default-standard-pbr", "forgeax::pbr-skin", "forgeax::default-standard-pbr-skin", "forgeax::default-unlit", "forgeax::default-shadow-caster", "forgeax::sprite", "forgeax::sprite-lit", "forgeax::msdf-text", "forgeax_material::standard", "forgeax_material::unlit", "forgeax_material::sprite", "forgeax_material::sprite-lit"];
 /** Names of the zero-binding Standard reflection-probe shader helpers. */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAoC,MAAM,uBAAuB,CAAC;AAG7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EACL,GAAG,EACH,iBAAiB,EACjB,sBAAsB,EACtB,EAAE,EACF,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,wBAAwB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,0BAA0B,EAC1B,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,EAClC,oCAAoC,EACpC,gCAAgC,EAChC,8BAA8B,EAC9B,KAAK,4BAA4B,EACjC,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,KAAK,aAAa,GACnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,eAAO,MAAM,2BAA2B,EAAG,6BAAsC,CAAC;AAClF,OAAO,EACL,4BAA4B,EAC5B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EAClC,cAAc,EACd,cAAc,IAAI,aAAa,EAC/B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,IAAI,mBAAmB,EAChD,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,IAAI,oBAAoB,GACnD,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,KAAK,2BAA2B,EAChC,KAAK,6BAA6B,GACnC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX,sEAAsE;AACtE,eAAO,MAAM,oCAAoC,EAAG,wBAAiC,CAAC;AAEtF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,wVAa1B,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,+BAA+B,2DAGjC,CAAC;AAEZ,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAGjF;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AA0BxE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,mBAAmB,GAAG,aAAa,CAOnF;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,UAAO,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAoC,MAAM,uBAAuB,CAAC;AAG7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EACL,GAAG,EACH,iBAAiB,EACjB,sBAAsB,EACtB,EAAE,EACF,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,wBAAwB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,0BAA0B,EAC1B,0BAA0B,EAC1B,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,EAClC,oCAAoC,EACpC,gCAAgC,EAChC,8BAA8B,EAC9B,KAAK,4BAA4B,EACjC,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,KAAK,aAAa,GACnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,eAAO,MAAM,2BAA2B,EAAG,6BAAsC,CAAC;AAClF,OAAO,EACL,4BAA4B,EAC5B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EAClC,cAAc,EACd,cAAc,IAAI,aAAa,EAC/B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,IAAI,mBAAmB,EAChD,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,IAAI,oBAAoB,GACnD,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,KAAK,2BAA2B,EAChC,KAAK,6BAA6B,GACnC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAC1C,4CAAqD,CAAC;AAExD,sEAAsE;AACtE,eAAO,MAAM,oCAAoC,EAAG,wBAAiC,CAAC;AAEtF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,wVAa1B,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,+BAA+B,2DAGjC,CAAC;AAEZ,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAWjF;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AA0BxE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,mBAAmB,GAAG,aAAa,CAiBnF;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,UAAO,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.mjs

@@ -33106,18 +33106,35 @@ function hashLtcTable(table) {
 function equalBytes(left, right) {
   return left.length === right.length && left.every((value, index) => value === right[index]);
 }
+function equalParamSchema(left, right) {
+  return JSON.stringify(left.metadata?.paramSchema) === JSON.stringify(right.metadata?.paramSchema);
+}
 var MaterialArtifactRegistry = class {
   #artifacts = /* @__PURE__ */ new Map();
   register(artifact) {
     const previous = this.#artifacts.get(artifact.key);
     if (previous !== void 0) {
-      if (equalBytes(previous.bytes, artifact.bytes)) return ok(previous);
+      if (equalBytes(previous.bytes, artifact.bytes)) {
+        if (equalParamSchema(previous, artifact)) return ok(previous);
+        return err({
+          code: "material-artifact-conflict",
+          expected: "one immutable parameter schema per specialization key",
+          hint: "re-cook the conflicting specialization with one canonical parameter schema",
+          detail: {
+            key: artifact.key,
+            dimension: "param-schema",
+            ...previous.digest ? { existingDigest: previous.digest } : {},
+            ...artifact.digest ? { incomingDigest: artifact.digest } : {}
+          }
+        });
+      }
       return err({
         code: "material-artifact-conflict",
         expected: "one immutable artifact byte sequence per specialization key",
         hint: "re-cook the conflicting specialization and publish one artifact digest",
         detail: {
           key: artifact.key,
+          dimension: "bytes",
           ...previous.digest ? { existingDigest: previous.digest } : {},
           ...artifact.digest ? { incomingDigest: artifact.digest } : {}
         }
@@ -33585,6 +33602,7 @@ var BUILTIN_MATERIAL_MODULES = {
   unlit: "forgeax_material::unlit",
   sprite: "forgeax_material::sprite"
 };
+var DEFAULT_STANDARD_SURFACE_MODULE = "forgeax_material::default_standard_surface";
 var SCENE_DATA_TEMPORAL_V1_SHADER_MODULE = "forgeax_scene_temporal";
 var ENGINE_MATERIAL_MODULES = [
   "forgeax::default-standard-pbr",
@@ -33609,7 +33627,9 @@ function isEngineMaterialModule(module) {
 }
 function isEngineMaterial(material) {
   const passes = material.passes ?? [];
-  return passes.length > 0 && passes.every((pass) => isEngineMaterialModule(pass.program.module));
+  return passes.length > 0 && passes.every(
+    (pass) => isEngineMaterialModule(pass.program.module) && (pass.program.moduleSlots?.surface === void 0 || pass.program.moduleSlots.surface === DEFAULT_STANDARD_SURFACE_MODULE)
+  );
 }
 var BUILTIN_PARAMETERS = {
   standard: [
@@ -33634,13 +33654,21 @@ var BUILTIN_VALUES = {
 function createBuiltinMaterialAsset(kind) {
   return {
     kind: "material",
-    passes: [{ name: "forward", program: { module: BUILTIN_MATERIAL_MODULES[kind] } }],
+    passes: [
+      {
+        name: "forward",
+        program: {
+          module: BUILTIN_MATERIAL_MODULES[kind],
+          ...kind === "standard" ? { moduleSlots: { surface: DEFAULT_STANDARD_SURFACE_MODULE } } : {}
+        }
+      }
+    ],
     parameters: BUILTIN_PARAMETERS[kind],
     values: BUILTIN_VALUES[kind]
   };
 }
 var TONEMAP_LUMINANCE_EPSILON = 1e-5;
 
-export { BUILTIN_MATERIAL_MODULES, DEFAULT_MSDF_TEXT_PARAM_SCHEMA, DEFAULT_SPRITE_PARAM_SCHEMA, DEFAULT_STANDARD_PBR_PARAM_SCHEMA, DEFAULT_UNLIT_PARAM_SCHEMA, ENGINE_MATERIAL_MODULES, FORGEAX_RESERVED_PATH_PREFIX, LTC_SOURCE_PROVENANCE, LTC_TABLES, LTC_TABLE_HASHES, LTC_TABLE_HEIGHT, LTC_TABLE_INPUT_HASHES, LTC_TABLE_WIDTH, MaterialArtifactRegistry, RECT_AREA_LTC_SHADER_MODULE, REFLECTION_PROBE_SHADER_HELPERS, SCENE_DATA_TEMPORAL_V1_SHADER_MODULE, STANDARD_BASE_PARAM_SCHEMA, STANDARD_PBR_ALPHA_CUTOFF_DEFAULT, STANDARD_PBR_ARTIFACT_RECEIPT, STANDARD_PBR_SKIN_ARTIFACT_RECEIPT, STANDARD_PHYSICAL_LAYER_PARAM_SCHEMA, STANDARD_PIPELINE_PARAM_SCHEMA, ShaderRegistry as ShaderCatalog, ShaderError, ShaderRegistry, TONEMAP_LUMINANCE_EPSILON, TONEMAP_SHADER_MODE, createBuiltinMaterialAsset, createStandardPbrArtifactReceipt, findVariantByKey, generateLtcTables, hashLtcTable, isEngineMaterial, isEngineMaterialModule, isMaterialShaderArtifact, manifestMalformed, materialShaderNotFound, registerDefaultSpriteLit, registerDefaultStandardPbrSkin, shaderNotFound };
+export { BUILTIN_MATERIAL_MODULES, DEFAULT_MSDF_TEXT_PARAM_SCHEMA, DEFAULT_SPRITE_PARAM_SCHEMA, DEFAULT_STANDARD_PBR_PARAM_SCHEMA, DEFAULT_STANDARD_SURFACE_MODULE, DEFAULT_UNLIT_PARAM_SCHEMA, ENGINE_MATERIAL_MODULES, FORGEAX_RESERVED_PATH_PREFIX, LTC_SOURCE_PROVENANCE, LTC_TABLES, LTC_TABLE_HASHES, LTC_TABLE_HEIGHT, LTC_TABLE_INPUT_HASHES, LTC_TABLE_WIDTH, MaterialArtifactRegistry, RECT_AREA_LTC_SHADER_MODULE, REFLECTION_PROBE_SHADER_HELPERS, SCENE_DATA_TEMPORAL_V1_SHADER_MODULE, STANDARD_BASE_PARAM_SCHEMA, STANDARD_PBR_ALPHA_CUTOFF_DEFAULT, STANDARD_PBR_ARTIFACT_RECEIPT, STANDARD_PBR_SKIN_ARTIFACT_RECEIPT, STANDARD_PHYSICAL_LAYER_PARAM_SCHEMA, STANDARD_PIPELINE_PARAM_SCHEMA, ShaderRegistry as ShaderCatalog, ShaderError, ShaderRegistry, TONEMAP_LUMINANCE_EPSILON, TONEMAP_SHADER_MODE, createBuiltinMaterialAsset, createStandardPbrArtifactReceipt, findVariantByKey, generateLtcTables, hashLtcTable, isEngineMaterial, isEngineMaterialModule, isMaterialShaderArtifact, manifestMalformed, materialShaderNotFound, registerDefaultSpriteLit, registerDefaultStandardPbrSkin, shaderNotFound };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map