reze-engine 0.41.0 → 0.41.2

package/dist/shaders/passes/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;+BAwB+B;AAC/B,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;CACvB,CAAA;AAoTD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAclF;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;+BAwB+B;AAC/B,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;CACvB,CAAA;AA4XD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAclF;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}

package/dist/shaders/passes/composite.js

@@ -23,7 +23,7 @@ override APPLY_GAMMA: bool = true;
 @group(0) @binding(0) var hdrTex: texture_2d<f32>;
 @group(0) @binding(1) var bloomTex: texture_2d<f32>;   // bloomUpTexture mip 0 (full pyramid top)
 @group(0) @binding(2) var bloomSamp: sampler;
-@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 11>;
+@group(0) @binding(3) var<uniform> viewU: array<vec4<f32>, 15>;
 // Aux mask/alpha texture. .r = bloom mask (unused here; bloom blit uses it).
 // .g = accumulated canvas alpha (what hdr.a carried before the HDR format
 // became rg11b10ufloat). We unpremultiply HDR by this alpha for tonemap, then
@@ -47,7 +47,7 @@ override APPLY_GAMMA: bool = true;
 //            the compiled variant IS the flag.
 // viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
 // viewU[5] = (camera forward, _) — refreshed per frame while skybox/effect active.
-// viewU[6] = (time seconds, _, canvas width, canvas height).
+// viewU[6] = (time seconds, view transform id, canvas width, canvas height).
 // viewU[7] = (grade offset.rgb, contrast);  viewU[8] = (grade power.rgb, saturation);
 // viewU[9] = (grade slope.rgb, grade on/off) — see grade() below.
 // viewU[10] = (camera world position, _) — refreshed with the basis above.
@@ -67,6 +67,9 @@ override APPLY_GAMMA: bool = true;
 //           track the camera radius. Cleared depth (1.0) inverts to the far
 //           plane, so empty sky reads as maximally defocused background.
 @group(0) @binding(9) var<uniform> dofU: array<vec4<f32>, 3>;
+// Blender's AgX, as the 57³ lookup it ships as rather than a reconstruction of
+// it. Sampled in the log-encoded E-Gamut space the cube expects — see agxTransform.
+@group(0) @binding(10) var agxLut: texture_3d<f32>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
@@ -110,12 +113,82 @@ fn filmic(x: f32) -> f32 {
   return textureSampleLevel(filmicLut, bloomSamp, vec2f(u, 0.5), 0.0).r;
 }
 
+/** The sRGB display encoding — Blender's "Standard" view transform, which is what
+ *  NPR work uses: no film curve at all, so the colours a graph computes are the
+ *  colours that land. Not a 2.2 power law; sRGB has a linear toe. */
+fn srgb_encode(x: f32) -> f32 {
+  let c = max(x, 0.0);
+  return select(1.055 * pow(c, 1.0 / 2.4) - 0.055, c * 12.92, c <= 0.0031308);
+}
+
+/**
+ * AgX, the chain config.ocio states for "AgX Base Rec.1886" on an sRGB display:
+ *
+ *   scene-linear Rec.709 → 3x3 into FilmLight E-Gamut
+ *   → log2 across 25 stops, [-12.47393, +12.5261] → 0..1
+ *   → the 57³ cube
+ *   → Rec.1886 (pure γ2.4) decoded, then re-encoded as sRGB for the swapchain
+ *
+ * The last step is not pedantry: Rec.1886 is a pure power law and sRGB has a
+ * linear toe, so skipping it lifts the darkest few code values.
+ *
+ * Blender interpolates the cube tetrahedrally and a GPU sampler is trilinear.
+ * The difference is small and confined to saturated gradients; if it ever shows,
+ * tetrahedral is a dozen lines here.
+ */
+fn agxTransform(c: vec3f) -> vec3f {
+  let m = mat3x3<f32>(
+    vec3f(0.55937113, 0.07622071, 0.06552670),
+    vec3f(0.30478326, 0.78797183, 0.16454675),
+    vec3f(0.13584556, 0.13580748, 0.76992653),
+  );
+  let e = m * max(c, vec3f(0.0));
+  // The cube's domain: an unlit pixel would take log2 to -inf, so floor it at
+  // the bottom stop rather than sampling outside the LUT.
+  let t = clamp((log2(max(e, vec3f(1e-10))) + vec3f(12.47393)) / 25.0, vec3f(0.0), vec3f(1.0));
+  // Half-texel inset, so the end stops are the cube's own values and not a blend
+  // with the clamp-to-edge border.
+  let n = 57.0;
+  let uvw = t * ((n - 1.0) / n) + (0.5 / n);
+  let formed = textureSampleLevel(agxLut, bloomSamp, uvw, 0.0).rgb;
+  let linear = pow(max(formed, vec3f(0.0)), vec3f(2.4));
+  return vec3f(srgb_encode(linear.r), srgb_encode(linear.g), srgb_encode(linear.b));
+}
+
+/** Which display transform, chosen per frame at viewU[6].y (0 filmic, 1 standard, 2 agx).
+ *  A uniform branch rather than a pipeline variant: switching is rare, and both
+ *  arms are cheap enough that specialising the pipeline would buy nothing. */
+fn viewTransform(c: vec3f) -> vec3f {
+  let mode = viewU[6].y;
+  if (mode > 1.5) { return agxTransform(c); }
+  if (mode > 0.5) { return vec3f(srgb_encode(c.r), srgb_encode(c.g), srgb_encode(c.b)); }
+  return vec3f(filmic(c.r), filmic(c.g), filmic(c.b));
+}
+
 /** Canvas size in pixels — for user effects (aspect correction). */
 fn bgResolution() -> vec2f { return viewU[6].zw; }
 
 /** The camera's world position. */
 fn bgCameraPos() -> vec3f { return viewU[10].xyz; }
 
+/** How many characters are in the scene, up to four. */
+fn bgSubjectCount() -> i32 { return i32(viewU[10].w); }
+
+/**
+ * Where a character is standing, in world space.
+ *
+ * An effect that wants to RESPOND to the cast — ripples under the feet, a glow
+ * that follows someone, dust kicked up where they are — needs to know where
+ * they are, and the ray and the depth cannot tell it: they describe the pixel,
+ * not the scene. This is the model's root, which for a PMX is between the feet
+ * on the floor, so it is already the contact point a ripple wants.
+ *
+ * Clamped rather than bounds-checked: an effect looping past the count reads the
+ * last subject instead of sampling whatever follows the array, which is a wrong
+ * ripple rather than an undefined one.
+ */
+fn bgSubjectPos(i: i32) -> vec3f { return viewU[11 + clamp(i, 0, 3)].xyz; }
+
 /** Where in the WORLD the scene drew this pixel — the depth handed to
  *  foreground() turned into a place. Without it an effect can only think in
  *  distances from the lens, which is no use to anything that belongs somewhere:
@@ -222,8 +295,7 @@ const COMPOSITE_BODY = /* wgsl */ `
   let sceneStraight = scenePm.rgb / max(sceneAlpha, 1e-6);
 
   let exposed = sceneStraight * exp2(viewU[0].x);
-  let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));
-  var disp = max(tm, vec3f(0.0));
+  var disp = max(viewTransform(exposed), vec3f(0.0));
   // Grade the SCENE only, before the display gamma. Deliberately not applied to
   // the background: it keeps a picked background color exactly as picked, and —
   // load-bearing — leaves green-screen mode's key color unshifted so chroma

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.41.0",
+  "version": "0.41.2",
   "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

@@ -31,6 +31,7 @@ import {
   BLOOM_DOWNSAMPLE_SHADER_WGSL,
   BLOOM_UPSAMPLE_SHADER_WGSL,
 } from "./shaders/passes/bloom"
+import { AGX_LUT_GZ, AGX_LUT_SIZE } from "./shaders/agx-lut"
 import { buildCompositeShader } from "./shaders/passes/composite"
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick"
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap"
@@ -84,7 +85,17 @@ const PRESET_NAME_HINTS: Array<[MaterialPreset, string[]]> = [
     "face",
     ["顔", "颜", "顏", "脸", "臉", "かお", "face", "舌", "tongue", "牙", "牙齿", "齿", "歯", "teeth", "tooth", "口腔", "口内", "mouth", "嘴", "唇", "歯茎", "gums"],
   ],
-  ["hair", ["前髪", "後髪", "髪", "髮", "头发", "頭髪", "もみあげ", "アホ毛", "ヘア", "hair", "ahoge", "bang"]],
+  // Simplified 发 is listed as compounds, never bare: it also writes 发光 (glow),
+  // and hair carries a renderClass, so a chance hit puts an emissive panel in the
+  // hair pass. Same reasoning as bare 口 being omitted from face above.
+  [
+    "hair",
+    [
+      "前髪", "後髪", "髪", "髮", "頭髪", "もみあげ", "アホ毛", "ヘア",
+      "头发", "前发", "后发", "长发", "短发", "发丝", "刘海", "辫", "马尾",
+      "hair", "ahoge", "bang",
+    ],
+  ],
   ["body", ["肌", "皮肤", "skin"]],
   ["metal", ["金属", "メタル", "metal", "earring", "耳环", "耳環"]],
   [
@@ -187,6 +198,9 @@ type GroupInstall = {
   /** hair render-class only: the stencil-matched IS_OVER_EYES=true variant. */
   overEyesPipeline?: GPURenderPipeline
   uniformBuffer: GPUBuffer
+  /** 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)[]
   slotMap: StyleSlot[]
   /** Serialized (graph + renderClass + alphaMode) — lets applyStyleGroups skip recompiling
    *  an unchanged group. */
@@ -218,6 +232,14 @@ export type WorldOptions = {
 
 /** A model's scene placement — root offset baked into skinning + visibility. Serializable
  *  into a scene descriptor via getModelTransform. */
+/** How many character positions an effect can read (viewU[11..14]). */
+const MAX_EFFECT_SUBJECTS = 4
+/** Where a character IS, for an effect that follows them. センター carries a
+ *  motion's root movement — walking, jumping — where the model transform only
+ *  carries where the model was placed; 全ての親 is the fallback for a model that
+ *  animates the true root instead. */
+const SUBJECT_BONES = ["センター", "全ての親"]
+
 export type ModelTransform = {
   position: Vec3
   rotation: Quat
@@ -320,7 +342,17 @@ export type ViewTransformOptions = {
   exposure: number
   /** After Filmic, display gamma (`pow(rgb, 1/gamma)`). */
   gamma: number
-  look: "default" | "medium_high_contrast"
+  /**
+   * Which display transform the frame is formed with.
+   *
+   * "standard" is Blender's Standard: the sRGB encoding and nothing else, which
+   * is what NPR and anime work uses — the colours the graph computes are the
+   * colours that land, with no film curve reinterpreting them. Both of the
+   * reference Wuthering Waves projects render this way.
+   *
+   * "filmic" is Blender 3.6's Filmic, Medium High Contrast, baked as a LUT.
+   */
+  transform: "agx" | "filmic" | "standard"
 }
 
 // Matches the reference Blender project: Filmic view, Medium High Contrast look,
@@ -328,7 +360,7 @@ export type ViewTransformOptions = {
 export const DEFAULT_VIEW_TRANSFORM: ViewTransformOptions = {
   exposure: 0.6,
   gamma: 1.0,
-  look: "medium_high_contrast",
+  transform: "filmic",
 }
 
 /** Color grading applied to the tonemapped scene (ASC CDL — see grade() in
@@ -778,7 +810,7 @@ export class Engine {
   // 11 × vec4f — see the viewU comment in composite.ts. The last one is the
   // camera's world position, which is what lets a foreground effect turn the
   // depth it is handed into a PLACE (bgWorldPos) rather than a distance.
-  private readonly compositeUniformData = new Float32Array(44)
+  private readonly compositeUniformData = new Float32Array(60)
   /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
   private backgroundColor: Vec3 | null = null
   // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
@@ -802,6 +834,8 @@ export class Engine {
      *  STORE its depth, which it otherwise discards into tile memory. */
     hasForeground: boolean
   } | null = null
+  private agxLutTexture: GPUTexture | null = null
+  private agxFallbackTexture!: GPUTexture
   /** Bound at composite binding 7 when no effect (or a param-less one) is set. */
   private bgParamsDummyBuffer!: GPUBuffer
   private compositePipelineLayout!: GPUPipelineLayout
@@ -981,7 +1015,7 @@ export class Engine {
     return {
       exposure: partial?.exposure ?? d.exposure,
       gamma: partial?.gamma ?? d.gamma,
-      look: partial?.look ?? d.look,
+      transform: partial?.transform ?? d.transform,
     }
   }
 
@@ -1001,7 +1035,7 @@ export class Engine {
 
   getViewTransformOptions(): ViewTransformOptions {
     const v = this.viewTransform
-    return { exposure: v.exposure, gamma: v.gamma, look: v.look }
+    return { exposure: v.exposure, gamma: v.gamma, transform: v.transform }
   }
 
   private colorGrading: ColorGradingOptions = {
@@ -1044,7 +1078,7 @@ export class Engine {
     const v = this.viewTransform
     if (patch.exposure !== undefined) v.exposure = patch.exposure
     if (patch.gamma !== undefined) v.gamma = patch.gamma
-    if (patch.look !== undefined) v.look = patch.look
+    if (patch.transform !== undefined) v.transform = patch.transform
     if (this.device && this.compositeUniformBuffer) {
       this.writeCompositeViewUniforms()
     }
@@ -1076,8 +1110,10 @@ export class Engine {
     u[10] = bg?.z ?? 0
     // Base-layer mode only. A user effect is a separate LAYER over whichever
     // base is active, and needs no flag of its own: the composite pipeline is
-    // rebuilt per effect, so the compiled variant IS the flag. u[25] is spare.
+    // rebuilt per effect, so the compiled variant IS the flag.
     u[11] = this.backdropEquirectView ? 2 : bg ? 1 : 0
+    // Which display transform forms the frame (see viewTransform in composite.ts).
+    u[25] = v.transform === "agx" ? 2 : v.transform === "standard" ? 1 : 0
     u[26] = this.canvas.width
     u[27] = this.canvas.height
     // ── Grade (viewU[7..9]) ── The UI's three tonal COLORS map to ASC CDL here,
@@ -1148,6 +1184,7 @@ export class Engine {
         { binding: 7, resource: { buffer: this.effect?.paramsBuffer ?? this.bgParamsDummyBuffer } },
         { binding: 8, resource: this.depthReadView },
         { binding: 9, resource: { buffer: this.dofUniformBuffer } },
+        { binding: 10, resource: (this.agxLutTexture ?? this.agxFallbackTexture).createView({ dimension: "3d" }) },
       ],
     })
   }
@@ -1638,6 +1675,37 @@ export class Engine {
   // smooth gradients) while still passing through every anchor (look preserved) and staying
   // monotone (no tonemap overshoot/ringing). Domain is uniform in log2 space: anchor k sits
   // at t=k, k=0..13 (t = log2(linear)+10). See composite.ts::filmic for the sampling map.
+  /**
+   * Decompress and upload Blender's AgX cube.
+   *
+   * Deliberately off the critical path: it is 723 KB once inflated, and a frame
+   * rendered before it lands should show the scene under whatever transform is
+   * already there rather than wait. Until then binding 10 holds a 1×1×1 stand-in,
+   * which is only ever sampled if someone selects AgX in that window.
+   */
+  private async loadAgxLut(): Promise<void> {
+    try {
+      const packed = Uint8Array.from(atob(AGX_LUT_GZ), (ch) => ch.charCodeAt(0))
+      const stream = new Blob([packed]).stream().pipeThrough(new DecompressionStream("gzip"))
+      const bytes = new Uint8Array(await new Response(stream).arrayBuffer())
+      const n = AGX_LUT_SIZE
+      if (bytes.byteLength !== n * n * n * 4) throw new Error(`AgX LUT is ${bytes.byteLength} bytes, expected ${n ** 3 * 4}`)
+      const tex = this.device.createTexture({
+        label: "AgX 57³ LUT",
+        size: [n, n, n],
+        dimension: "3d",
+        format: "rgb10a2unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+      })
+      // .cube order is red fastest, which is exactly a 3D texture's own layout.
+      this.device.queue.writeTexture({ texture: tex }, bytes, { bytesPerRow: n * 4, rowsPerImage: n }, [n, n, n])
+      this.agxLutTexture = tex
+      this.rebuildCompositeBindGroup()
+    } catch {
+      // A missing LUT costs AgX, not the renderer — the other transforms stand.
+    }
+  }
+
   private bakeFilmicLut() {
     const anchors = [
       0.0028, 0.0068, 0.0151, 0.0313, 0.061, 0.112, 0.192, 0.306, 0.459, 0.631, 0.82, 0.907, 0.962, 0.989,
@@ -1911,6 +1979,13 @@ export class Engine {
         // StyleUniforms for compiled graph shaders (adjust-tier sliders). Hand-written
         // presets simply don't declare it — a layout may carry bindings a shader ignores.
         { binding: 4, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        // Style-group image maps. A PMX material carries one image; a
+        // Blender-authored look needs a lightmap or ramp beside it, and those
+        // belong to the GROUP rather than to the model's own material data.
+        { binding: 5, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        { binding: 6, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        { binding: 7, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        { binding: 8, visibility: GPUShaderStage.FRAGMENT, texture: {} },
       ],
     })
 
@@ -2043,6 +2118,14 @@ export class Engine {
 
     // One-shot bake of Blender EEVEE's combined BRDF LUT (DFG + LTC packed rgba8unorm).
     this.bakeBrdfLut()
+    this.agxFallbackTexture = this.device.createTexture({
+      label: "AgX LUT fallback",
+      size: [1, 1, 1],
+      dimension: "3d",
+      format: "rgb10a2unorm",
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    })
+    void this.loadAgxLut()
     this.bakeFilmicLut()
 
     // Now that shadow resources exist, create the main per-frame bind group
@@ -2337,8 +2420,9 @@ export class Engine {
       // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
       // (time, _, canvas width, canvas height) for user effects · three grade
       // vectors (CDL offset+contrast, power+saturation, slope+flag) · camera
-      // world position, for an effect placing itself in the scene.
-      size: 176,
+      // world position, for an effect placing itself in the scene · four
+      // character positions, for one that wants to respond to the cast.
+      size: 240,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
     })
     this.dofUniformBuffer = this.device.createBuffer({
@@ -2378,6 +2462,9 @@ export class Engine {
           texture: { sampleType: "depth", viewDimension: "2d", multisampled: true },
         },
         { binding: 9, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        // AgX's 57³ cube. Decompressed and uploaded off the critical path, so a
+        // 1×1×1 stand-in keeps the bind group valid until it arrives.
+        { binding: 10, visibility: GPUShaderStage.FRAGMENT, texture: { viewDimension: "3d" } },
       ],
     })
     this.fallbackEquirectTexture = this.device.createTexture({
@@ -3293,7 +3380,7 @@ export class Engine {
     // explicit destroy). Per-model group buffers are torn down in removeModel; the shared
     // zero buffer is engine-owned.
     this.forEachInstance((inst) => {
-      for (const install of inst.styleGroups.values()) install.uniformBuffer.destroy()
+      for (const install of inst.styleGroups.values()) this.destroyInstall(install)
       inst.styleGroups.clear()
     })
     this.zeroStyleBuffer?.destroy()
@@ -3442,7 +3529,7 @@ export class Engine {
       buf.destroy()
     }
     // Per-group StyleUniforms buffers aren't in gpuBuffers (allocated post-load).
-    for (const install of inst.styleGroups.values()) install.uniformBuffer.destroy()
+    for (const install of inst.styleGroups.values()) this.destroyInstall(install)
     this.modelInstances.delete(name)
   }
 
@@ -3524,11 +3611,58 @@ export class Engine {
 
   // Build a material's bind group with binding(4) pointing at a given StyleUniforms buffer
   // (the group's buffer when grouped, or the shared zero buffer when ungrouped).
-  private createMaterialBindGroup(label: string, baseEntries: GPUBindGroupEntry[], styleBuffer: GPUBuffer): GPUBindGroup {
+  /** A group's uniform buffer and its maps have the same lifetime — freeing one
+   *  without the other is how a re-apply leaks GPU memory a frame at a time. */
+  private destroyInstall(install: GroupInstall): void {
+    install.uniformBuffer.destroy()
+    for (const tex of install.images ?? []) 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) => {
+      if (!entry) return null
+      const wrapped = "source" in entry
+      const src = wrapped ? entry.source : entry
+      const width = Math.max(1, "naturalWidth" in src ? src.naturalWidth : src.width)
+      const height = Math.max(1, "naturalHeight" in src ? src.naturalHeight : src.height)
+      const tex = this.device.createTexture({
+        label: `group map: ${group.id}`,
+        size: [width, height],
+        // Colour maps decode to linear on sample, the way material textures do;
+        // data maps must not, or every threshold packed in their channels moves.
+        format: wrapped && entry.srgb ? "rgba8unorm-srgb" : "rgba8unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+      })
+      this.device.queue.copyExternalImageToTexture(
+        { source: src },
+        { texture: tex, premultipliedAlpha: wrapped && entry.premultiplied === true },
+        [width, height],
+      )
+      return tex
+    })
+  }
+
+  private createMaterialBindGroup(
+    label: string,
+    baseEntries: GPUBindGroupEntry[],
+    styleBuffer: GPUBuffer,
+    groupImages?: (GPUTexture | null)[],
+  ): GPUBindGroup {
+    // Every material bind group in the engine is built here, which is why the
+    // group's maps are threaded through this one function rather than patched in
+    // at each call site — an unset slot reads white, never stale.
+    const slots: GPUBindGroupEntry[] = []
+    for (let i = 0; i < 4; i++) {
+      const tex = groupImages?.[i] ?? this.fallbackMaterialTexture
+      slots.push({ binding: 5 + i, resource: tex.createView() })
+    }
     return this.device.createBindGroup({
       label,
       layout: this.mainPerMaterialBindGroupLayout,
-      entries: [...baseEntries, { binding: 4, resource: { buffer: styleBuffer } }],
+      entries: [...baseEntries, { binding: 4, resource: { buffer: styleBuffer } }, ...slots],
     })
   }
 
@@ -5500,7 +5634,7 @@ export class Engine {
     for (const [id, install] of inst.styleGroups) {
       if (!nextIds.has(id)) {
         inst.styleGroupGen.set(id, (inst.styleGroupGen.get(id) ?? 0) + 1)
-        install.uniformBuffer.destroy()
+        this.destroyInstall(install)
         inst.styleGroups.delete(id)
       }
     }
@@ -5537,7 +5671,7 @@ export class Engine {
     const install = inst?.styleGroups.get(groupId)
     if (!inst || !install) return
     inst.styleGroupGen.set(groupId, (inst.styleGroupGen.get(groupId) ?? 0) + 1) // discard in-flight compile
-    install.uniformBuffer.destroy()
+    this.destroyInstall(install)
     inst.styleGroups.delete(groupId)
     this.assignDrawCallGroups(inst, this.currentClaims(inst))
   }
@@ -5548,7 +5682,7 @@ export class Engine {
     if (!inst) return
     for (const [id, install] of inst.styleGroups) {
       inst.styleGroupGen.set(id, (inst.styleGroupGen.get(id) ?? 0) + 1)
-      install.uniformBuffer.destroy()
+      this.destroyInstall(install)
     }
     inst.styleGroups.clear()
     this.assignDrawCallGroups(inst, new Map())
@@ -5648,6 +5782,9 @@ export class Engine {
         usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
       })
 
+    // The outgoing install's maps go with it — a re-apply that changes images
+    // would otherwise strand the old textures for the life of the model.
+    const previousImages = inst.styleGroups.get(group.id)?.images
     inst.styleGroups.set(group.id, {
       group,
       renderClass,
@@ -5656,9 +5793,31 @@ export class Engine {
       pipelineNoDepthWrite,
       overEyesPipeline,
       uniformBuffer,
+      images: this.uploadGroupImages(group),
       slotMap: result.slotMap,
       signature,
     })
+    // Rebind this group's draw calls before the old textures go.
+    //
+    // assignDrawCallGroups only rebuilds a bind group when a material CHANGES
+    // group, which is the wrong test here: swapping the graph on a group a
+    // material already belongs to leaves its id alone while replacing the maps
+    // underneath it. The draw call then kept a bind group holding the outgoing
+    // textures — destroyed on the next line — so a graph swap either sampled the
+    // old maps, or the fallback white where the previous graph had none (which
+    // reads as a blown-out white material through any screen or add), or tripped
+    // a validation error on a destroyed texture. Only a reload cleared it.
+    const install = inst.styleGroups.get(group.id)
+    for (const dc of inst.drawCalls) {
+      if (!dc.baseBindGroupEntries || dc.groupId !== group.id) continue
+      dc.bindGroup = this.createMaterialBindGroup(
+        `material: ${dc.materialName}`,
+        dc.baseBindGroupEntries,
+        uniformBuffer,
+        install?.images,
+      )
+    }
+    for (const tex of previousImages ?? []) tex?.destroy()
     this.writeGroupDefaults(uniformBuffer, group, result.slotMap)
     return { ok: true, diagnostics, slotMap: result.slotMap }
   }
@@ -5679,6 +5838,7 @@ export class Engine {
         `material: ${dc.materialName}`,
         dc.baseBindGroupEntries,
         install ? install.uniformBuffer : this.zeroStyleBuffer,
+        install?.images,
       )
     }
     this.sortDrawCalls(inst)
@@ -5971,6 +6131,40 @@ export class Engine {
       u[40] = cameraPos.x
       u[41] = cameraPos.y
       u[42] = cameraPos.z
+      // Character positions (viewU[11..14]), count in viewU[10].w. Stages are
+      // excluded: an effect asking where the cast is means the characters, and a
+      // stage's origin is wherever its author put it, which is not a place
+      // anything is standing. Four is the cap because the uniform is small and a
+      // scene with five characters is not the case this serves.
+      let n = 0
+      this.forEachInstance((inst) => {
+        if (n >= MAX_EFFECT_SUBJECTS || inst.isStage) return
+        const m = inst.model
+        // The model transform is only where the model was PLACED. A motion moves
+        // the character by animating bones, so an effect anchored to the
+        // transform never follows anyone anywhere — it sits at the spawn point
+        // while they walk out of it. Composed exactly as the follow camera
+        // composes it, for the same reason: bone matrices are model-space.
+        let px = m.position.x
+        let py = m.position.y
+        let pz = m.position.z
+        for (const bone of SUBJECT_BONES) {
+          const pos = m.getBoneWorldPosition(bone)
+          if (!pos) continue
+          const sc = m.scale
+          pos.setXYZ(pos.x * sc, pos.y * sc, pos.z * sc)
+          Quat.rotateVecInto(m.rotation, pos, pos)
+          px += pos.x
+          py += pos.y
+          pz += pos.z
+          break
+        }
+        u[44 + n * 4] = px
+        u[45 + n * 4] = py
+        u[46 + n * 4] = pz
+        n++
+      })
+      u[43] = n
       this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u)
     }
   }

package/src/graph/presets/body.ts

@@ -55,7 +55,7 @@ export const BODY_GRAPH: ShaderGraph = {
     {
       id: "principled",
       type: "principled",
-      inputs: { metallic: 0.0, specular: 0.5, roughness: 0.3, spec_clamp: 10.0, sheen: 0.0, sheen_tint: 0.0 },
+      inputs: { metallic: 0.0, specular_ior_level: 0.5, roughness: 0.3, spec_clamp: 10.0, sheen_weight: 0.0, sheen_tint: 0.0 },
     },
     { id: "p_sum", type: "add_shader" },
     { id: "mix_shader_001", type: "mix_shader", inputs: { fac: 0.5 } },
@@ -92,7 +92,7 @@ export const BODY_GRAPH: ShaderGraph = {
     { from: { node: "noise_ramp", socket: "fac_out" }, to: { node: "principled_base", socket: "fac" } },
     { from: { node: "bc", socket: "color" }, to: { node: "principled_base", socket: "a" } },
     { from: { node: "bc", socket: "color" }, to: { node: "p_emit", socket: "color" } },
-    { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base" } },
+    { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base_color" } },
     { from: { node: "bump", socket: "vector" }, to: { node: "principled", socket: "normal" } },
     { from: { node: "principled", socket: "color" }, to: { node: "p_sum", socket: "a" } },
     { from: { node: "p_emit", socket: "color" }, to: { node: "p_sum", socket: "b" } },

package/src/graph/presets/cloth_rough.ts

@@ -30,7 +30,7 @@ export const CLOTH_ROUGH_GRAPH: ShaderGraph = {
     {
       id: "principled",
       type: "principled",
-      inputs: { metallic: 0.0, specular: 0.8, roughness: 0.8187, spec_clamp: 10.0, sheen: 0.0, sheen_tint: 0.0 },
+      inputs: { metallic: 0.0, specular_ior_level: 0.8, roughness: 0.8187, spec_clamp: 10.0, sheen_weight: 0.0, sheen_tint: 0.0 },
     },
     { id: "mix_shader_001", type: "mix_shader", inputs: { fac: 0.8999999761581421 } },
   ],
@@ -55,7 +55,7 @@ export const CLOTH_ROUGH_GRAPH: ShaderGraph = {
     { from: { node: "noise_ramp", socket: "fac_out" }, to: { node: "bump", socket: "height" } },
     { from: { node: "geo", socket: "normal" }, to: { node: "bump", socket: "normal" } },
     { from: { node: "tex", socket: "color" }, to: { node: "principled_base", socket: "color" } },
-    { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base" } },
+    { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base_color" } },
     { from: { node: "bump", socket: "vector" }, to: { node: "principled", socket: "normal" } },
     { from: { node: "npr_emit", socket: "color" }, to: { node: "mix_shader_001", socket: "a" } },
     { from: { node: "principled", socket: "color" }, to: { node: "mix_shader_001", socket: "b" } },

package/src/graph/presets/cloth_smooth.ts

@@ -27,7 +27,7 @@ export const CLOTH_SMOOTH_GRAPH: ShaderGraph = {
     {
       id: "principled",
       type: "principled",
-      inputs: { metallic: 0.0, specular: 0.8, roughness: 0.5, spec_clamp: 10.0, sheen: 0.0, sheen_tint: 0.0 },
+      inputs: { metallic: 0.0, specular_ior_level: 0.8, roughness: 0.5, spec_clamp: 10.0, sheen_weight: 0.0, sheen_tint: 0.0 },
     },
     { id: "mix_shader_001", type: "mix_shader", inputs: { fac: 0.8999999761581421 } },
   ],
@@ -48,7 +48,7 @@ export const CLOTH_SMOOTH_GRAPH: ShaderGraph = {
     { from: { node: "hue_004", socket: "color" }, to: { node: "npr_overlay", socket: "b" } },
     { from: { node: "npr_overlay", socket: "color" }, to: { node: "npr_emit", socket: "color" } },
     { from: { node: "tex", socket: "color" }, to: { node: "principled_base", socket: "color" } },
-    { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base" } },
+    { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base_color" } },
     { from: { node: "npr_emit", socket: "color" }, to: { node: "mix_shader_001", socket: "a" } },
     { from: { node: "principled", socket: "color" }, to: { node: "mix_shader_001", socket: "b" } },
   ],

package/src/graph/presets/default.ts

@@ -18,13 +18,13 @@ export const DEFAULT_GRAPH: ShaderGraph = {
     {
       id: "principled",
       type: "principled",
-      inputs: { metallic: 0.0, specular: 0.5, roughness: 0.5, spec_clamp: 10.0, sheen: 0.0, sheen_tint: 0.0 },
+      inputs: { metallic: 0.0, specular_ior_level: 0.5, roughness: 0.5, spec_clamp: 10.0, sheen_weight: 0.0, sheen_tint: 0.0 },
     },
   ],
   links: [
     { from: { node: "tex", socket: "color" }, to: { node: "base", socket: "a" } },
     { from: { node: "mat", socket: "color" }, to: { node: "base", socket: "b" } },
-    { from: { node: "base", socket: "color" }, to: { node: "principled", socket: "base" } },
+    { from: { node: "base", socket: "color" }, to: { node: "principled", socket: "base_color" } },
   ],
   output: { node: "principled", socket: "color" },
 }

package/src/graph/presets/eye.ts

@@ -18,13 +18,13 @@ export const EYE_GRAPH: ShaderGraph = {
     {
       id: "principled",
       type: "principled",
-      inputs: { metallic: 0.0, specular: 0.5, roughness: 0.5, spec_clamp: 1e30, sheen: 0.0, sheen_tint: 0.0 },
+      inputs: { metallic: 0.0, specular_ior_level: 0.5, roughness: 0.5, spec_clamp: 1e30, sheen_weight: 0.0, sheen_tint: 0.0 },
     },
     { id: "emission", type: "emission", inputs: { strength: 1.5 } },
     { id: "add", type: "add_shader" },
   ],
   links: [
-    { from: { node: "tex", socket: "color" }, to: { node: "principled", socket: "base" } },
+    { from: { node: "tex", socket: "color" }, to: { node: "principled", socket: "base_color" } },
     { from: { node: "tex", socket: "color" }, to: { node: "emission", socket: "color" } },
     { from: { node: "principled", socket: "color" }, to: { node: "add", socket: "a" } },
     { from: { node: "emission", socket: "color" }, to: { node: "add", socket: "b" } },