reze-engine 0.61.6 → 0.62.0

package/dist/shaders/passes/physics-debug.js

@@ -0,0 +1,69 @@
+// Wireframe + solid overlay for physics rigid bodies (sphere / box / capsule).
+// Rendered in its own pass after composite, straight to the swapchain — no
+// MSAA, no depth, no MRT — so it sits cleanly on top of the tonemapped scene
+// regardless of camera angle, model occlusion, or the composite alpha gate.
+//
+//   SHAPE_KIND   0 = sphere   → unit-sphere line/tri primitive scaled by size.x (radius)
+//                1 = box      → unit cube ±1 scaled by size.xyz (half-extents)
+//                2 = capsule  → unit cap+ring with per-vertex `axial` (-1/0/+1)
+//                               that lifts cap rings/arcs ±halfHeight along Y;
+//                               XZ scales by size.x (radius), Y by size.y/2.
+//   SOLID_ALPHA  fragment alpha multiplier. Wireframe pipelines leave this at
+//                1.0 for crisp edges; solid pipelines set it to ~0.2 so the fill
+//                stays gentle under stacked bodies.
+export const PHYSICS_DEBUG_SHADER_WGSL = /* wgsl */ `
+struct CameraUniforms {
+  view: mat4x4f,
+  projection: mat4x4f,
+  viewPos: vec3f,
+  _pad: f32,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+override SHAPE_KIND: u32 = 0u;
+override SOLID_ALPHA: f32 = 1.0;
+
+struct VsIn {
+  @location(0) unit: vec4f,       // xyz = unit pos; w = capsule axial anchor
+  @location(1) modelCol0: vec4f,
+  @location(2) modelCol1: vec4f,
+  @location(3) modelCol2: vec4f,
+  @location(4) modelCol3: vec4f,
+  @location(5) size: vec4f,       // xyz = size; w unused
+  @location(6) color: vec4f,
+};
+
+struct VsOut {
+  @builtin(position) pos: vec4f,
+  @location(0) color: vec4f,
+};
+
+@vertex
+fn vsMain(in: VsIn) -> VsOut {
+  let model = mat4x4f(in.modelCol0, in.modelCol1, in.modelCol2, in.modelCol3);
+  var local: vec3f;
+  if (SHAPE_KIND == 1u) {
+    local = in.unit.xyz * in.size.xyz;
+  } else if (SHAPE_KIND == 2u) {
+    // PMX capsule: size.x = radius, size.y = full cylinder height. Bullet 2.x's
+    // btCapsuleShape(radius, height) stores height/2 internally, so the actual
+    // collision cylinder spans ±size.y/2 — halve here to match.
+    let r = in.size.x;
+    let halfH = in.size.y * 0.5;
+    local = vec3f(in.unit.x * r, in.unit.y * r + halfH * in.unit.w, in.unit.z * r);
+  } else {
+    local = in.unit.xyz * in.size.x;
+  }
+  let world = model * vec4f(local, 1.0);
+  var out: VsOut;
+  out.pos = camera.projection * camera.view * world;
+  out.color = in.color;
+  return out;
+}
+
+@fragment
+fn fsMain(in: VsOut) -> @location(0) vec4f {
+  return vec4f(in.color.rgb, in.color.a * SOLID_ALPHA);
+}
+`;

package/dist/shaders/passes/scene-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-contract.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/scene-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;uDAEuD;AACvD,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,GAAG,EAAE,gBAAgB,CAAA;IACrB,iEAAiE;IACjE,GAAG,EAAE,gBAAgB,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,gBAA6B,CAAA;AAkB3D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;GAMG;AACH,KAAK,gBAAgB;AACnB,2DAA2D;AACzD,UAAU;AACZ;;+CAE+C;GAC7C,QAAQ;AACV,uEAAuE;GACrE,SAAS;AACX;;;;6EAI6E;GAC3E,QAAQ;AACV;;;;;;yEAMyE;GACvE,mBAAmB;AACrB,iEAAiE;GAC/D,UAAU;AACZ;;;mDAGmD;GACjD,mBAAmB;AACrB;;;oCAGoC;GAClC,OAAO;AACT;;;kDAGkD;GAChD,eAAe,CAAA;AAqFnB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,mBAAmB,EAAE,CAoBhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAE3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAmB7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}
+{"version":3,"file":"scene-contract.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/scene-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;uDAEuD;AACvD,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,GAAG,EAAE,gBAAgB,CAAA;IACrB,iEAAiE;IACjE,GAAG,EAAE,gBAAgB,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,gBAA6B,CAAA;AAkB3D,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;GAMG;AACH,KAAK,gBAAgB;AACnB,2DAA2D;AACzD,UAAU;AACZ;;+CAE+C;GAC7C,QAAQ;AACV,uEAAuE;GACrE,SAAS;AACX;;;;6EAI6E;GAC3E,QAAQ;AACV;;;;;;yEAMyE;GACvE,mBAAmB;AACrB,iEAAiE;GAC/D,UAAU;AACZ;;;mDAGmD;GACjD,mBAAmB;AACrB;;;oCAGoC;GAClC,OAAO;AACT;;;kDAGkD;GAChD,eAAe,CAAA;AAyFnB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,mBAAmB,EAAE,CAoBhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAE3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAmB7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/shaders/passes/scene-contract.js

@@ -72,7 +72,7 @@ const ADD_BOTH = {
  * OVER for something that arrives ALREADY premultiplied: take the source whole
  * and let it displace the destination by its own coverage.
  *
- * The ground needs this and nothing else does. Every other class writes a
+ * The ground, the mirror and particles need it. The other classes write a
  * straight colour and an alpha, and the src-alpha factor premultiplies it once
  * on the way in. The ground cannot: its coverage is the SUM of a lit surface
  * and a colourless shadow-catcher layer, so it has to weight its own colour by
@@ -125,7 +125,11 @@ const BLENDS = {
     // everything else, and coverage is what the blend applies.
     ground: [PREMULTIPLIED_OVER, ALPHA_OVER],
     outline: [ALPHA_OVER, ALPHA_OVER],
-    particle: [ALPHA_OVER, ALPHA_OVER],
+    // PREMULTIPLIED colour: the particle fragment weights its colour by its own
+    // alpha before it writes (passes/particles.ts), so the src-alpha blend would
+    // weight it a second time — a splash at alpha 0.1 arrived at a hundredth of
+    // its colour instead of a tenth. The aux mask is written straight, as ever.
+    particle: [PREMULTIPLIED_OVER, ALPHA_OVER],
     "particle-additive": [ADD_KEEP_ALPHA, ADD_BOTH],
     trail: [ADD_PREMULTIPLIED, ALPHA_OVER],
 };

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

@@ -1 +1 @@
-{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AA+BA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd;sFACkF;IAClF,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CA6ZR"}
+{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AAgCA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd;sFACkF;IAClF,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CA6ZR"}

package/dist/shaders/passes/trails.js

@@ -12,6 +12,7 @@ import { sceneIdFieldWgsl, sceneIdPadWgsl } from "./scene-contract";
 import { idApi } from "../id-api";
 import { sceneLightApi } from "../scene-light-api";
 import { pointsApi } from "../points-api";
+import { textureApi } from "../texture-api";
 /**
  * Sub-segments drawn between each pair of recorded samples.
  *
@@ -249,7 +250,7 @@ fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
         gridReadApi(0, 8, 9, src.gridSize) +
         // Stubbed: this module cannot read an attachment the scene pass writes — see
         // id-api.ts. The author's whole file compiles here, so the names must exist.
-        idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false) +
+        idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false) + textureApi(0) +
         "\n// ── user effect ──\n" +
         src.wgsl +
         /* wgsl */ `

package/dist/shaders/texture-api.d.ts

@@ -0,0 +1,9 @@
+/** How many pictures one effect can read. */
+export declare const MAX_EFFECT_TEXTURES = 4;
+/**
+ * rzTexture / rzTextureLod. `count` is the effect's `#textures` (0 = stubs);
+ * the textures take bindings first..first+count-1 in `group` and the one
+ * sampler `sampler`.
+ */
+export declare function textureApi(count: number, group?: number, first?: number, sampler?: number): string;
+//# sourceMappingURL=texture-api.d.ts.map

package/dist/shaders/texture-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture-api.d.ts","sourceRoot":"","sources":["../../src/shaders/texture-api.ts"],"names":[],"mappings":"AAkBA,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,EAAE,KAAK,SAAI,EAAE,OAAO,SAAI,GAAG,MAAM,CA6BnF"}

package/dist/shaders/texture-api.js

@@ -0,0 +1,54 @@
+// Pictures an effect is handed by its host — `#textures N`.
+//
+//     #textures 2
+//
+// gives the PARTICLE SHADING rzTexture(i, uv) and rzTextureLod(i, uv, lod) over
+// N images the host passes with the install (setEffects' `textures`, slot i =
+// picture i). uv (0,0) is the image's top-left row, the style graph's
+// tex_image convention, and it repeats. A slot the host left empty reads white.
+//
+// WHY: a game's splash is a picture on a card, and an effect that may only draw
+// procedurally can only ever guess at it — shape, coverage, veins, each a guess
+// to be corrected. A converted stage carries the game's own textures, and this
+// is how its particles draw them.
+//
+// Fragment-only, because textureSample is: the compute stage and every other
+// module the author's file is spliced into get STUBS returning zero, so one
+// effect file compiles in every mount it has.
+/** How many pictures one effect can read. */
+export const MAX_EFFECT_TEXTURES = 4;
+/**
+ * rzTexture / rzTextureLod. `count` is the effect's `#textures` (0 = stubs);
+ * the textures take bindings first..first+count-1 in `group` and the one
+ * sampler `sampler`.
+ */
+export function textureApi(count, group = 0, first = 0, sampler = 0) {
+    if (count <= 0) {
+        return /* wgsl */ `
+fn rzTexture(i: u32, uv: vec2f) -> vec4f { return vec4f(0.0); }
+fn rzTextureLod(i: u32, uv: vec2f, lod: f32) -> vec4f { return vec4f(0.0); }
+`;
+    }
+    const n = Math.min(count, MAX_EFFECT_TEXTURES);
+    let decl = `@group(${group}) @binding(${sampler}) var _rzTexSampler: sampler;\n`;
+    for (let k = 0; k < n; k++)
+        decl += `@group(${group}) @binding(${first + k}) var _rzTex${k}: texture_2d<f32>;\n`;
+    // Every slot is sampled unconditionally and the one asked for is selected:
+    // textureSample must be reached in uniform control flow, and a switch on a
+    // per-fragment index is not.
+    const pick = (call) => {
+        let body = "  var c = vec4f(0.0);\n";
+        for (let k = 0; k < n; k++)
+            body += `  let s${k} = ${call(k)};\n  if (i == ${k}u) { c = s${k}; }\n`;
+        return body + "  return c;\n";
+    };
+    return (decl +
+        /* wgsl */ `
+/** Picture i of the effect's #textures, at uv ((0,0) top-left, repeating). */
+fn rzTexture(i: u32, uv: vec2f) -> vec4f {
+${pick((k) => `textureSample(_rzTex${k}, _rzTexSampler, uv)`)}}
+/** The same at an explicit mip level — usable where derivatives are not. */
+fn rzTextureLod(i: u32, uv: vec2f, lod: f32) -> vec4f {
+${pick((k) => `textureSampleLevel(_rzTex${k}, _rzTexSampler, uv, lod)`)}}
+`);
+}

package/package.json

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

@@ -118,6 +118,8 @@ import {
   buildParticleRenderShader,
   PARTICLE_LIGHT_BINDING,
   PARTICLE_POINTS_BINDING,
+  PARTICLE_TEXTURE_BINDING,
+  PARTICLE_TEXTURE_SAMPLER_BINDING,
   particleEntryPoints,
   PARTICLE_INDIRECT_BINDING,
   PARTICLE_INDIRECT_BYTES,
@@ -183,10 +185,17 @@ export type MaterialPresetMap = Partial<Record<MaterialPreset, string[]>>
 
 // Substring hints mapping common PMX material names (JP/CN/EN) to a style category,
 // tried when a material isn't in the caller's explicit override map. Ordered: more
-// specific families first (靴下 must hit stockings before 靴 hits cloth). A material
+// specific families first (靴下 must hit socks before 靴 hits cloth). A material
 // matching nothing resolves to null — it stays ungrouped (neutral default).
+//
+// SOCKS ARE CLOTH, STOCKINGS ARE SHEER. The game draws a white sock as opaque
+// fabric on the ordinary cloth ramp; only a sheer stocking gets the stockings
+// look, whose see-through blend made white socks glow flat or wash out. So the
+// sock words go to rough cloth ahead of the stocking words — 袜子 before the
+// bare 袜 that 丝袜 (silk stockings) still reaches.
 const PRESET_NAME_HINTS: Array<[MaterialPreset, string[]]> = [
-  ["stockings", ["靴下", "ソックス", "タイツ", "ニーソ", "袜", "stocking", "socks", "tights"]],
+  ["cloth_rough", ["靴下", "ソックス", "ニーソ", "袜子", "短袜", "棉袜", "socks", "sock"]],
+  ["stockings", ["タイツ", "ストッキング", "袜", "stocking", "tights", "pantyhose"]],
   [
     "eye",
     ["白目", "目影", "二重", "睫", "まつげ", "まゆ", "眉", "目", "瞳", "眼", "eye", "iris", "pupil", "lash", "brow"],
@@ -481,6 +490,17 @@ export type EffectParamValue = number | { x: number; y: number; z: number }
 /** A vector by shape rather than by class — Vec3 satisfies it, and so does a
  *  JSON object out of a scene document or a literal typed into a console. */
 export type XYZ = { x: number; y: number; z: number }
+/**
+ * One picture an effect's `#textures` reads, as the host holds it — slot i of
+ * the install's `textures` is rzTexture(i, uv). `srgb` for a colour picture
+ * (decoded to linear on sample), false for data. Null, or a slot past the end,
+ * reads white. The engine never fetches: images arrive decoded, as models do.
+ */
+export type EffectTextureInput = {
+  source: ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageData
+  srgb: boolean
+} | null
+
 export type EffectResult = {
   ok: boolean
   /** Compile/validation errors, line:col relative to the USER's WGSL. Also
@@ -1506,6 +1526,9 @@ interface EffectParticles {
    *  indirect arguments it writes them to. Null when the effect declared none —
    *  the whole pool is then stepped and drawn. */
   live: { pipeline: GPUComputePipeline; indirect: GPUBuffer; binds: [GPUBindGroup, GPUBindGroup] } | null
+  /** `#textures`: the pictures the host handed over, uploaded for this effect
+   *  alone and destroyed with it. Empty when it declared none. */
+  textures: GPUTexture[]
 }
 
 /**
@@ -4773,6 +4796,8 @@ export class Engine {
     anchors: { bone: string; trail: boolean }[],
     /** Its row of that table: local slot → scene slot. */
     alias: number[],
+    /** The pictures for `#textures`, as the host passed them. */
+    textures?: EffectTextureInput[],
   ): Promise<{ ok: true; instance: EffectInstance; warnings: string[] } | EffectResult> {
     const noMounts = { background: false, foreground: false }
     if (!this.device) return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts, params: [], duration: 0, readsCast: false }
@@ -5093,6 +5118,7 @@ export class Engine {
       particles?.uniform.destroy()
       particles?.points?.buffer.destroy()
       particles?.live?.indirect.destroy()
+      for (const t of particles?.textures ?? []) t.destroy()
       grid?.textures[0].destroy()
       grid?.textures[1].destroy()
       grid?.uniform.destroy()
@@ -5108,7 +5134,7 @@ export class Engine {
       grid = built.state
     }
     if (wantsParticles) {
-      const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor, grid)
+      const built = await this.buildParticles(wgsl, d, anchors, alias, paramsFor, grid, textures)
       if (!built.ok) return abandon(built.diagnostics)
       particles = built.state
     }
@@ -5269,6 +5295,9 @@ export class Engine {
            *  aimed at one dancer should not spend its first frame on all four,
            *  which on a ribbon or a sigil reads as a flash. */
           subjects?: readonly string[] | null
+          /** `#textures`: slot i is the effect's rzTexture(i, uv). See
+           *  EffectTextureInput. Ignored by an effect that declares none. */
+          textures?: EffectTextureInput[]
         }[]
       | null,
   ): Promise<EffectResult[]> {
@@ -5322,6 +5351,7 @@ export class Engine {
         requested[i].params,
         perEffectAnchors[i],
         table.alias[i],
+        requested[i].textures,
       )
       if (!("instance" in built)) {
         // Contained: this one is out, the others carry on.
@@ -5437,13 +5467,13 @@ export class Engine {
    * Install ONE effect — the singleton API, kept because most scenes are one
    * effect and every existing caller uses it. A one-element setEffects.
    */
-  async setEffect(wgsl: string | null, params?: Record<string, EffectParamValue>): Promise<EffectResult> {
+  async setEffect(wgsl: string | null, params?: Record<string, EffectParamValue>, textures?: EffectTextureInput[]): Promise<EffectResult> {
     const noMounts = { background: false, foreground: false }
     if (wgsl === null) {
       await this.setEffects(null)
       return { ok: true, diagnostics: [], mounts: noMounts, params: [], duration: 0, readsCast: false }
     }
-    const [result] = await this.setEffects([{ wgsl, params }])
+    const [result] = await this.setEffects([{ wgsl, params, textures }])
     return result ?? { ok: false, diagnostics: ["effect failed to install"], mounts: noMounts, params: [], duration: 0, readsCast: false }
   }
 
@@ -5464,6 +5494,8 @@ export class Engine {
     /** This effect's own grid, already built, or null when it declared none.
      *  Read-only here: the pool samples it, the grid pass owns it. */
     grid: EffectGrid | null,
+    /** `#textures`: the host's pictures, slot for slot. */
+    textureInputs?: EffectTextureInput[],
   ): Promise<{ ok: true; state: EffectParticles } | { ok: false; diagnostics: string[] }> {
     // No pragma means "some": an author who wrote the trio clearly wants
     // particles, and failing over a missing comment would be pedantry.
@@ -5477,8 +5509,15 @@ export class Engine {
       gridSize: grid?.size ?? 0,
       cover: particleEntryPoints(wgsl).cover,
       live: particleEntryPoints(wgsl).count,
+      textures: d.textures,
     }
     const prepass = src.blend === "cutout" && src.cover
+    // `#textures`: uploaded now, each with its mips, for this effect alone. A
+    // slot the host left empty is null here and binds the white fallback.
+    const textures = this.uploadEffectTextures(textureInputs, d.textures)
+    const dropTextures = () => {
+      for (const t of textures) t?.destroy()
+    }
     const points = d.points
       ? {
           prefix: d.points,
@@ -5518,11 +5557,13 @@ export class Engine {
     const computeModule = await compile(buildParticleComputeShader(src, cast), "particle compute")
     if (Array.isArray(computeModule)) {
       points?.buffer.destroy()
+      dropTextures()
       return { ok: false, diagnostics: computeModule }
     }
     const renderModule = await compile(buildParticleRenderShader(src, cast), "particle render")
     if (Array.isArray(renderModule)) {
       points?.buffer.destroy()
+      dropTextures()
       return { ok: false, diagnostics: renderModule }
     }
 
@@ -5602,6 +5643,18 @@ export class Engine {
           ...(withIndirect
             ? [{ binding: PARTICLE_INDIRECT_BINDING, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" as const } }]
             : []),
+          // `#textures`, the shading stage only and only when declared — an
+          // effect without them keeps exactly the layout it always had.
+          ...(shadow && textures.length
+            ? [
+                ...textures.map((_, k) => ({
+                  binding: PARTICLE_TEXTURE_BINDING + k,
+                  visibility: GPUShaderStage.FRAGMENT,
+                  texture: { sampleType: "float" as const },
+                })),
+                { binding: PARTICLE_TEXTURE_SAMPLER_BINDING, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" as const } },
+              ]
+            : []),
         ],
       })
     /** One per GRID PARITY, for the reason rebuildFieldBindGroup gives: the grid
@@ -5634,6 +5687,15 @@ export class Engine {
                 ]
               : []),
             ...(withIndirect && indirect ? [{ binding: PARTICLE_INDIRECT_BINDING, resource: { buffer: indirect } }] : []),
+            ...(shadow && textures.length
+              ? [
+                  ...textures.map((t, k) => ({
+                    binding: PARTICLE_TEXTURE_BINDING + k,
+                    resource: (t ?? this.fallbackMaterialTexture).createView(),
+                  })),
+                  { binding: PARTICLE_TEXTURE_SAMPLER_BINDING, resource: this.effectTextureSampler() },
+                ]
+              : []),
           ],
         }),
       ) as [GPUBindGroup, GPUBindGroup]
@@ -5716,6 +5778,7 @@ export class Engine {
         uniform.destroy()
         points?.buffer.destroy()
         indirect?.destroy()
+        dropTextures()
         return { ok: false, diagnostics: [scoped.message] }
       }
       return {
@@ -5745,6 +5808,7 @@ export class Engine {
           }),
           points,
           live,
+          textures: textures.filter((t): t is GPUTexture => t !== null),
         },
       }
     } catch (e) {
@@ -5753,6 +5817,7 @@ export class Engine {
       uniform.destroy()
       points?.buffer.destroy()
       indirect?.destroy()
+      dropTextures()
       return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] }
     }
   }
@@ -6521,6 +6586,7 @@ export class Engine {
       e.particles?.uniform.destroy()
       e.particles?.points?.buffer.destroy()
       e.particles?.live?.indirect.destroy()
+      for (const t of e.particles?.textures ?? []) t.destroy()
       e.particles = null
     }
   }
@@ -12389,6 +12455,54 @@ export class Engine {
     for (const set of Object.values(install.imagesByMaterial ?? {})) for (const tex of set) tex?.destroy()
   }
 
+  /**
+   * An effect's `#textures`, uploaded: `count` slots, each with a full mip chain
+   * (a splash card seen from across a stage is a few pixels, and unmipped it
+   * sparkles). Slot k is null where the host gave nothing — the bind group then
+   * reads the white fallback.
+   */
+  private uploadEffectTextures(inputs: EffectTextureInput[] | undefined, count: number): (GPUTexture | null)[] {
+    const out: (GPUTexture | null)[] = []
+    for (let k = 0; k < count; k++) {
+      const entry = inputs?.[k]
+      if (!entry) {
+        out.push(null)
+        continue
+      }
+      const src = entry.source
+      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 mipLevelCount = Math.floor(Math.log2(Math.max(width, height))) + 1
+      const tex = this.device.createTexture({
+        label: `effect texture ${k}`,
+        size: [width, height],
+        mipLevelCount,
+        format: entry.srgb ? "rgba8unorm-srgb" : "rgba8unorm",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+      })
+      this.device.queue.copyExternalImageToTexture({ source: src }, { texture: tex }, [width, height])
+      if (mipLevelCount > 1) this.generateMipmaps(tex, mipLevelCount)
+      out.push(tex)
+    }
+    return out
+  }
+
+  private effectTextureSamplerCache: GPUSampler | null = null
+  /** Linear, mipmapped, repeating — one for every effect's pictures. */
+  private effectTextureSampler(): GPUSampler {
+    if (!this.effectTextureSamplerCache) {
+      this.effectTextureSamplerCache = this.device.createSampler({
+        label: "effect texture sampler",
+        magFilter: "linear",
+        minFilter: "linear",
+        mipmapFilter: "linear",
+        addressModeU: "repeat",
+        addressModeV: "repeat",
+      })
+    }
+    return this.effectTextureSamplerCache
+  }
+
   /** 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, slots = group.images): (GPUTexture | null)[] | undefined {

package/src/graph/presets/cloth_rough.ts

@@ -1,6 +1,8 @@
 // M_Rough_Cloth as a ShaderGraph — port of shaders/materials/cloth_rough.ts.
 // NPR graph identical to M_Smooth_Cloth, but the noise bump subtree IS live on
-// Principled.Normal (weave bump in rest space) and Roughness is raised to 0.8187.
+// Principled.Normal (weave bump in rest space), and it is MATTE where smooth cloth
+// shines: roughness 1, specular 0.25, and a wider toon band (0.20-0.45) so the
+// light rolls off cotton instead of cutting. Smooth keeps 0.5 / 0.8 / 0.25-0.35.
 // The tex_noise node hits the detail=2 peephole → tex_noise_d2.
 
 import type { ShaderGraph } from "../schema"
@@ -19,7 +21,7 @@ export const CLOTH_ROUGH_GRAPH: ShaderGraph = {
     { id: "tex_base", type: "mix/multiply", inputs: { fac: 1.0 } },
     { id: "geo", type: "geometry" },
     { id: "str", type: "shader_to_rgb_diffuse" },
-    { id: "ramp_008", type: "ramp_cardinal", inputs: { pos0: 0.2466, pos1: 0.3466 } },
+    { id: "ramp_008", type: "ramp_cardinal", inputs: { pos0: 0.2, pos1: 0.45 } },
     { id: "mix04_fac", type: "math/multiply", inputs: { b: 0.5 } },
     { id: "dark_tex", type: "hue_sat", inputs: { hue: 0.5, saturation: 1.0, value: 0.19999998807907104, fac: 1.0 } },
     { id: "mix_004", type: "mix/blend" },
@@ -36,7 +38,7 @@ export const CLOTH_ROUGH_GRAPH: ShaderGraph = {
     {
       id: "principled",
       type: "principled",
-      inputs: { metallic: 0.0, specular_ior_level: 0.8, roughness: 0.8187, spec_clamp: 10.0, sheen_weight: 0.0, sheen_tint: 0.0 },
+      inputs: { metallic: 0.0, specular_ior_level: 0.25, roughness: 1.0, spec_clamp: 10.0, sheen_weight: 0.0, sheen_tint: 0.0 },
     },
     { id: "mix_shader_001", type: "mix_shader", inputs: { fac: 0.8999999761581421 } },
   ],

package/src/graph/schema.ts

@@ -74,5 +74,7 @@ export type Diagnostic = {
   message: string
 }
 
-export const MAX_NODES = 64
+// A sanity bound, not a GPU one: a graph compiles to one fragment function and
+// a longer one is only more WGSL. The game ports (X348's sea and water) run 60+.
+export const MAX_NODES = 128
 export const MAX_PARAMS = 16

package/src/shaders/directives.ts

@@ -60,6 +60,16 @@ export type EffectDirectives = {
   /** `#points <prefix>`: every bone on every model whose name starts with it,
    *  as rzPoint(i) in the particle stages. Null when the file declares none. */
   points: string | null
+  /**
+   * `#textures N` (1-4): the particle shading reads N pictures the HOST hands
+   * over with the install (setEffects' `textures`), as rzTexture(i, uv) — uv
+   * (0,0) at the image's top-left, repeating. A game's own splash or spray is a
+   * picture on a card, and drawn procedurally it can only ever be a guess at
+   * it; this is how a converted stage's particles carry the real one. The
+   * other modules an effect is spliced into get the names as stubs returning
+   * zero. 0 when undeclared.
+   */
+  textures: number
   bloom: boolean
   /** This effect takes the cast apart — the host reads the timing. */
   dissolve: boolean
@@ -124,6 +134,7 @@ const SPEC = {
   lights: 1,
   grid: 1,
   points: 1,
+  textures: 1,
   bloom: 0,
   dissolve: 0,
   mirror: 0,
@@ -183,6 +194,7 @@ export function parseDirectives(wgsl: string): DirectiveResult {
     lights: 0,
     grid: 0,
     points: null,
+    textures: 0,
     bloom: false,
     dissolve: false,
     ground: null,
@@ -304,6 +316,15 @@ export function parseDirectives(wgsl: string): DirectiveResult {
       case "points":
         d.points = args[0]
         return
+      case "textures": {
+        const n = num(args[0])
+        if (n === null || !Number.isInteger(n) || n < 1 || n > 4) {
+          errors.push(`${at}: #textures takes a count from 1 to 4`)
+          return
+        }
+        d.textures = n
+        return
+      }
       case "mirror":
         d.mirror = true
         return

package/src/shaders/lights.ts

@@ -49,6 +49,7 @@ import { clockApi, trailSlotsApi, viewportApi } from "./passes/hosted-api"
 import { idApi } from "./id-api"
 import { sceneLightApi, worldAmbientWgsl } from "./scene-light-api"
 import { pointsApi } from "./points-api"
+import { textureApi } from "./texture-api"
 
 /** Words before the first record: the counts, the grid's placement and the
  *  outside mask, four vec4s — see the layout above. */
@@ -179,7 +180,7 @@ ${viewportApi("viewU[6].w")}
 ${trailSlotsApi(cast.trailCount)}
 // The id accessors, stubbed: this module cannot read an attachment the
 // scene pass writes. See id-api.ts — the author's whole file compiles here.
-${idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false)}
+${idApi(false, 0, 0) + castDistanceStub() + sceneLightApi(false, 0, 0) + pointsApi(false) + textureApi(0)}
 // The dials the author declared, if any. A lamp is exactly the thing someone
 // retunes — its colour and its reach — so an emitter reads params like every
 // other mount rather than being the one place a #param resolves to nothing.

package/src/shaders/passes/composite.ts

@@ -8,6 +8,7 @@ import { audioApi } from "../audio-api"
 import { idApi } from "../id-api"
 import { sceneLightApi } from "../scene-light-api"
 import { pointsApi } from "../points-api"
+import { textureApi } from "../texture-api"
 import { castDistanceApi, CAST_FIELD_DIV } from "./cast-distance"
 import { lyricsApi, lyricsTextApi } from "../lyrics-api"
 import { midiApi } from "../midi-api"
@@ -758,6 +759,7 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
     idApi(effect.ids === true, 0, 23) +
     sceneLightApi(false, 0, 0) +
     pointsApi(false) +
+    textureApi(0) +
     // Distance to the cast, in SCREEN pixels: the field is half-res, so a field
     // texel is CAST_FIELD_DIV of them and the accessor scales on the way out.
     // An author writes the width they mean and never learns how it is built.

package/src/shaders/passes/grid.ts

@@ -10,6 +10,7 @@ import { clockApi, trailSlotsApi, viewportApi } from "./hosted-api"
 import { idApi } from "../id-api"
 import { sceneLightApi } from "../scene-light-api"
 import { pointsApi } from "../points-api"
+import { textureApi } from "../texture-api"
 
 // A persistent grid an effect can step and read: the one thing an effect could
 // not have before, which is MEMORY.
@@ -172,6 +173,7 @@ fn rzGrid(uv: vec2f) -> vec4f { return rzGridPrev(uv); }
     idApi(false, 0, 0) +
     sceneLightApi(false, 0, 0) +
     pointsApi(false) +
+    textureApi(0) +
     // Inlined rather than imported from cast-distance, and NOT for tidiness.
     //
     // This module and composite.ts import each other — grid takes