reze-engine 0.18.1 → 0.19.0

package/src/graph/compile.ts

@@ -8,6 +8,7 @@ import type { Diagnostic, ExposedParam, GraphNode, SocketValue, StyleGraph } fro
 import { NODE_REGISTRY, canConvert, convert, fmtValue, literalFits } from "./registry"
 import type { NodeSpec, SockT } from "./registry"
 import { assembleModule } from "./slots"
+import type { AlphaMode, RenderClass } from "./render-class"
 
 export type CompileOptions = {
   /** Fold exposed params to their defaults as consts (no StyleUniforms binding).
@@ -16,6 +17,11 @@ export type CompileOptions = {
   /** Override the graph output with any node's socket — Blender's node-preview
    *  (Ctrl+Shift+Click viewer) workflow for the editor. */
   previewNode?: { node: string; socket: string }
+  /** Pass-integration class the fs() shell is assembled for (stencil/cull/gate). The
+   *  graph is pure shading; the group supplies this. Default "auto". */
+  renderClass?: RenderClass
+  /** Alpha-handling axis, orthogonal to renderClass. Default "opaque". */
+  alphaMode?: AlphaMode
 }
 
 /** UBO slot for one exposed param: write `value` at style.p[vec4Index] (+ component). */
@@ -337,6 +343,6 @@ export function compileGraph(graph: StyleGraph, opts: CompileOptions = {}): Comp
   lines.push(`  let final_color = ${outputExpr(out, "color")}; // @node:${out.node}`)
 
   const fsBody = lines.join("\n")
-  const wgsl = assembleModule(graph.slot, fsBody, usesStyle.current)
+  const wgsl = assembleModule(opts.renderClass ?? "auto", opts.alphaMode ?? "opaque", fsBody, usesStyle.current)
   return { ok: true, wgsl, fsBody, slotMap, diagnostics, prunedNodes }
 }

package/src/graph/presets/body.ts

@@ -8,7 +8,7 @@ import type { StyleGraph } from "../schema"
 export const BODY_GRAPH: StyleGraph = {
   version: 1,
   name: "Body",
-  slot: "body",
+  tags: ["body"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/cloth_rough.ts

@@ -8,7 +8,7 @@ import type { StyleGraph } from "../schema"
 export const CLOTH_ROUGH_GRAPH: StyleGraph = {
   version: 1,
   name: "Rough Cloth",
-  slot: "cloth_rough",
+  tags: ["cloth_rough"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/cloth_smooth.ts

@@ -8,7 +8,7 @@ import type { StyleGraph } from "../schema"
 export const CLOTH_SMOOTH_GRAPH: StyleGraph = {
   version: 1,
   name: "Smooth Cloth",
-  slot: "cloth_smooth",
+  tags: ["cloth_smooth"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/default.ts

@@ -9,7 +9,7 @@ import type { StyleGraph } from "../schema"
 export const DEFAULT_GRAPH: StyleGraph = {
   version: 1,
   name: "Principled BSDF",
-  slot: "default",
+  tags: ["default"],
   nodes: [
     { id: "tex", type: "texture" },
     {

package/src/graph/presets/eye.ts

@@ -12,7 +12,7 @@ import type { StyleGraph } from "../schema"
 export const EYE_GRAPH: StyleGraph = {
   version: 1,
   name: "Eye",
-  slot: "eye",
+  tags: ["eye"],
   nodes: [
     { id: "tex", type: "texture" },
     {

package/src/graph/presets/face.ts

@@ -11,7 +11,7 @@ import type { StyleGraph } from "../schema"
 export const FACE_GRAPH: StyleGraph = {
   version: 1,
   name: "Face",
-  slot: "face",
+  tags: ["face"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/hair.ts

@@ -15,7 +15,7 @@ import type { StyleGraph } from "../schema"
 export const HAIR_GRAPH: StyleGraph = {
   version: 1,
   name: "Hair",
-  slot: "hair",
+  tags: ["hair"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/metal.ts

@@ -9,7 +9,7 @@ import type { StyleGraph } from "../schema"
 export const METAL_GRAPH: StyleGraph = {
   version: 1,
   name: "Metal",
-  slot: "metal",
+  tags: ["metal"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/stockings.ts

@@ -11,7 +11,7 @@ import type { StyleGraph } from "../schema"
 export const STOCKINGS_GRAPH: StyleGraph = {
   version: 1,
   name: "Stockings",
-  slot: "stockings",
+  tags: ["stockings"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/render-class.ts

@@ -0,0 +1,33 @@
+// Render-class + alpha-mode: the small, closed, engine-owned vocabularies that carry
+// pass integration for a style group. A group's node graph is pure shading; these select
+// how the engine wires that shading into the passes. Not user-extensible — this is where
+// rendering correctness lives (stencil, cull, draw order, alpha test). See
+// docs/style-groups-spec.md §5.
+
+/** Pass-integration class. Selects stencil/cull/draw-order behavior. */
+export type RenderClass = "auto" | "eye" | "hair"
+
+/** Alpha-handling axis, orthogonal to RenderClass. "hashed" = Wyman & McGuire object-space
+ *  hashed alpha test (stockings); "opaque" = the standard near-zero threshold discard. */
+export type AlphaMode = "opaque" | "hashed"
+
+/** Descriptive manifest for hosts (reze-design) so the render-class picker is data-driven
+ *  instead of hardcoding strings. The effect implementations stay engine-side; this only
+ *  describes them. `pairsWith` = the effect needs a counterpart class present to show. */
+export type RenderClassInfo = {
+  id: RenderClass
+  label: string
+  description: string
+  pairsWith?: RenderClass
+}
+
+export const RENDER_CLASSES: readonly RenderClassInfo[] = [
+  { id: "auto", label: "Standard", description: "Opaque or transparent, derived from material alpha." },
+  { id: "eye", label: "Eye", description: "Stamps the see-through stencil; visible through hair.", pairsWith: "hair" },
+  {
+    id: "hair",
+    label: "Hair",
+    description: "Reads the eye stencil so eyes show through the silhouette.",
+    pairsWith: "eye",
+  },
+]

package/src/graph/schema.ts

@@ -3,8 +3,6 @@
 // time (Blender Normal Z → engine Y), the compiler never sees Blender conventions.
 // See docs/graph-compiler-spec.md.
 
-import type { MaterialPreset } from "../engine"
-
 export type SocketValue = number | [number, number, number] | [number, number, number, number]
 
 export type GraphNode = {
@@ -39,15 +37,15 @@ export type ExposedParam = {
 export type StyleGraph = {
   version: 1
   name: string
-  /** Which preset slot this style targets. The slot owns pass integration (stencil
-   *  variants like hair-over-eyes, alpha semantics, draw order) — always on,
-   *  graph-invisible. The graph only restyles the slot's shading. */
-  slot: MaterialPreset
   nodes: GraphNode[]
   links: GraphLink[]
   /** Must resolve to a color (vec3f) or float (auto-splatted) socket. */
   output: { node: string; socket: string }
   params?: ExposedParam[]
+  /** Soft, host-only hints for library filtering and smart default-group / render-class
+   *  matching (e.g. ["hair"]). Ignored by the compiler; round-tripped. A graph is pure
+   *  shading — pass integration lives on the style group's renderClass, not here. */
+  tags?: string[]
 }
 
 export type Diagnostic = {

package/src/graph/slots.ts

@@ -1,52 +1,24 @@
-// Per-slot WGSL templates. The graph computes only `final_color`; everything the slot
-// owns — texture sample, MMD alpha semantics, discard, lighting context, FSOut/mask
-// writes, and built-in pass effects like hair's over-eyes stencil variant — lives here,
-// always on, graph-invisible. Mirrors the hand-written material shaders line-for-line.
+// fs() shell assembly. The graph computes only `final_color`; everything around it —
+// texture sample, alpha discard, lighting context, built-in gates, and the FSOut/mask
+// write — is composed here from two orthogonal, engine-owned axes:
+//   RenderClass ("auto" | "eye" | "hair")  — stencil/cull/draw-order + eye rear-gate +
+//                                             hair over-eyes alpha. See render-class.ts.
+//   AlphaMode   ("opaque" | "hashed")       — standard threshold discard vs Wyman hashed.
+// A style group supplies both; this file turns them into the WGSL shell around fsBody.
+// See docs/style-groups-spec.md §5, §7.
 
 import { NODES_WGSL } from "../shaders/materials/nodes"
 import { COMMON_MATERIAL_PRELUDE_WGSL } from "../shaders/materials/common"
-import type { MaterialPreset } from "../engine"
+import type { AlphaMode, RenderClass } from "./render-class"
 
-export type SlotTemplate = {
-  /** Module-scope declarations (pipeline-override constants, helper fns). */
-  decls: string
-  /** Optional replacement for the standard fs() prelude (custom alpha semantics). */
-  prelude?: string
-  /** Tail of fs(): consumes `final_color` + template locals, writes FSOut. */
-  epilogue: string
-}
+// ── Module-scope declarations ──
+// hair: the over-eyes pipeline-override constant (a second pipeline is compiled with
+// IS_OVER_EYES=1). hashed: the Wyman & McGuire object-space hashed-alpha helpers.
+const HAIR_OVER_EYES_DECL = `override IS_OVER_EYES: bool = false;
 
-const DEFAULT_EPILOGUE = `  var out: FSOut;
-  out.color = vec4f(final_color, alpha);
-  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
 `
 
-const DEFAULT_TEMPLATE: SlotTemplate = { decls: "", epilogue: DEFAULT_EPILOGUE }
-
-// Hair's built-in over-eyes effect (see hair.ts): the engine compiles two pipeline
-// variants from the same module — normal opaque hair, and a stencil-matched re-draw
-// at 25% alpha so eyes read through the silhouette. Always on for the hair slot.
-const HAIR_TEMPLATE: SlotTemplate = {
-  decls: `override IS_OVER_EYES: bool = false;
-
-`,
-  epilogue: `  var outAlpha = alpha;
-  if (IS_OVER_EYES) { outAlpha = alpha * 0.25; }
-
-  var out: FSOut;
-  out.color = vec4f(final_color, outAlpha);
-  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
-`,
-}
-
-// Stockings' built-in alpha behavior (see stockings.ts): Wyman & McGuire hashed
-// alpha testing on bind-pose restPos replaces the standard threshold discard —
-// sort-independent through self-overlap, dither pinned to the fabric. The graph
-// only computes final_color; the hash gate and the alpha=1 output are slot-owned.
-const STOCKINGS_TEMPLATE: SlotTemplate = {
-  decls: `fn _hash3d_wm(a: vec3f) -> f32 {
+const HASHED_ALPHA_DECLS = `fn _hash3d_wm(a: vec3f) -> f32 {
   return _hash33(a).x * 0.5 + 0.5;
 }
 fn hashed_alpha_threshold(co: vec3f) -> f32 {
@@ -71,89 +43,48 @@ fn hashed_alpha_threshold(co: vec3f) -> f32 {
   return clamp(threshold, 1e-6, 1.0);
 }
 
-`,
-  prelude: `@fragment fn fs(input: VertexOutput) -> FSOut {
-  let tex_s = textureSample(diffuseTexture, diffuseSampler, input.uv);
-  // Hashed alpha test (EEVEE "Hashed" blend) instead of the standard threshold.
-  let alpha = material.alpha * tex_s.a;
-  if (alpha < hashed_alpha_threshold(input.restPos)) { discard; }
-
-  let n = safe_normal(input.normal);
-  let v = normalize(camera.viewPos - input.worldPos);
-  let l = -light.lights[0].direction.xyz;
-  let sun = light.lights[0].color.xyz * light.lights[0].color.w;
-  let amb = light.ambientColor.xyz;
-  let shadow = sampleShadow(input.worldPos, n);
-  let tex_color = tex_s.rgb;
-
-`,
-  epilogue: `  var out: FSOut;
-  out.color = vec4f(final_color, 1.0);
-  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
-`,
-}
-
-// Eye's built-in rear-view gate (see eye.ts): open-shell PMX heads don't occlude
-// the eye from behind, so it would draw (and stamp the see-through stencil) through
-// the back of the head. Gate by camera-vs-face hemisphere via the 頭 bone's skinning
-// matrix. Discarding here drops color, depth, and the stencil stamp together. The
-// stencil-stamp pipeline state + front-face cull are slot-owned in createSlotPipeline;
-// the graph only computes the eye's shading (Principled + emission).
-const EYE_TEMPLATE: SlotTemplate = {
-  decls: "",
-  prelude: `@fragment fn fs(input: VertexOutput) -> FSOut {
-  let tex_s = textureSample(diffuseTexture, diffuseSampler, input.uv);
-  let alpha = material.alpha * tex_s.a;
-  if (alpha < 0.001) { discard; }
-
-  let n = safe_normal(input.normal);
-  let v = normalize(camera.viewPos - input.worldPos);
+`
 
+// Eye's built-in rear-view gate (open-shell PMX heads don't occlude the eye from behind,
+// so gate by camera-vs-face hemisphere via the 頭 bone; discard drops color + depth +
+// the stencil stamp together). Injected between the view vectors and the lighting setup.
+const EYE_REAR_GATE = `
   if (material.headBoneIndex >= 0.0) {
     let hm = skinMats[u32(material.headBoneIndex)];
     let faceDir = -normalize(hm[2].xyz);
     if (dot(faceDir, v) < -0.15) { discard; }
   }
+`
 
-  let l = -light.lights[0].direction.xyz;
-  let sun = light.lights[0].color.xyz * light.lights[0].color.w;
-  let amb = light.ambientColor.xyz;
-  let shadow = sampleShadow(input.worldPos, n);
-  let tex_color = tex_s.rgb;
-
-`,
-  epilogue: DEFAULT_EPILOGUE,
-}
-
-export const SLOT_TEMPLATES: Partial<Record<MaterialPreset, SlotTemplate>> = {
-  hair: HAIR_TEMPLATE,
-  stockings: STOCKINGS_TEMPLATE,
-  eye: EYE_TEMPLATE,
-}
-
-export function slotTemplate(slot: MaterialPreset): SlotTemplate {
-  return SLOT_TEMPLATES[slot] ?? DEFAULT_TEMPLATE
-}
-
-// Adjust-tier uniforms — fixed 16-vec4f block (256 B) so the single shared material
-// bind group layout serves every graph; non-graph presets bind a zero buffer.
+// ── Adjust-tier uniforms — fixed 16-vec4f block (256 B) shared by the single material
+// bind group layout; non-graph draws bind a zero buffer. ──
 export const STYLE_UNIFORMS_WGSL = `struct StyleUniforms { p: array<vec4f, 16> };
 @group(2) @binding(4) var<uniform> style: StyleUniforms;
 
 `
 
-// fs() prelude — identical to the hand-written materials so template locals keep the
-// exact names the registry's context nodes and emit functions reference.
-const FS_PRELUDE = `@fragment fn fs(input: VertexOutput) -> FSOut {
+function decls(renderClass: RenderClass, alphaMode: AlphaMode): string {
+  return (alphaMode === "hashed" ? HASHED_ALPHA_DECLS : "") + (renderClass === "hair" ? HAIR_OVER_EYES_DECL : "")
+}
+
+// fs() header up to and including the graph body's context locals. Composed so the
+// hand-written material shaders' local names (tex_color, n, v, l, sun, amb, shadow) are
+// preserved exactly — the registry's context nodes and emit functions reference them.
+function prelude(renderClass: RenderClass, alphaMode: AlphaMode): string {
+  const discard =
+    alphaMode === "hashed"
+      ? "  if (alpha < hashed_alpha_threshold(input.restPos)) { discard; }"
+      : "  if (alpha < 0.001) { discard; }"
+  const gate = renderClass === "eye" ? EYE_REAR_GATE : ""
+  return `@fragment fn fs(input: VertexOutput) -> FSOut {
   let tex_s = textureSample(diffuseTexture, diffuseSampler, input.uv);
-  // MMD alpha semantics: material alpha × texture alpha (hair/lace textures cut
-  // their shapes in the alpha channel).
+  // MMD alpha semantics: material alpha × texture alpha.
   let alpha = material.alpha * tex_s.a;
-  if (alpha < 0.001) { discard; }
+${discard}
 
   let n = safe_normal(input.normal);
   let v = normalize(camera.viewPos - input.worldPos);
+${gate}
   let l = -light.lights[0].direction.xyz;
   let sun = light.lights[0].color.xyz * light.lights[0].color.w;
   let amb = light.ambientColor.xyz;
@@ -161,18 +92,50 @@ const FS_PRELUDE = `@fragment fn fs(input: VertexOutput) -> FSOut {
   let tex_color = tex_s.rgb;
 
 `
+}
+
+// Tail of fs(): consumes `final_color` + locals, writes FSOut. hashed forces output
+// alpha to 1 (the discard already did the cutout); hair scales alpha for the over-eyes
+// pass when IS_OVER_EYES is compiled true.
+function epilogue(renderClass: RenderClass, alphaMode: AlphaMode): string {
+  const alphaBase = alphaMode === "hashed" ? "1.0" : "alpha"
+  if (renderClass === "hair") {
+    return `  var outAlpha = ${alphaBase};
+  if (IS_OVER_EYES) { outAlpha = ${alphaBase} * 0.25; }
+
+  var out: FSOut;
+  out.color = vec4f(final_color, outAlpha);
+  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
+  return out;
+`
+  }
+  return `  var out: FSOut;
+  out.color = vec4f(final_color, ${alphaBase});
+  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
+  return out;
+`
+}
 
-export function assembleModule(slot: MaterialPreset, fsBody: string, includeStyleUniforms: boolean): string {
-  const tmpl = slotTemplate(slot)
+/**
+ * Assemble a full WGSL module: shared node library + bindings/skinning prelude, optional
+ * StyleUniforms, render-class/alpha-mode declarations, the composed fs() shell, and the
+ * graph's node body.
+ */
+export function assembleModule(
+  renderClass: RenderClass,
+  alphaMode: AlphaMode,
+  fsBody: string,
+  includeStyleUniforms: boolean,
+): string {
   return (
     NODES_WGSL +
     COMMON_MATERIAL_PRELUDE_WGSL +
     (includeStyleUniforms ? STYLE_UNIFORMS_WGSL : "") +
-    tmpl.decls +
-    (tmpl.prelude ?? FS_PRELUDE) +
+    decls(renderClass, alphaMode) +
+    prelude(renderClass, alphaMode) +
     fsBody +
     "\n" +
-    tmpl.epilogue +
+    epilogue(renderClass, alphaMode) +
     "}\n"
   )
 }

package/src/graph/style-group.ts

@@ -0,0 +1,39 @@
+// Style groups — the user-facing unit of material styling. A group binds a set of
+// materials to a node graph (pure shading) plus the engine-owned pass-integration axes
+// (renderClass + alphaMode). Each material belongs to at most one group; grouped
+// materials render via the group's compiled-graph pipeline, ungrouped ones fall back to
+// the hand-written preset path. See docs/style-groups-spec.md.
+
+import type { Diagnostic, StyleGraph } from "./schema"
+import type { AlphaMode, RenderClass } from "./render-class"
+import type { StyleSlot } from "./compile"
+
+export type StyleGroup = {
+  /** Stable, unique within a model; /^[a-z0-9_-]+$/. The engine keys installs by this. */
+  id: string
+  /** Human display name ("Skirt", "Visor"); host-owned, round-tripped, never interpreted
+   *  by the engine. Defaults to `id`. */
+  label?: string
+  /** Material names in this group; each material is in AT MOST one group. */
+  materials: string[]
+  /** Pure shading (StyleGraph has no `slot` — integration lives here on the group). */
+  graph: StyleGraph
+  /** Pass-integration class: stencil/cull/draw-order. Default "auto". */
+  renderClass?: RenderClass
+  /** Alpha-handling axis, orthogonal to renderClass. Default "opaque". */
+  alphaMode?: AlphaMode
+}
+
+export type GroupDiagnostic = { groupId: string; diagnostics: Diagnostic[]; ok: boolean }
+
+export type ApplyStyleGroupsResult = {
+  /** Every group compiled + swapped. */
+  ok: boolean
+  groups: GroupDiagnostic[]
+  /** Names in a group that no model material matches (warning). */
+  unknownMaterials: string[]
+  /** Materials claimed by >1 group; the last group in array order wins (logged). */
+  conflicts: string[]
+}
+
+export type ApplyStyleGroupResult = { ok: boolean; diagnostics: Diagnostic[]; slotMap: StyleSlot[] }

package/src/index.ts

@@ -10,7 +10,6 @@ export {
   type MaterialPreset,
   type ResolvedMaterialPreset,
   type MaterialPresetMap,
-  type ApplyStyleResult,
   type GizmoDragEvent,
   type GizmoDragCallback,
   type GizmoDragKind,
@@ -33,6 +32,13 @@ export type {
   Diagnostic,
 } from "./graph/schema"
 export { NODE_REGISTRY, type NodeSpec, type SockT } from "./graph/registry"
+export { RENDER_CLASSES, type RenderClass, type AlphaMode, type RenderClassInfo } from "./graph/render-class"
+export type {
+  StyleGroup,
+  GroupDiagnostic,
+  ApplyStyleGroupsResult,
+  ApplyStyleGroupResult,
+} from "./graph/style-group"
 export { HAIR_GRAPH } from "./graph/presets/hair"
 export { DEFAULT_GRAPH } from "./graph/presets/default"
 export { CLOTH_SMOOTH_GRAPH } from "./graph/presets/cloth_smooth"