reze-engine 0.50.6 → 0.50.8

package/dist/shaders/passes/physics-debug.d.ts

@@ -0,0 +1,2 @@
+export declare const PHYSICS_DEBUG_SHADER_WGSL = "\nstruct CameraUniforms {\n  view: mat4x4f,\n  projection: mat4x4f,\n  viewPos: vec3f,\n  _pad: f32,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\noverride SHAPE_KIND: u32 = 0u;\noverride SOLID_ALPHA: f32 = 1.0;\n\nstruct VsIn {\n  @location(0) unit: vec4f,       // xyz = unit pos; w = capsule axial anchor\n  @location(1) modelCol0: vec4f,\n  @location(2) modelCol1: vec4f,\n  @location(3) modelCol2: vec4f,\n  @location(4) modelCol3: vec4f,\n  @location(5) size: vec4f,       // xyz = size; w unused\n  @location(6) color: vec4f,\n};\n\nstruct VsOut {\n  @builtin(position) pos: vec4f,\n  @location(0) color: vec4f,\n};\n\n@vertex\nfn vsMain(in: VsIn) -> VsOut {\n  let model = mat4x4f(in.modelCol0, in.modelCol1, in.modelCol2, in.modelCol3);\n  var local: vec3f;\n  if (SHAPE_KIND == 1u) {\n    local = in.unit.xyz * in.size.xyz;\n  } else if (SHAPE_KIND == 2u) {\n    // PMX capsule: size.x = radius, size.y = full cylinder height. Bullet 2.x's\n    // btCapsuleShape(radius, height) stores height/2 internally, so the actual\n    // collision cylinder spans \u00B1size.y/2 \u2014 halve here to match.\n    let r = in.size.x;\n    let halfH = in.size.y * 0.5;\n    local = vec3f(in.unit.x * r, in.unit.y * r + halfH * in.unit.w, in.unit.z * r);\n  } else {\n    local = in.unit.xyz * in.size.x;\n  }\n  let world = model * vec4f(local, 1.0);\n  var out: VsOut;\n  out.pos = camera.projection * camera.view * world;\n  out.color = in.color;\n  return out;\n}\n\n@fragment\nfn fsMain(in: VsOut) -> @location(0) vec4f {\n  return vec4f(in.color.rgb, in.color.a * SOLID_ALPHA);\n}\n";
+//# sourceMappingURL=physics-debug.d.ts.map

package/dist/shaders/passes/physics-debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-debug.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/physics-debug.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,yBAAyB,2kDAuDrC,CAAA"}

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/shadow.d.ts

@@ -1,2 +1,2 @@
-export declare const SHADOW_DEPTH_SHADER_WGSL = "\nstruct LightVP { viewProj: mat4x4f, };\n@group(0) @binding(0) var<uniform> lp: LightVP;\n@group(0) @binding(1) var<storage, read> skinMats: array<mat4x4f>;\n@group(0) @binding(2) var texSampler: sampler;\n@group(1) @binding(0) var diffuseTexture: texture_2d<f32>;\nstruct MaterialDiffuse { diffuse: vec4f, };\n@group(1) @binding(1) var<uniform> material: MaterialDiffuse;\n\nstruct VSOut {\n  @builtin(position) position: vec4f,\n  @location(0) uv: vec2f,\n};\n\n@vertex fn vs(@location(0) position: vec3f, @location(1) normal: vec3f, @location(2) uv: vec2f,\n  @location(3) joints0: vec4<u32>, @location(4) weights0: vec4<f32>) -> VSOut {\n  let pos4 = vec4f(position, 1.0);\n  let ws = weights0.x + weights0.y + weights0.z + weights0.w;\n  let inv = select(1.0, 1.0 / ws, ws > 0.0001);\n  let nw = select(vec4f(1.0,0.0,0.0,0.0), weights0 * inv, ws > 0.0001);\n  var sp = vec4f(0.0);\n  for (var i = 0u; i < 4u; i++) { sp += (skinMats[joints0[i]] * pos4) * nw[i]; }\n  var out: VSOut;\n  out.position = lp.viewProj * vec4f(sp.xyz, 1.0);\n  out.uv = uv;\n  return out;\n}\n\n@fragment fn fs(in: VSOut) {\n  let alpha = textureSample(diffuseTexture, texSampler, in.uv).a * material.diffuse.a;\n  if (alpha < 0.5) { discard; }\n}\n";
+export declare const SHADOW_DEPTH_SHADER_WGSL = "\n\n/** Flake size, in object-space units \u2014 MMD's are roughly centimetres. */\nconst RZ_DISSOLVE_GRAIN: f32 = 0.55;\n/** How wide the glowing front is, in threshold units. */\nconst RZ_DISSOLVE_EDGE: f32 = 0.16;\n/** What the front burns with. Emission, added after lighting and after the\n *  graph \u2014 a colour that ramps or takes a shadow reads as paint, not as heat.\n *  Above 1 on purpose: it is meant to reach the bloom pyramid. */\nconst RZ_BURN_COLOR: vec3f = vec3f(0.55, 1.85, 2.60);\n\nfn rz_dissolve_hash(p: vec3f) -> f32 {\n  let q = fract(p * 0.3183099 + vec3f(0.1, 0.2, 0.3));\n  let r = q * 17.0 * (q + 34.0);\n  return fract(r.x * r.y * r.z);\n}\n\n/** Value noise over that hash \u2014 smooth within a flake, uncorrelated between. */\nfn rz_dissolve_field(p: vec3f) -> f32 {\n  let i = floor(p);\n  let f = fract(p);\n  let u = f * f * (3.0 - 2.0 * f);\n  let c000 = rz_dissolve_hash(i);\n  let c100 = rz_dissolve_hash(i + vec3f(1.0, 0.0, 0.0));\n  let c010 = rz_dissolve_hash(i + vec3f(0.0, 1.0, 0.0));\n  let c110 = rz_dissolve_hash(i + vec3f(1.0, 1.0, 0.0));\n  let c001 = rz_dissolve_hash(i + vec3f(0.0, 0.0, 1.0));\n  let c101 = rz_dissolve_hash(i + vec3f(1.0, 0.0, 1.0));\n  let c011 = rz_dissolve_hash(i + vec3f(0.0, 1.0, 1.0));\n  let c111 = rz_dissolve_hash(i + vec3f(1.0, 1.0, 1.0));\n  let x00 = mix(c000, c100, u.x);\n  let x10 = mix(c010, c110, u.x);\n  let x01 = mix(c001, c101, u.x);\n  let x11 = mix(c011, c111, u.x);\n  return mix(mix(x00, x10, u.y), mix(x01, x11, u.y), u.z);\n}\n\n/**\n * The threshold this fragment is measured against.\n *\n * Tilted by HEIGHT so the dissolve sweeps up the body instead of arriving\n * everywhere at once: a body that comes apart from the feet reads as something\n * happening TO her, and one that fades uniformly reads as an opacity slider.\n * The tilt is gentle \u2014 a third of the range \u2014 so the noise still decides which\n * flake goes when, and the sweep only decides roughly where it is.\n *\n * FEET FIRST, head last: the face is the last thing to go and the first thing\n * back, which is the order every disappearance in film is cut in. Object space\n * puts the floor at y = 0 on any PMX, so the tilt needs no rig measurement.\n */\nfn rz_dissolve_threshold(restPos: vec3f) -> f32 {\n  let n = rz_dissolve_field(restPos / RZ_DISSOLVE_GRAIN);\n  let low = 1.0 - clamp(restPos.y * 0.045, 0.0, 1.0);\n  return clamp(n * 0.68 + low * 0.32, 0.0, 1.0);\n}\n\nstruct LightVP { viewProj: mat4x4f, };\n@group(0) @binding(0) var<uniform> lp: LightVP;\n@group(0) @binding(1) var<storage, read> skinMats: array<mat4x4f>;\n@group(0) @binding(2) var texSampler: sampler;\n@group(1) @binding(0) var diffuseTexture: texture_2d<f32>;\n// The head of the material block and the one field at its tail \u2014 the same\n// reach the depth prepass takes, and for the same reason: a shadow cast by a\n// body that is no longer drawn is the tell that the vanishing is a trick.\nstruct MaterialDiffuse {\n  diffuse: vec4f,\n  _skip0: vec4f,\n  _skip1: vec4f,\n  _skip2: vec3f,\n  dissolve: f32,\n};\n@group(1) @binding(1) var<uniform> material: MaterialDiffuse;\n\nstruct VSOut {\n  @builtin(position) position: vec4f,\n  @location(0) uv: vec2f,\n  /** Bind-pose position, for the dissolve test \u2014 object space, as everywhere. */\n  @location(1) restPos: vec3f,\n};\n\n@vertex fn vs(@location(0) position: vec3f, @location(1) normal: vec3f, @location(2) uv: vec2f,\n  @location(3) joints0: vec4<u32>, @location(4) weights0: vec4<f32>) -> VSOut {\n  let pos4 = vec4f(position, 1.0);\n  let ws = weights0.x + weights0.y + weights0.z + weights0.w;\n  let inv = select(1.0, 1.0 / ws, ws > 0.0001);\n  let nw = select(vec4f(1.0,0.0,0.0,0.0), weights0 * inv, ws > 0.0001);\n  var sp = vec4f(0.0);\n  for (var i = 0u; i < 4u; i++) { sp += (skinMats[joints0[i]] * pos4) * nw[i]; }\n  var out: VSOut;\n  out.position = lp.viewProj * vec4f(sp.xyz, 1.0);\n  out.uv = uv;\n  out.restPos = position;\n  return out;\n}\n\n@fragment fn fs(in: VSOut) {\n  let alpha = textureSample(diffuseTexture, texSampler, in.uv).a * material.diffuse.a;\n  if (alpha < 0.5) { discard; }\n  // The dissolve, run as the colour pass runs it. A flake that is gone stops\n  // casting: without this she leaves a whole shadow standing on the floor while\n  // her body is in the air.\n  if (material.dissolve < 0.9995 && rz_dissolve_threshold(in.restPos) > material.dissolve) { discard; }\n}\n";
 //# sourceMappingURL=shadow.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/shadow.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,wBAAwB,otCAgCpC,CAAA"}
+{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/shadow.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,wBAAwB,y1IAiDpC,CAAA"}

package/dist/shaders/passes/shadow.js

@@ -1,3 +1,4 @@
+import { DISSOLVE_WGSL } from "../materials/common";
 // Shadow map depth pass. Skinned VS + alpha-test FS (depth-only attachment, no
 // color targets): texels where diffuse-texture alpha × material alpha fall below
 // the cutoff are discarded, so lace casts lace-shaped shadows and a true veil
@@ -5,17 +6,29 @@
 // Group 1 is the main pass's per-material bind group reused as-is; only
 // bindings 0/1 are declared here (a layout may carry bindings a shader ignores).
 export const SHADOW_DEPTH_SHADER_WGSL = /* wgsl */ `
+${DISSOLVE_WGSL}
 struct LightVP { viewProj: mat4x4f, };
 @group(0) @binding(0) var<uniform> lp: LightVP;
 @group(0) @binding(1) var<storage, read> skinMats: array<mat4x4f>;
 @group(0) @binding(2) var texSampler: sampler;
 @group(1) @binding(0) var diffuseTexture: texture_2d<f32>;
-struct MaterialDiffuse { diffuse: vec4f, };
+// The head of the material block and the one field at its tail — the same
+// reach the depth prepass takes, and for the same reason: a shadow cast by a
+// body that is no longer drawn is the tell that the vanishing is a trick.
+struct MaterialDiffuse {
+  diffuse: vec4f,
+  _skip0: vec4f,
+  _skip1: vec4f,
+  _skip2: vec3f,
+  dissolve: f32,
+};
 @group(1) @binding(1) var<uniform> material: MaterialDiffuse;
 
 struct VSOut {
   @builtin(position) position: vec4f,
   @location(0) uv: vec2f,
+  /** Bind-pose position, for the dissolve test — object space, as everywhere. */
+  @location(1) restPos: vec3f,
 };
 
 @vertex fn vs(@location(0) position: vec3f, @location(1) normal: vec3f, @location(2) uv: vec2f,
@@ -29,11 +42,16 @@ struct VSOut {
   var out: VSOut;
   out.position = lp.viewProj * vec4f(sp.xyz, 1.0);
   out.uv = uv;
+  out.restPos = position;
   return out;
 }
 
 @fragment fn fs(in: VSOut) {
   let alpha = textureSample(diffuseTexture, texSampler, in.uv).a * material.diffuse.a;
   if (alpha < 0.5) { discard; }
+  // The dissolve, run as the colour pass runs it. A flake that is gone stops
+  // casting: without this she leaves a whole shadow standing on the floor while
+  // her body is in the air.
+  if (material.dissolve < 0.9995 && rz_dissolve_threshold(in.restPos) > material.dissolve) { discard; }
 }
 `;

package/dist/vmd-writer.d.ts

@@ -17,12 +17,17 @@ export declare class VMDWriter {
     /**
      * A camera VMD: the shot's own file, with no model motion in it.
      *
-     * Bone and morph counts are written as zero rather than omitted — the camera
-     * block sits after them in the format, so a reader walking the file in order
-     * (including this package's own parseCamera) has to pass through both to
-     * reach it. Light, self-shadow and IK blocks are left off entirely; every
-     * reader bounds-checks past the camera block, and MMD is happy with a file
-     * that simply ends there.
+     * Every section count is written, including the empty ones. The format is
+     * positional, so a reader reaches each block by walking the counts before it —
+     * bone and morph to arrive at the camera block, and light, self-shadow and IK
+     * to leave it cleanly.
+     *
+     * The trailing three used to be omitted, on the theory that every reader
+     * bounds-checks past the camera block. They do not. This file type is
+     * カメラ・照明 — camera AND lighting — so MMD looks for the light block exactly
+     * where the file used to stop, read past the end, and lit the scene from
+     * whatever it found there. It reached users as a stray coloured light on a
+     * camera-only export.
      *
      * `frames` is sorted by frame on the way out: CameraAnimation binary-searches
      * the track it loads, and an out-of-order file would sample wrong rather than

package/dist/vmd-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vmd-writer.d.ts","sourceRoot":"","sources":["../src/vmd-writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAmC,MAAM,aAAa,CAAA;AAC5E,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAsDhF;;;;;;;;8CAQ8C;AAC9C,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE3D,qBAAa,SAAS;IACpB,KAAK,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,WAAW;IAiIjF;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,WAAW;CA2CnD"}
+{"version":3,"file":"vmd-writer.d.ts","sourceRoot":"","sources":["../src/vmd-writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAmC,MAAM,aAAa,CAAA;AAC5E,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAsDhF;;;;;;;;8CAQ8C;AAC9C,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE3D,qBAAa,SAAS;IACpB,KAAK,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,WAAW;IA0IjF;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,WAAW;CAiDnD"}

package/dist/vmd-writer.js

@@ -90,10 +90,17 @@ export class VMDWriter {
             MODEL_NAME_SIZE +
             4 + totalBoneFrames * BONE_FRAME_SIZE +
             4 + totalMorphFrames * MORPH_FRAME_SIZE +
-            // Camera, light and self-shadow counts, then the IK block. Written only
-            // when there is IK state to carry: a plain motion stays byte-identical to
-            // what this writer produced before.
-            (ikFrames.length > 0 ? 4 * 4 + ikSize : 0);
+            // Camera, light, self-shadow and IK counts, ALWAYS — 16 bytes even when
+            // every one of them is zero.
+            //
+            // A VMD's sections are positional: a reader reaches each block by walking
+            // every count before it. Writing these only when there was IK state to
+            // carry left an ordinary motion ending right after the morph block, so
+            // anything looking for the sections that follow read past the end of the
+            // file and took whatever it found. MMD's own motion files carry all five
+            // counts unconditionally; so do ours now.
+            4 * 4 +
+            ikSize;
         const buffer = new ArrayBuffer(size);
         const view = new DataView(buffer);
         let offset = 0;
@@ -150,13 +157,14 @@ export class VMDWriter {
                 offset += 4;
             }
         }
+        // Empty camera, light and self-shadow blocks, then the IK count — written
+        // whether or not there is IK state, so the file always ends on a complete
+        // section table.
+        for (let i = 0; i < 3; i++, offset += 4)
+            view.setUint32(offset, 0, true);
+        view.setUint32(offset, ikFrames.length, true);
+        offset += 4;
         if (ikFrames.length > 0) {
-            // Empty camera, light and self-shadow blocks — a reader walking the file
-            // in order has to pass through them to reach the IK block.
-            for (let i = 0; i < 3; i++, offset += 4)
-                view.setUint32(offset, 0, true);
-            view.setUint32(offset, ikFrames.length, true);
-            offset += 4;
             for (const [frame, states] of ikFrames) {
                 view.setUint32(offset, frame, true);
                 offset += 4;
@@ -176,12 +184,17 @@ export class VMDWriter {
     /**
      * A camera VMD: the shot's own file, with no model motion in it.
      *
-     * Bone and morph counts are written as zero rather than omitted — the camera
-     * block sits after them in the format, so a reader walking the file in order
-     * (including this package's own parseCamera) has to pass through both to
-     * reach it. Light, self-shadow and IK blocks are left off entirely; every
-     * reader bounds-checks past the camera block, and MMD is happy with a file
-     * that simply ends there.
+     * Every section count is written, including the empty ones. The format is
+     * positional, so a reader reaches each block by walking the counts before it —
+     * bone and morph to arrive at the camera block, and light, self-shadow and IK
+     * to leave it cleanly.
+     *
+     * The trailing three used to be omitted, on the theory that every reader
+     * bounds-checks past the camera block. They do not. This file type is
+     * カメラ・照明 — camera AND lighting — so MMD looks for the light block exactly
+     * where the file used to stop, read past the end, and lit the scene from
+     * whatever it found there. It reached users as a stray coloured light on a
+     * camera-only export.
      *
      * `frames` is sorted by frame on the way out: CameraAnimation binary-searches
      * the track it loads, and an out-of-order file would sample wrong rather than
@@ -189,7 +202,7 @@ export class VMDWriter {
      */
     writeCamera(frames) {
         const sorted = [...frames].sort((a, b) => a.frame - b.frame);
-        const size = HEADER_SIZE + MODEL_NAME_SIZE + 4 + 4 + 4 + sorted.length * CAMERA_FRAME_SIZE;
+        const size = HEADER_SIZE + MODEL_NAME_SIZE + 4 + 4 + 4 + sorted.length * CAMERA_FRAME_SIZE + 4 * 3;
         const buffer = new ArrayBuffer(size);
         const view = new DataView(buffer);
         let offset = 0;
@@ -234,6 +247,11 @@ export class VMDWriter {
             view.setUint8(offset, 0); // 0 = perspective
             offset += 1;
         }
+        // Light, self-shadow and IK/display counts. See the note above: the light
+        // block begins here, and leaving it off is what lit MMD from past the end
+        // of the file.
+        for (let i = 0; i < 3; i++, offset += 4)
+            view.setUint32(offset, 0, true);
         return buffer;
     }
 }

package/package.json

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

@@ -666,12 +666,40 @@ interface PickDrawCall {
   bindGroup: GPUBindGroup
 }
 
+/**
+ * A repeating dissolve, in seconds within one cycle.
+ *
+ * Four moments rather than a duration and a delay: every one of them is a thing
+ * you can see happen, and an author tuning this is watching for exactly those
+ * four frames.
+ */
+export interface DissolveCycle {
+  period: number
+  /** She starts to come apart. */
+  breakAt: number
+  /** Fully gone. */
+  hiddenAt: number
+  /** She starts to come back. */
+  backAt: number
+  /** Whole again. */
+  doneAt: number
+}
+
 interface ModelInstance {
   name: string
   /** This model's id in the id attachment — 1-based, so 0 stays "nothing".
    *  The pick pass has always minted it; the cast carries it now too, so an
    *  effect can compare what it reads out of the id buffer against a subject. */
   objectId: number
+  /** How much of this model is still THERE: 1 whole, 0 gone. Written into every
+   *  material's uniform (see setModelDissolve) and mirrored into the cast, so
+   *  the material shell can take her apart and an effect can draw what is
+   *  leaving — both from one number rather than two clocks that must agree. */
+  dissolve: number
+  /** Every material's uniform buffer, in draw order. Kept because a dissolve
+   *  writes ONE float into each of them and needs no other reason to hold a
+   *  block: the whole 16-float copy exists only for materials that morph. */
+  materialUniformBuffers: GPUBuffer[]
   model: Model
   basePath: string
   assetReader: AssetReader
@@ -1595,6 +1623,8 @@ export class Engine {
    *  every frame. */
   private fieldClockScratch = new Float32Array(4)
   /** Material parameters driven by the scene clock — see setStyleParamTrack. */
+  /** Repeating dissolves, by model name — see setModelDissolveCycle. */
+  private dissolveCycles = new Map<string, DissolveCycle>()
   private paramTracks = new Map<
     string,
     { modelName: string; groupId: string; paramId: string; keys: ParamKey[]; last: ParamValue | null }
@@ -8662,6 +8692,8 @@ export class Engine {
       materialToGroup: new Map(),
       styleGroupGen: new Map(),
       objectId: this.modelInstances.size + 1,
+      dissolve: 1,
+      materialUniformBuffers: [],
       cullModelIndex: 0,
       // Seeded false: the first skin-matrix upload decides it, and until then the
       // sphere path is the safe answer (it never culls something it should not).
@@ -9069,6 +9101,7 @@ export class Engine {
         modelId,
       )
       inst.gpuBuffers.push(materialUniformBuffer)
+      inst.materialUniformBuffers.push(materialUniformBuffer)
       if (morphedMaterials.has(pmxMaterialIndex)) {
         const base = this.materialUniformData(mat, sphereMode, headBoneIndex, materialId, modelId)
         morphTargets.push({
@@ -9225,6 +9258,10 @@ export class Engine {
     // bound and the indirect-draw path is untouched.
     data[13] = materialId
     data[14] = objectId
+    // 15 is the last of that padding: how much of this material is there. ONE,
+    // not zero — the default has to be "whole", or every model would load
+    // already gone.
+    data[15] = 1
     return data
   }
 
@@ -10329,6 +10366,7 @@ export class Engine {
     // and a grid stepped after them is one frame stale in everything that used it.
     // Material parameters on the scene clock, before anything reads their
     // uniforms this frame.
+    this.evaluateDissolveCycles()
     this.evaluateParamTracks()
     this.stepSim(encoder, deltaTime)
     this.stepParticles(encoder, deltaTime)
@@ -10730,6 +10768,102 @@ export class Engine {
     return true
   }
 
+  /**
+   * How much of a model is still THERE: 1 whole, 0 gone.
+   *
+   * The instant tier, like setStyleParam — one float per material, no recompile,
+   * no pipeline touched. What it drives is a THRESHOLD, not an opacity: the
+   * material shell throws away every flake whose object-space threshold has
+   * passed, and lights the ones about to go. So a model at 0.5 is not
+   * half-transparent, it is half GONE, which is the difference between a fade
+   * and a disintegration.
+   *
+   * Written into the depth prepass's copy of the same test as well, so the
+   * flakes stop claiming depth the moment they stop being drawn — see
+   * DISSOLVE_WGSL for why that has to be one implementation.
+   *
+   * Mirrored into the cast, so an effect can read rzSubject(i).dissolve and draw
+   * the sparks that leave her in step with the body they came off. That is the
+   * whole reason this lives on the model rather than in an effect's uniform: the
+   * material pass runs long before any effect, and only the engine sees both.
+   */
+  setModelDissolve(modelName: string, value: number): boolean {
+    const inst = this.modelInstances.get(modelName)
+    if (!inst) return false
+    const v = Math.min(1, Math.max(0, value))
+    if (inst.dissolve === v) return true
+    inst.dissolve = v
+    // Offset 60: the sixteenth float of MaterialUniforms. One four-byte write
+    // per material rather than the whole block — the block only exists as a
+    // copy for materials that morph.
+    const one = new Float32Array([v])
+    for (const buffer of inst.materialUniformBuffers) {
+      this.device.queue.writeBuffer(buffer, 60, one)
+    }
+    // The morph path rebuilds a material's block from its `base` copy and
+    // uploads it whole, which would put the old value straight back. Patching
+    // `base` is what keeps a face that is morphing while she dissolves from
+    // coming back solid for those frames; `last` is cleared so the next
+    // comparison genuinely re-uploads rather than deciding nothing moved.
+    if (inst.materialMorphTargets) {
+      for (const t of inst.materialMorphTargets) {
+        t.base[15] = v
+        t.last[15] = Number.NaN
+      }
+    }
+    return true
+  }
+
+  /**
+   * A repeating dissolve, on the scene clock.
+   *
+   * The alternative was a host calling setModelDissolve every frame, and it is
+   * the wrong shape twice: an exported take stepped at another rate would land
+   * on different values than the preview did, and the effect drawing the sparks
+   * would be reading a number some other clock wrote. Here the engine samples it
+   * where it samples everything else time-driven, so a take reproduces exactly
+   * and rzSubject().dissolve is the same value the material shell used on that
+   * very frame.
+   *
+   * The five numbers are seconds within one cycle: when she starts to go, when
+   * she is fully gone, when she starts to come back, and when she is whole. The
+   * gaps between them are the timing, and the hold between the middle two is how
+   * long she is away.
+   */
+  setModelDissolveCycle(modelName: string, cycle: DissolveCycle | null): boolean {
+    if (!this.modelInstances.has(modelName)) return false
+    if (!cycle) {
+      if (this.dissolveCycles.delete(modelName)) this.setModelDissolve(modelName, 1)
+      return true
+    }
+    this.dissolveCycles.set(modelName, cycle)
+    return true
+  }
+
+  /** Every dissolve cycle, at the current scene clock. Once per frame, before
+   *  the cast is written and long before any effect reads it. */
+  private evaluateDissolveCycles(): void {
+    if (this.dissolveCycles.size === 0) return
+    for (const [name, c] of this.dissolveCycles) {
+      const period = Math.max(c.period, 1e-3)
+      const t = this.sceneClock - Math.floor(this.sceneClock / period) * period
+      let v = 1
+      if (t >= c.breakAt && t < c.hiddenAt) {
+        v = 1 - (t - c.breakAt) / Math.max(c.hiddenAt - c.breakAt, 1e-4)
+      } else if (t >= c.hiddenAt && t < c.backAt) {
+        v = 0
+      } else if (t >= c.backAt && t < c.doneAt) {
+        v = (t - c.backAt) / Math.max(c.doneAt - c.backAt, 1e-4)
+      }
+      this.setModelDissolve(name, v)
+    }
+  }
+
+  /** What setModelDissolve last set, or 1 for a model that has never dissolved. */
+  getModelDissolve(modelName: string): number {
+    return this.modelInstances.get(modelName)?.dissolve ?? 1
+  }
+
   // Materials claimed by the model's currently-installed groups (for upsert/remove paths;
   // applyStyleGroups derives claims from its input array instead).
   private currentClaims(inst: ModelInstance): Map<string, string> {
@@ -11494,7 +11628,11 @@ export class Engine {
     cd[b] = px
     cd[b + 1] = floorY
     cd[b + 2] = pz
-    cd[b + 3] = 1
+    // The root vec4's w, a constant 1 until now: how much of this subject is
+    // still there. An effect that draws what is LEAVING her needs to know how
+    // far along she is, and reading it here is what keeps the sparks in step
+    // with the body without a second clock to agree with.
+    cd[b + 3] = inst.dissolve
     cd[b + 4] = px
     cd[b + 5] = py
     cd[b + 6] = pz

package/src/graph/slots.ts

@@ -8,7 +8,7 @@
 // See docs/style-groups-spec.md §5, §7.
 
 import { NODES_WGSL } from "../shaders/materials/nodes"
-import { COMMON_MATERIAL_PRELUDE_WGSL, commonFsOutWgsl } from "../shaders/materials/common"
+import { COMMON_MATERIAL_PRELUDE_WGSL, DISSOLVE_WGSL, commonFsOutWgsl } from "../shaders/materials/common"
 import { sceneIdWriteWgsl } from "../shaders/passes/scene-contract"
 import type { AlphaMode, RenderClass } from "./render-class"
 
@@ -65,7 +65,16 @@ const STYLE_UNIFORMS_WGSL = `struct StyleUniforms { p: array<vec4f, 16> };
 `
 
 function decls(renderClass: RenderClass, alphaMode: AlphaMode): string {
-  return (alphaMode === "hashed" ? HASHED_ALPHA_DECLS : "") + (renderClass === "hair" ? HAIR_OVER_EYES_DECL : "")
+  // The dissolve helpers are ALWAYS declared, unlike the hashed-alpha ones.
+  // They cost nothing on a material that never dissolves — the branch that
+  // calls them is uniform across a draw and folds away — and making them
+  // conditional would mean deciding at COMPILE time which materials may ever
+  // come apart, which is the one thing a runtime value must not need.
+  return (
+    DISSOLVE_WGSL +
+    (alphaMode === "hashed" ? HASHED_ALPHA_DECLS : "") +
+    (renderClass === "hair" ? HAIR_OVER_EYES_DECL : "")
+  )
 }
 
 // fs() header up to and including the graph body's context locals. Composed so the
@@ -92,6 +101,25 @@ function prelude(renderClass: RenderClass, alphaMode: AlphaMode): string {
   let alpha = material.alpha * tex_s.a;
 ${discard}
 
+  // ── Dissolve ──
+  //
+  // A fragment is either THERE or it is not: the flake is thrown away rather
+  // than faded. A fade would be an opacity slider — she would go see-through
+  // and you would read the wall through her hair — while a threshold takes her
+  // apart in pieces, which is the thing being asked for. The depth prepass runs
+  // this identical test (rz_dissolve_threshold, shared), so depth and colour
+  // agree about which pieces are gone.
+  //
+  // The surviving edge glows: fragments within RZ_DISSOLVE_EDGE of the front
+  // are the ones about to go, and lighting them is what makes the boundary read
+  // as burning away rather than as a stencil moving over her.
+  var rz_burn = 0.0;
+  if (material.dissolve < 0.9995) {
+    let rz_t = rz_dissolve_threshold(input.restPos);
+    if (rz_t > material.dissolve) { discard; }
+    rz_burn = smoothstep(material.dissolve - RZ_DISSOLVE_EDGE, material.dissolve, rz_t);
+  }
+
   var n = safe_normal(input.normal);
   let v = normalize(camera.viewPos - input.worldPos);${flip}
 ${gate}
@@ -132,18 +160,23 @@ function epilogue(renderClass: RenderClass, alphaMode: AlphaMode): string {
   const LIT = ` + rzLightsDiffuse(input.worldPos, n) * albedo`
   const ALBEDO = `  let albedo = tex_color;
 `
+  // The dissolve's burning edge, ADDED after the graph and after the lights —
+  // it is emission, not a surface colour, so nothing may ramp or shadow it. Zero
+  // on every fragment of every material that is not dissolving, which is what
+  // keeps this out of the way of a scene that never uses it.
+  const BURN = ` + RZ_BURN_COLOR * rz_burn`
   if (renderClass === "hair") {
     return `${ALBEDO}  var outAlpha = ${alphaBase};
   if (IS_OVER_EYES) { outAlpha = ${alphaBase} * 0.25; }
 
   var out: FSOut;
-  out.color = vec4f(final_color${LIT}, outAlpha);
+  out.color = vec4f(final_color${LIT}${BURN}, outAlpha);
   out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
 ${ID_WRITE}  return out;
 `
   }
   return `${ALBEDO}  var out: FSOut;
-  out.color = vec4f(final_color${LIT}, ${alphaBase});
+  out.color = vec4f(final_color${LIT}${BURN}, ${alphaBase});
   out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
 ${ID_WRITE}  return out;
 `

package/src/index.ts

@@ -17,6 +17,7 @@ export {
   type GizmoDragEvent,
   type GizmoDragCallback,
   type GizmoDragKind,
+  type DissolveCycle,
   type EffectParamValue,
   type EffectResult,
   type CullDiagnostics,

package/src/shaders/cast-api.ts

@@ -45,6 +45,16 @@ struct RzSubject {
   center: vec3f,
   /** Bounding sphere: xyz centre, w radius. Deliberately generous — cull with it. */
   bounds: vec4f,
+  /**
+   * How much of this character is still THERE: 1 whole, 0 gone.
+   *
+   * What setModelDissolve last set on them, which the material pass has already
+   * acted on by the time an effect runs — so an effect drawing what LEAVES a
+   * dissolving body (sparks, ash, a ghost) reads the same number the body was
+   * taken apart with, rather than keeping a clock of its own and hoping the two
+   * agree. 1 on a scene that never dissolves anybody.
+   */
+  dissolve: f32,
   /** False past the end of the cast, and every field is then zero. */
   valid: bool,
 }
@@ -73,6 +83,7 @@ fn rzSubject(i: i32) -> RzSubject {
   if (!s.valid) { return s; }
   let b = i * 3;
   s.root = _rzCast[b].xyz;
+  s.dissolve = _rzCast[b].w;
   s.center = _rzCast[b + 1].xyz;
   s.bounds = _rzCast[b + 2];
   return s;