reze-engine 0.56.13 → 0.57.0

package/dist/shaders/materials/nodes.js

@@ -650,6 +650,28 @@ fn bump(strength: f32, height: f32, normal: vec3f, world_pos: vec3f) -> vec3f {
 }
 
 // LH engine + WebGPU fragment Y: flip dhdy contribution so height peaks read as outward bumps vs Blender reference
+// The same bump measured against the WORLD instead of the screen.
+//
+// bump_lh below takes dpdx(height) — the change across one PIXEL — and drops
+// the world size of that pixel on the floor when it normalizes the cross
+// products. Its slope is therefore per pixel, so the same surface ripples at a
+// distance, where a pixel spans metres, and goes glass-flat underfoot, where it
+// spans millimetres. For skin and cloth that reads as detail which holds its
+// size on screen, which is why it stays; for water it is the difference between
+// a pool and a mirror, because water is the thing you stand next to.
+//
+// Dividing each derivative by its own footprint gives the true world gradient:
+// view-independent, and strength becomes a real slope — 0.25 means a quarter
+// rise over a run, whatever the camera does.
+fn bump_world(strength: f32, height: f32, normal: vec3f, world_pos: vec3f) -> vec3f {
+  let dpdx_pos = dpdx(world_pos);
+  let dpdy_pos = dpdy(world_pos);
+  let dhdx = dpdx(height) / max(length(dpdx_pos), 1e-8);
+  let dhdy = dpdy(height) / max(length(dpdy_pos), 1e-8);
+  let perturbed = normalize(normal) - strength * (dhdx * normalize(cross(dpdy_pos, normal)) - dhdy * normalize(cross(normal, dpdx_pos)));
+  return normalize(perturbed);
+}
+
 fn bump_lh(strength: f32, height: f32, normal: vec3f, world_pos: vec3f) -> vec3f {
   let dhdx = dpdx(height);
   let dhdy = dpdy(height);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.56.13",
+  "version": "0.57.0",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -308,6 +308,8 @@ type GroupInstall = {
   /** The group's own image maps, uploaded once per apply and owned here — the
    *  install destroys them when it is replaced, so a re-apply cannot leak. */
   images?: (GPUTexture | null)[]
+  /** Per-material overrides of the above; same ownership. */
+  imagesByMaterial?: Record<string, (GPUTexture | null)[]>
   slotMap: StyleSlot[]
   /** Serialized (graph + renderClass + alphaMode) — lets applyStyleGroups skip recompiling
    *  an unchanged group. */
@@ -679,6 +681,14 @@ interface DrawCall {
   // Style group this material belongs to, or null (ungrouped → neutral base pipeline).
   // Outline/ground draw calls are never grouped and leave this null.
   groupId: string | null
+  /** The install this draw call's bind group was actually built from.
+   *
+   *  The id is not enough to decide a rebind: re-applying the SAME group id
+   *  after an edit compiles a NEW install — its own uniform buffer, its own
+   *  uploaded images — and destroys the old one. Comparing ids alone left the
+   *  draw call bound to what was just thrown away, which is why a stage looked
+   *  wrong on upload (two applies) and right after a refresh (one). */
+  boundInstall?: object | null
   // Bindings 0–3 kept so the bind group can be rebuilt when the material's group changes
   // (binding 4 must follow the group's style buffer, or the zero buffer when ungrouped).
   // Present only for material draw calls (opaque/transparent) — the grouping walk skips
@@ -2315,7 +2325,6 @@ export class Engine {
    */
   private worldEquirectTexture: GPUTexture | null = null
   private worldEquirectView: GPUTextureView | null = null
-  private worldStrength = 1
   /** A three-colour sky's irradiance SH, when the world is a gradient rather
    *  than a picture. An HDRI outranks it — see writeWorld. */
   private worldGradientSH: Float32Array | null = null
@@ -2740,13 +2749,15 @@ export class Engine {
     // exposure and view transform as the scene — a sun rolls off like a sun).
     // The camera basis at u[12..23] is refreshed per frame.
     // In modes 2 and 3 the colour slot is dead, so mode 3 carries the world
-    // STRENGTH in u[8] — Blender's world-strength dial, default 1.
+    // STRENGTH in u[8] — Blender's world-strength dial, the SAME number that
+    // scales the irradiance. A sky you can see at full brightness while it
+    // lights at two thirds is two skies.
     const bg = this.backgroundColor
     // THE BACKDROP WINS WHAT YOU SEE; the world lights regardless. With only a
     // world installed it is also the sky, which is what an HDRI alone has
     // always done.
     const showingWorld = this.backdropEquirectView === null && this.worldEquirectView !== null
-    u[8] = showingWorld ? this.worldStrength : (bg?.x ?? 0)
+    u[8] = showingWorld ? this.world.strength : (bg?.x ?? 0)
     u[9] = bg?.y ?? 0
     u[10] = bg?.z ?? 0
     // Base-layer mode only. A user effect is a separate LAYER over whichever
@@ -4113,7 +4124,7 @@ export class Engine {
    * `strength` is Blender's world-strength dial and is folded into the
    * coefficients, so what lights her is what you see.
    */
-  setWorldEquirect(source: HdrImage | null, options?: { strength?: number }): void {
+  setWorldEquirect(source: HdrImage | null): void {
     // RETIRED, NOT DESTROYED. A frame already encoded against the old sky can
     // still be in flight — the bind groups that name it are rebuilt below, but
     // the command buffer holding the previous ones is submitted at the end of
@@ -4123,7 +4134,6 @@ export class Engine {
     if (this.worldEquirectTexture) this.retiredSkies.push(this.worldEquirectTexture)
     this.worldEquirectTexture = null
     this.worldEquirectView = null
-    this.worldStrength = Math.max(options?.strength ?? 1, 0)
     const hadSH = this.worldSH !== null
     this.worldSH = null
     if (source && this.device) {
@@ -4183,10 +4193,13 @@ export class Engine {
       // The sky lights the scene, not only backs it. The sun keeps the toon
       // ramp — this is the ambient term, exactly where the flat world colour
       // used to sit.
+      // RAW irradiance. The World strength dial is applied where every other
+      // reading of it is, in writeWorld — folding it in here made the sky's
+      // brightness a function of WHEN it was installed: the dial moved
+      // afterwards rescaled the write and not the projection, and an install
+      // that landed mid-session carried a different strength from the same
+      // document reopened.
       this.worldSH = projectIrradianceSH({ ...source, data: source.data }, 4)
-      if (this.worldStrength !== 1) {
-        for (let i = 0; i < this.worldSH.length; i++) this.worldSH[i] *= this.worldStrength
-      }
     }
     if (this.worldSH || hadSH) this.writeWorld()
     // The MATERIAL groups too, not only the composite's: a surface that
@@ -9956,6 +9969,7 @@ export class Engine {
     const texturePath = `plane/${name}`
     const material: Material = {
       name,
+      memo: "",
       diffuse: [1, 1, 1, 1],
       specular: [0, 0, 0],
       ambient: [0, 0, 0],
@@ -10172,6 +10186,56 @@ export class Engine {
     return this.modelInstances.get(name)?.model ?? null
   }
 
+  /**
+   * What the engine is actually about to draw, per model.
+   *
+   * Every model the engine holds, not every model the host thinks it holds —
+   * which is the point. A scene that comes up brighter after an upload than the
+   * same document does after a reload differs somewhere between the two, and
+   * the candidates are all countable: a model left behind by a replace draws its
+   * transparent surfaces a second time, and a group that compiled but claimed
+   * nothing leaves its materials on the default graph. Both are invisible from
+   * the host, which sees its own lists rather than the engine's.
+   *
+   * `grouped` counts draw calls bound to a style group; `ungrouped` is the rest,
+   * on the default graph.
+   */
+  /**
+   * What the composite is about to put behind the scene, and at what level.
+   *
+   * `mode` is the base layer: 0 transparent, 1 a flat colour, 2 an LDR 360
+   * picture, 3 the HDR world as scene-linear radiance. `level` is what mode 3
+   * is multiplied by. The whole frame's brightness turns on these two, and
+   * neither is visible from a host reading its own document — a scene that came
+   * up brighter after an upload than after a reload of the same document is one
+   * of the cases they answer.
+   */
+  getBackgroundState(): { mode: 0 | 1 | 2 | 3; level: number; backdrop: boolean; world: boolean } {
+    const showingWorld = this.backdropEquirectView === null && this.worldEquirectView !== null
+    return {
+      mode: this.backdropEquirectView ? 2 : showingWorld ? 3 : this.backgroundColor ? 1 : 0,
+      level: this.world.strength,
+      backdrop: this.backdropEquirectView !== null,
+      world: this.worldEquirectView !== null,
+    }
+  }
+
+  getDrawStats(): { model: string; materials: number; opaque: number; transparent: number; grouped: number; ungrouped: number }[] {
+    const out = []
+    for (const [name, inst] of this.modelInstances) {
+      const shaded = inst.drawCalls.filter((d) => d.baseBindGroupEntries)
+      out.push({
+        model: name,
+        materials: shaded.length,
+        opaque: shaded.filter((d) => d.type === "opaque").length,
+        transparent: shaded.filter((d) => d.type === "transparent").length,
+        grouped: shaded.filter((d) => d.groupId !== null).length,
+        ungrouped: shaded.filter((d) => d.groupId === null).length,
+      })
+    }
+    return out
+  }
+
   /**
    * Hang a model from a bone of another — MMD's 外部親 (outside parent).
    *
@@ -11090,13 +11154,14 @@ export class Engine {
   private destroyInstall(install: GroupInstall): void {
     install.uniformBuffer.destroy()
     for (const tex of install.images ?? []) tex?.destroy()
+    for (const set of Object.values(install.imagesByMaterial ?? {})) for (const tex of set) tex?.destroy()
   }
 
   /** Upload a group's image maps. Sources are decoded images the host already
    *  holds; the engine never fetches, matching how models and motions arrive. */
-  private uploadGroupImages(group: StyleGroup): (GPUTexture | null)[] | undefined {
-    if (!group.images?.length) return undefined
-    return group.images.slice(0, 4).map((entry) => {
+  private uploadGroupImages(group: StyleGroup, slots = group.images): (GPUTexture | null)[] | undefined {
+    if (!slots?.length) return undefined
+    return slots.slice(0, 4).map((entry) => {
       if (!entry) return null
       const wrapped = "source" in entry
       const src = wrapped ? entry.source : entry
@@ -15503,7 +15568,19 @@ export class Engine {
   ): Promise<ApplyStyleGroupResult> {
     const renderClass = group.renderClass ?? "auto"
     const alphaMode = group.alphaMode ?? "opaque"
-    const signature = JSON.stringify({ g: group.graph, rc: renderClass, am: alphaMode, o: opts?.previewNode ?? null })
+    // THE MAPS ARE PART OF THE SIGNATURE, because a matching one skips the
+    // upload below and keeps whatever the install already holds. A group can
+    // arrive twice — once as the model lands and again once its sidecar has
+    // decoded — and without this the second apply refreshed the definition and
+    // silently kept the empty slots from the first.
+    const signature = JSON.stringify({
+      g: group.graph,
+      rc: renderClass,
+      am: alphaMode,
+      o: opts?.previewNode ?? null,
+      im: group.images?.length ?? 0,
+      ibm: Object.keys(group.imagesByMaterial ?? {}).sort(),
+    })
     const existing = inst.styleGroups.get(group.id)
     if (existing && existing.signature === signature) {
       existing.group = group // refresh def (label/materials) without recompiling
@@ -15577,6 +15654,11 @@ export class Engine {
       mirrorPipeline,
       uniformBuffer,
       images: this.uploadGroupImages(group),
+      imagesByMaterial: group.imagesByMaterial
+        ? Object.fromEntries(
+            Object.entries(group.imagesByMaterial).map(([name, slots]) => [name, this.uploadGroupImages(group, slots) ?? []]),
+          )
+        : undefined,
       slotMap: result.slotMap,
       signature,
     })
@@ -15637,15 +15719,27 @@ export class Engine {
       // alpha-blend bucket and is drawn in author order: soft haloed leaves
       // that do not occlude each other, and haze wherever cards overlap. The
       // game it came from alpha-tests exactly these materials.
-      const type = install?.alphaMode === "hashed" ? "opaque" : dc.baseType
+      // A GRAPH THAT COMPUTES OPACITY DRAWS TRANSPARENT. The phase was decided
+      // at load from the texture's alpha over this material's geometry, which
+      // cannot know about a curve the graph invents — water whose alpha runs
+      // from nothing to a mirror samples as solid and would land in the opaque
+      // phase, where the blend that makes it water never happens.
+      const type = install?.group.graph.opacity
+        ? "transparent"
+        : install?.alphaMode === "hashed"
+          ? "opaque"
+          : dc.baseType
       if (dc.type !== type) dc.type = type
-      if (dc.groupId === groupId) continue
+      // Rebind when the INSTALL changed, not merely when the id did.
+      const bound = install ?? null
+      if (dc.groupId === groupId && dc.boundInstall === bound) continue
       dc.groupId = groupId
+      dc.boundInstall = bound
       dc.bindGroup = this.createMaterialBindGroup(
         `material: ${dc.materialName}`,
         dc.baseBindGroupEntries,
         install ? install.uniformBuffer : this.zeroStyleBuffer,
-        install?.images,
+        install?.imagesByMaterial?.[dc.materialName] ?? install?.images,
       )
     }
     this.sortDrawCalls(inst)

package/src/graph/compile.ts

@@ -183,6 +183,13 @@ export function validateGraph(graph: ShaderGraph, opts: CompileOptions = {}): Di
   if (!outT) d.push(err(`output "${out.node}.${out.socket}" doesn't resolve`, out.node))
   else if (outT === "vec4") d.push(err(`output "${out.node}.${out.socket}" must be color or float`, out.node))
 
+  if (graph.opacity) {
+    const opNode = nodes.get(graph.opacity.node)
+    const opT = opNode ? NODE_REGISTRY[opNode.type]?.outputs[graph.opacity.socket] : undefined
+    if (!opT) d.push(err(`opacity "${graph.opacity.node}.${graph.opacity.socket}" doesn't resolve`, graph.opacity.node))
+    else if (opT === "vec4") d.push(err(`opacity "${graph.opacity.node}.${graph.opacity.socket}" must be float or color`, graph.opacity.node))
+  }
+
   return d
 }
 
@@ -216,7 +223,11 @@ export function compileGraph(graph: ShaderGraph, opts: CompileOptions = {}): Com
   // Prune: reverse-DFS from the (possibly preview-overridden) output.
   const out = opts.previewNode ?? graph.output
   const reachable = new Set<string>()
-  const stack = [out.node]
+  // SEEDED FROM BOTH ENDS. Pruning walks back from what is used, and opacity is
+  // used — seeding only the colour output drops every node that exists to feed
+  // the alpha curve, and the graph compiles cleanly with a fresnel nobody
+  // computed. A preview override replaces the colour output, never the opacity.
+  const stack = [out.node, ...(graph.opacity && !opts.previewNode ? [graph.opacity.node] : [])]
   while (stack.length) {
     const id = stack.pop()!
     if (reachable.has(id)) continue
@@ -341,8 +352,10 @@ export function compileGraph(graph: ShaderGraph, opts: CompileOptions = {}): Com
   }
 
   lines.push(`  let final_color = ${outputExpr(out, "color")}; // @node:${out.node}`)
+  const opacity = graph.opacity && !opts.previewNode ? graph.opacity : null
+  if (opacity) lines.push(`  let final_opacity = saturate(${outputExpr(opacity, "float")}); // @node:${opacity.node}`)
 
   const fsBody = lines.join("\n")
-  const wgsl = assembleModule(opts.renderClass ?? "auto", opts.alphaMode ?? "opaque", fsBody, usesStyle.current)
+  const wgsl = assembleModule(opts.renderClass ?? "auto", opts.alphaMode ?? "opaque", fsBody, usesStyle.current, !!opacity)
   return { ok: true, wgsl, fsBody, slotMap, diagnostics, prunedNodes }
 }

package/src/graph/registry.ts

@@ -153,6 +153,18 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
       // Blender Texture Coordinate → Reflection (view ray mirrored on the normal);
       // drives env-tracking patterns like metal's voronoi sparkle.
       reflection: "vector",
+      /**
+       * How much WORLD one pixel covers here, in units.
+       *
+       * What a texture gets free from its mipmap and a procedural pattern has
+       * no way to ask for. Past the point where this exceeds a pattern's
+       * wavelength the pattern is under-sampled, and a bump taken from it is
+       * differencing two uncorrelated samples — random per 2x2 quad, which on a
+       * receding plane stretches along the depth axis and reads as scan lines.
+       * Fade a layer out as this approaches its wavelength and the surface goes
+       * quietly smooth instead, which is what distance should look like.
+       */
+      footprint: "float",
     },
     contextOutputs: {
       normal: "n",
@@ -161,6 +173,7 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
       rest_pos: "input.restPos",
       uv: "vec3f(input.uv, 0.0)",
       reflection: "reflect(-v, n)",
+      footprint: "max(length(dpdx(input.worldPos)), length(dpdy(input.worldPos)))",
     },
   },
   // The scene's key light. Blender NPR presets rarely use a diffuse closure —
@@ -204,6 +217,38 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
   // PMX material's diffuse color (the authored base tint). Multiply the diffuse texture
   // by this for the MMD-correct base — untextured materials carry their color here, so a
   // texture-only base would render them white.
+  // WHAT THE SURFACE IS MADE OF, when whoever wrote the model said so.
+  //
+  // PMX carries a specular colour its own renderer barely uses, and a stage
+  // converted out of a game engine packs its material's (metal, roughness,
+  // occlusion) there — the same triple that game's property map holds, averaged
+  // per material. One shared look can then read it and a whole stage keeps ONE
+  // pipeline, where a look per material was what cost a garden its frame rate.
+  //
+  // A hand-authored PMX leaves it at whatever its exporter wrote, so a graph
+  // that reads this is choosing to trust the model. Nothing else does.
+  // How opaque the PMX said this material is, before its texture's alpha is
+  // multiplied in. A graph that computes its own opacity still wants it: glass
+  // is see-through by the amount its author chose and a mirror at a grazing
+  // angle, and without this every pane in a stage gets the same transparency
+  // whatever its material says.
+  material_alpha: {
+    inputs: {},
+    outputs: { value: "float" },
+    contextOutputs: { value: "material.alpha" },
+  },
+
+  material_specular: {
+    inputs: {},
+    outputs: { color: "color" },
+    contextOutputs: { color: "material.specular" },
+  },
+  material_shininess: {
+    inputs: {},
+    outputs: { value: "float" },
+    contextOutputs: { value: "material.shininess" },
+  },
+
   material_diffuse: {
     inputs: {},
     outputs: { color: "color" },
@@ -629,15 +674,21 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
 
   // ── View-dependent scalars ──
   fresnel: { inputs: { ior: F(1.45) }, outputs: { value: "float" }, emit: (a) => `fresnel(${a.ior}, n, v)` },
+  // The normal is an INPUT with the shading normal as its default, so these read
+  // like every other node when nothing is wired and can be handed a perturbed
+  // normal when something is. Water is why: its ripples live in a bump node, and
+  // a fresnel that quietly read the flat surface normal gave a pool whose
+  // reflection and opacity were both perfectly smooth however the bump was
+  // tuned — the ripples existed and touched nothing anybody could see.
   "layer_weight/fresnel": {
-    inputs: { blend: F(0.5) },
+    inputs: { blend: F(0.5), normal: { type: "vector", contextDefault: "n" } },
     outputs: { value: "float" },
-    emit: (a) => `layer_weight_fresnel(${a.blend}, n, v)`,
+    emit: (a) => `layer_weight_fresnel(${a.blend}, ${a.normal}, v)`,
   },
   "layer_weight/facing": {
-    inputs: { blend: F(0.5) },
+    inputs: { blend: F(0.5), normal: { type: "vector", contextDefault: "n" } },
     outputs: { value: "float" },
-    emit: (a) => `layer_weight_facing(${a.blend}, n, v)`,
+    emit: (a) => `layer_weight_facing(${a.blend}, ${a.normal}, v)`,
   },
 
   /**
@@ -717,6 +768,15 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     outputs: { vector: "vector" },
     emit: (a) => `bump_lh(${a.strength}, ${a.height}, ${a.normal}, input.worldPos)`,
   },
+  // Its strength is a SLOPE, not a screen effect — see bump_world. Use it for
+  // anything whose detail belongs to the surface rather than to the frame:
+  // water, sand, hammered metal. `bump` holds its size on screen, which is what
+  // skin and cloth want and what water cannot use.
+  "bump/world": {
+    inputs: { strength: F(0.1), height: F(0, true), normal: V([0, 0, 0], true) },
+    outputs: { vector: "vector" },
+    emit: (a) => `bump_world(${a.strength}, ${a.height}, ${a.normal}, input.worldPos)`,
+  },
 
   // ── Procedural textures ──
   tex_noise: {

package/src/graph/schema.ts

@@ -41,6 +41,26 @@ export type ShaderGraph = {
   links: GraphLink[]
   /** Must resolve to a color (vec3f) or float (auto-splatted) socket. */
   output: { node: string; socket: string }
+  /**
+   * How opaque the fragment is, when the graph wants to say.
+   *
+   * Absent, alpha is MMD's own: the material's alpha times its texture's, one
+   * number per material. That is right for a dress and wrong for anything whose
+   * transparency depends on where you stand — glass and water are the same
+   * surface at 5% looking straight down and near-mirror at a grazing angle, and
+   * no constant is both. A game's own water shader writes
+   * `(1 - NdotV) * fresnel` per pixel; this is the socket that lets a graph do
+   * the same.
+   *
+   * It REPLACES the constant rather than scaling it, because a graph that
+   * bothers to compute opacity is claiming the whole answer. A graph that still
+   * wants the texture's holes multiplies in `texture.alpha` itself.
+   *
+   * A material wearing a group whose graph declares this always draws in the
+   * transparent phase: the phase is otherwise decided at load from the texture's
+   * alpha, which knows nothing about a curve the graph invents.
+   */
+  opacity?: { 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

package/src/graph/slots.ts

@@ -143,8 +143,11 @@ ${gate}
 // 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"
+function epilogue(renderClass: RenderClass, alphaMode: AlphaMode, hasOpacity: boolean): string {
+  // A graph that computes its own opacity wins, including over hashed: hashed
+  // writes 1 because its discard already decided the cutout, and a graph asking
+  // for a curve is asking for the opposite of a cutout.
+  const alphaBase = hasOpacity ? "final_opacity" : alphaMode === "hashed" ? "1.0" : "alpha"
   // Empty while ids are off, so the epilogue is exactly what it was. The values
   // ride in the per-draw material uniform (see MaterialUniforms), which is what
   // keeps this working through the indirect-draw path.
@@ -198,6 +201,7 @@ export function assembleModule(
   alphaMode: AlphaMode,
   fsBody: string,
   includeStyleUniforms: boolean,
+  hasOpacity = false,
 ): string {
   return (
     NODES_WGSL +
@@ -211,7 +215,7 @@ export function assembleModule(
     prelude(renderClass, alphaMode) +
     fsBody +
     "\n" +
-    epilogue(renderClass, alphaMode) +
+    epilogue(renderClass, alphaMode, hasOpacity) +
     "}\n"
   )
 }

package/src/graph/style-group.ts

@@ -36,6 +36,20 @@ export type StyleGroup = {
    * no-op rather than a failure.
    */
   images?: (GroupImage | GroupImageSource | null)[]
+  /**
+   * The same slots, but PER MATERIAL — for a group whose members each bring
+   * their own maps.
+   *
+   * `images` belongs to the LOOK and is right when a look carries its own ramp
+   * or detail map. A converted stage is the other case: twenty-seven props, one
+   * shading model, and a different normal map on every one of them. Keyed here,
+   * they share a pipeline and differ only in what the bind group points at —
+   * the alternative is a group per material, which is a pipeline per material,
+   * which is what cost a garden stage its frame rate.
+   *
+   * A material with no entry falls back to `images`, and then to 1×1 white.
+   */
+  imagesByMaterial?: Record<string, (GroupImage | GroupImageSource | null)[]>
 }
 
 export type GroupImageSource = ImageBitmap | HTMLImageElement | HTMLCanvasElement

package/src/model.ts

@@ -116,6 +116,17 @@ export interface Material {
   edgeColor: [number, number, number, number]
   edgeSize: number
   vertexCount: number
+  /**
+   * The PMX material's free-text memo.
+   *
+   * MMD shows it in the material panel and nothing reads it, which makes it the
+   * one place a converter can say what a material WAS without inventing a
+   * sidecar. A stage ported out of a game engine writes its source shader here
+   * — `SimPipeline/Scene/Ripplet`, `SimPipeline/PBR/Glass` — so a host can give
+   * the pool the water look by what it is rather than by hoping its name
+   * contains "water". Empty on a hand-authored model, which reads as no claim.
+   */
+  memo: string
 }
 
 export interface Bone {

package/src/pmx-loader.ts

@@ -303,7 +303,7 @@ export class PmxLoader {
         const isSharedToonTexture = this.getUint8() === 1
         const toonTextureIndex = isSharedToonTexture ? this.getUint8() : this.getNonVertexIndex(this.textureIndexSize)
 
-        this.getText() // comment (skip)
+        const memo = this.getText()
         const vertexCount = this.getInt32()
 
         // PMX material flag bits:
@@ -311,6 +311,7 @@ export class PmxLoader {
         // Bit 4 (0x10): Edge drawing (outline)
         const mat: Material = {
           name,
+          memo,
           diffuse,
           specular,
           ambient,

package/src/shaders/materials/nodes.ts

@@ -651,6 +651,28 @@ fn bump(strength: f32, height: f32, normal: vec3f, world_pos: vec3f) -> vec3f {
 }
 
 // LH engine + WebGPU fragment Y: flip dhdy contribution so height peaks read as outward bumps vs Blender reference
+// The same bump measured against the WORLD instead of the screen.
+//
+// bump_lh below takes dpdx(height) — the change across one PIXEL — and drops
+// the world size of that pixel on the floor when it normalizes the cross
+// products. Its slope is therefore per pixel, so the same surface ripples at a
+// distance, where a pixel spans metres, and goes glass-flat underfoot, where it
+// spans millimetres. For skin and cloth that reads as detail which holds its
+// size on screen, which is why it stays; for water it is the difference between
+// a pool and a mirror, because water is the thing you stand next to.
+//
+// Dividing each derivative by its own footprint gives the true world gradient:
+// view-independent, and strength becomes a real slope — 0.25 means a quarter
+// rise over a run, whatever the camera does.
+fn bump_world(strength: f32, height: f32, normal: vec3f, world_pos: vec3f) -> vec3f {
+  let dpdx_pos = dpdx(world_pos);
+  let dpdy_pos = dpdy(world_pos);
+  let dhdx = dpdx(height) / max(length(dpdx_pos), 1e-8);
+  let dhdy = dpdy(height) / max(length(dpdy_pos), 1e-8);
+  let perturbed = normalize(normal) - strength * (dhdx * normalize(cross(dpdy_pos, normal)) - dhdy * normalize(cross(normal, dpdx_pos)));
+  return normalize(perturbed);
+}
+
 fn bump_lh(strength: f32, height: f32, normal: vec3f, world_pos: vec3f) -> vec3f {
   let dhdx = dpdx(height);
   let dhdy = dpdy(height);