reze-engine 0.39.0 → 0.41.0

package/dist/engine.js

@@ -5,7 +5,6 @@ import { MORPH_COMPUTE_WGSL } from "./shaders/passes/morph";
 import { decodeTga } from "./tga-loader";
 import { VMDLoader } from "./vmd-loader";
 import { CameraAnimation } from "./camera-animation";
-import { ParticleSystem } from "./particles";
 import { PmxLoader } from "./pmx-loader";
 import { RezePhysics } from "./physics";
 import { createFetchAssetReader, createFileMapAssetReader, deriveBasePathFromPmxPath, fileListToMap, findFirstPmxFileInList, joinAssetPath, normalizeAssetPath, } from "./asset-reader";
@@ -145,6 +144,16 @@ export const DEFAULT_BLOOM_OPTIONS = {
     intensity: 0.05,
     clamp: 0.0,
 };
+export const DEFAULT_DEPTH_OF_FIELD_OPTIONS = {
+    enabled: false,
+    focusMode: "auto",
+    focusDistance: 25,
+    focusRange: 2,
+    aperture: 1,
+    maxBlurRadius: 18,
+    bladeCount: 6,
+    quality: "balanced",
+};
 // Matches the reference Blender project: Filmic view, Medium High Contrast look,
 // exposure 0.3, gamma 1.0, sRGB display, no curves.
 export const DEFAULT_VIEW_TRANSFORM = {
@@ -287,22 +296,29 @@ export class Engine {
         // the fragment shader and treats missing dst.a as 1, so the blend math is
         // unchanged).
         this.hdrFormat = "rgba16float";
-        /** One-shot particle emissions (emitParticles); lazily built on first emit. */
-        this.particles = null;
+        this.depthOfField = { ...DEFAULT_DEPTH_OF_FIELD_OPTIONS };
+        this.dofUniformData = new Float32Array(12);
+        this.dofFocusScratch = new Vec3(0, 0, 0);
+        /** Depth-only view of the scene's MSAA depth buffer, read by the DoF gather. */
+        this.depthReadView = null;
         // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-        this.compositeUniformData = new Float32Array(40);
+        // 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.
+        this.compositeUniformData = new Float32Array(44);
         /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
         this.backgroundColor = null;
         // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
         this.backdropEquirectTexture = null;
         this.backdropEquirectView = null;
-        // User WGSL background effect (background mode 3, setBackgroundEffect). The
-        // composite pipelines are REBUILT with the user code injected; params live in
-        // their own uniform buffer so setBackgroundEffectParam is a write, not a
+        // The scene's user WGSL effect (setEffect). ONE per scene, mounted under the
+        // scene, over it, or both — whichever of background()/foreground() the code
+        // defines. The composite pipelines are REBUILT with the user code injected;
+        // params live in their own uniform buffer so setEffectParam is a write, not a
         // recompile (the same instant tier as setStyleParam).
-        this.backgroundEffect = null;
-        /** time=0 origin for the active effect — reset each setBackgroundEffect. */
-        this.bgEffectEpochMs = 0;
+        this.effect = null;
+        /** time=0 origin for the active effect — reset each setEffect. */
+        this.effectEpochMs = 0;
         this.compositeBloomView = null;
         this.bloomBlitUniformData = new Float32Array(4);
         this.bloomUpsampleUniformData = new Float32Array(4);
@@ -725,10 +741,10 @@ export class Engine {
         u[8] = bg?.x ?? 0;
         u[9] = bg?.y ?? 0;
         u[10] = bg?.z ?? 0;
-        // Base-layer mode; a user effect is a separate LAYER flagged at u[25] and
-        // over-composited onto whichever base is active.
+        // 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.
         u[11] = this.backdropEquirectView ? 2 : bg ? 1 : 0;
-        u[25] = this.backgroundEffect ? 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,
@@ -774,7 +790,7 @@ export class Engine {
         this.outlineEnabled = on;
     }
     rebuildCompositeBindGroup() {
-        if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView)
+        if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView || !this.depthReadView)
             return;
         this.compositeBindGroup = this.device.createBindGroup({
             label: "composite bind group",
@@ -787,7 +803,9 @@ export class Engine {
                 { binding: 4, resource: this.maskResolveView },
                 { binding: 5, resource: this.filmicLutView },
                 { binding: 6, resource: this.backdropEquirectView ?? this.fallbackEquirectView },
-                { binding: 7, resource: { buffer: this.backgroundEffect?.paramsBuffer ?? this.bgParamsDummyBuffer } },
+                { binding: 7, resource: { buffer: this.effect?.paramsBuffer ?? this.bgParamsDummyBuffer } },
+                { binding: 8, resource: this.depthReadView },
+                { binding: 9, resource: { buffer: this.dofUniformBuffer } },
             ],
         });
     }
@@ -850,42 +868,71 @@ export class Engine {
         });
     }
     /**
-     * Install a WGSL background effect (shadertoy-style) as a LAYER between the
-     * base background and the scene: rendered per-pixel in the composite pass and
-     * over-composited onto whichever base is active (solid color, 360 equirect,
-     * or transparency) — its alpha lets the base show through, so a starfield is
-     * stars over the user's background color. Display-space: never affects
-     * lighting, bloom, or tonemapping, and is captured by offline export like any
-     * background.
-     *
-     * `wgsl` must define:
+     * Install the scene's WGSL effect (shadertoy-style), rendered per-pixel in the
+     * composite pass. ONE effect per scene, and the code says where it mounts by
+     * which of these it defines — either, or both in one file:
      *
      *     fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f
+     *     fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f
+     *
+     * `background` is a LAYER between the base background and the scene,
+     * over-composited onto whichever base is active (solid color, 360 equirect, or
+     * transparency) — its alpha lets the base show through, so a starfield is
+     * stars over the user's background color. `foreground` composites over the
+     * finished frame instead, which is where rain, snow, petals and fog live, and
+     * is handed `depth`: the camera-space distance in metres of whatever the scene
+     * drew at that pixel (the far plane where it drew nothing). Compare a
+     * particle's own distance against it and the model occludes it; fog just reads
+     * it, since fog's alpha IS a function of distance.
      *
-     * where `ray` is the pixel's normalized world-space view direction (LH, +Z
-     * forward — what the skybox samples by), `uv` is 0..1 bottom-left origin,
-     * `time` is seconds since apply, and `bgResolution()` gives the canvas size.
-     * Return sRGB + alpha. Declared `params` arrive as `params.<name>` (number →
-     * f32, Vec3 → vec3f) and are later tweaked without recompiling via
-     * setBackgroundEffectParam.
+     * `ray` is the pixel's normalized world-space view direction (LH, +Z forward —
+     * what the skybox samples by), `uv` is 0..1 bottom-left origin, `time` is
+     * seconds since apply, and `bgResolution()` gives the canvas size. Return sRGB
+     * + alpha; alpha is the only "how much does this replace" control there is.
+     * Declared `params` arrive as `params.<name>` (number → f32, Vec3 → vec3f),
+     * shared by both mounts, and are later tweaked without recompiling via
+     * setEffectParam.
      *
-     * Compiles off the hot path (async pipelines): on failure the previous
-     * background is KEPT and diagnostics are returned with line numbers relative
-     * to the user's WGSL. Pass null to remove the effect.
+     * Both mounts are display-space: neither affects lighting, bloom or
+     * tonemapping, and both are captured by offline export. A foreground makes the
+     * scene pass STORE its depth buffer (it otherwise discards it into tile
+     * memory) for as long as one is installed.
+     *
+     * Compiles off the hot path (async pipelines): on failure the previous effect
+     * is KEPT and diagnostics are returned with line numbers relative to the
+     * user's WGSL. Pass null to remove the effect.
      */
-    async setBackgroundEffect(wgsl, params) {
+    async setEffect(wgsl, params) {
+        const noMounts = { background: false, foreground: false };
         if (!this.device)
-            return { ok: false, diagnostics: ["setBackgroundEffect requires init() to have run"] };
+            return { ok: false, diagnostics: ["setEffect requires init() to have run"], mounts: noMounts };
         if (wgsl === null) {
-            this.backgroundEffect?.paramsBuffer?.destroy();
-            this.backgroundEffect = null;
+            this.effect?.paramsBuffer?.destroy();
+            this.effect = null;
             const module = this.device.createShaderModule({ label: "composite shader", code: buildCompositeShader(null) });
             this.compositePipelineIdentity = this.makeCompositePipeline(module, false, "composite pipeline (gamma=1)");
             this.compositePipelineGamma = this.makeCompositePipeline(module, true, "composite pipeline (gamma!=1)");
             this.rebuildCompositeBindGroup();
             this.writeCompositeViewUniforms();
-            return { ok: true, diagnostics: [] };
+            return { ok: true, diagnostics: [], mounts: noMounts };
+        }
+        // ── Which mounts did the author ask for? A declaration, not a setting: the
+        // entry points present in the source are the ones compiled in. Matching the
+        // `fn` keyword is enough to be safe against a `foreground` LOCAL or a call
+        // to one — those never follow `fn`.
+        const hasBackground = /\bfn\s+background\s*\(/.test(wgsl);
+        const hasForeground = /\bfn\s+foreground\s*\(/.test(wgsl);
+        if (!hasBackground && !hasForeground) {
+            return {
+                ok: false,
+                diagnostics: [
+                    "an effect must define fn background(ray: vec3f, uv: vec2f, time: f32) -> vec4f " +
+                        "or fn foreground(ray: vec3f, uv: vec2f, time: f32, depth: f32) -> vec4f (or both)",
+                ],
+                mounts: noMounts,
+            };
         }
+        const mounts = { background: hasBackground, foreground: hasForeground };
         // ── Params: codegen a WGSL struct and mirror its uniform layout on the CPU.
         // Fields are emitted in declaration order; offsets follow WGSL's natural
         // uniform rules (f32 align 4, vec3f align 16 size 12), computed identically
@@ -896,7 +943,7 @@ export class Engine {
         let cursor = 0;
         for (const [name, value] of entries) {
             if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
-                return { ok: false, diagnostics: [`invalid param name "${name}" (must be a WGSL identifier)`] };
+                return { ok: false, diagnostics: [`invalid param name "${name}" (must be a WGSL identifier)`], mounts };
             }
             const isVec = typeof value !== "number";
             const align = isVec ? 16 : 4;
@@ -917,14 +964,14 @@ export class Engine {
             }
         }
         const paramsDecl = entries.length
-            ? `struct BgParams {\n${fields.join("\n")}\n}\n@group(0) @binding(7) var<uniform> params: BgParams;\n`
+            ? `struct EffectParams {\n${fields.join("\n")}\n}\n@group(0) @binding(7) var<uniform> params: EffectParams;\n`
             : "";
         // ── Compile with validation captured, not thrown at the console. Line
         // numbers in diagnostics are rebased to the USER's source.
-        const source = buildCompositeShader({ wgsl, paramsDecl });
+        const source = buildCompositeShader({ wgsl, paramsDecl, hasBackground, hasForeground });
         const userLineOffset = source.slice(0, source.indexOf(wgsl)).split("\n").length - 1;
         this.device.pushErrorScope("validation");
-        const module = this.device.createShaderModule({ label: "composite shader (bg effect)", code: source });
+        const module = this.device.createShaderModule({ label: "composite shader (effect)", code: source });
         const info = await module.getCompilationInfo();
         const scopeErr = await this.device.popErrorScope();
         const diagnostics = info.messages
@@ -933,7 +980,7 @@ export class Engine {
         if (diagnostics.length === 0 && scopeErr)
             diagnostics.push(scopeErr.message);
         if (diagnostics.length > 0)
-            return { ok: false, diagnostics };
+            return { ok: false, diagnostics, mounts };
         let identity;
         let gamma;
         try {
@@ -950,36 +997,40 @@ export class Engine {
                 primitive: { topology: "triangle-list" },
             });
             [identity, gamma] = await Promise.all([
-                make(false, "composite pipeline (bg effect, gamma=1)"),
-                make(true, "composite pipeline (bg effect, gamma!=1)"),
+                make(false, "composite pipeline (effect, gamma=1)"),
+                make(true, "composite pipeline (effect, gamma!=1)"),
             ]);
         }
         catch (e) {
-            return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] };
+            return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)], mounts };
         }
         // ── Swap — only now does the old effect (and its params buffer) go away.
-        this.backgroundEffect?.paramsBuffer?.destroy();
+        this.effect?.paramsBuffer?.destroy();
         let paramsBuffer = null;
         if (entries.length) {
             paramsBuffer = this.device.createBuffer({
-                label: "bg effect params",
+                label: "effect params",
                 size: paramsData.byteLength,
                 usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
             });
             this.device.queue.writeBuffer(paramsBuffer, 0, paramsData);
         }
-        this.backgroundEffect = { wgsl, paramLayout: layout, paramsBuffer, paramsData };
+        this.effect = { wgsl, paramLayout: layout, paramsBuffer, paramsData, hasBackground, hasForeground };
         this.compositePipelineIdentity = identity;
         this.compositePipelineGamma = gamma;
-        this.bgEffectEpochMs = performance.now();
+        this.effectEpochMs = performance.now();
         this.rebuildCompositeBindGroup();
         this.writeCompositeViewUniforms();
-        return { ok: true, diagnostics: [] };
+        return { ok: true, diagnostics: [], mounts };
+    }
+    /** Which mounts the installed effect declared. Both false when none is set. */
+    getEffectMounts() {
+        return { background: this.effect?.hasBackground ?? false, foreground: this.effect?.hasForeground ?? false };
     }
-    /** Write one background-effect param (declared at setBackgroundEffect) — a
-     *  uniform write, no recompile; the instant tier, like setStyleParam. */
-    setBackgroundEffectParam(name, value) {
-        const fx = this.backgroundEffect;
+    /** Write one effect param (declared at setEffect) — a uniform write, no
+     *  recompile; the instant tier, like setStyleParam. */
+    setEffectParam(name, value) {
+        const fx = this.effect;
         if (!fx || !fx.paramsBuffer)
             return;
         const slot = fx.paramLayout.get(name);
@@ -995,6 +1046,92 @@ export class Engine {
         this.device.queue.writeBuffer(fx.paramsBuffer, 0, fx.paramsData);
     }
     /** Patch bloom; GPU uniforms update immediately if `init()` has run. */
+    /** Camera depth of field (see DepthOfFieldOptions). Free while disabled —
+     *  the scene pass only stores its depth buffer on frames the gather reads. */
+    setDepthOfField(patch) {
+        this.depthOfField = { ...this.depthOfField, ...patch };
+        if (!this.device || !this.dofUniformBuffer)
+            return;
+        if (this.depthOfField.enabled) {
+            this.writeDepthOfFieldUniforms();
+        }
+        else {
+            // One last write so the shader's uniform branch reads a clean zero.
+            this.dofUniformData[0] = 0;
+            this.device.queue.writeBuffer(this.dofUniformBuffer, 0, this.dofUniformData);
+        }
+    }
+    getDepthOfField() {
+        return { ...this.depthOfField };
+    }
+    /** Auto-focus target: the camera-space depth span of the first visible
+     *  character's bones. Focus sits at the span's midpoint; the range covers the
+     *  span plus a margin for what bones don't reach (shoes, hair, cloth). */
+    getModelBodyFocus() {
+        if (!this.camera)
+            return null;
+        const view = this.camera.getViewMatrix().values;
+        for (const inst of this.modelInstances.values()) {
+            if (!inst.model.visible || inst.isStage)
+                continue;
+            const model = inst.model;
+            const matrices = model.getWorldMatrices();
+            if (matrices.length === 0)
+                continue;
+            const scale = model.scale;
+            const local = this.dofFocusScratch;
+            let minDepth = Infinity;
+            let maxDepth = -Infinity;
+            for (const matrix of matrices) {
+                const values = matrix.values;
+                // Bone matrices are model-space; apply the same root transform the
+                // renderer bakes into skinning, then take camera-space z.
+                local.setXYZ(values[12] * scale, values[13] * scale, values[14] * scale);
+                Quat.rotateVecInto(model.rotation, local, local);
+                const x = model.position.x + local.x;
+                const y = model.position.y + local.y;
+                const z = model.position.z + local.z;
+                const depth = view[2] * x + view[6] * y + view[10] * z + view[14];
+                if (!Number.isFinite(depth) || depth <= this.camera.near)
+                    continue;
+                minDepth = Math.min(minDepth, depth);
+                maxDepth = Math.max(maxDepth, depth);
+            }
+            if (Number.isFinite(minDepth) && Number.isFinite(maxDepth)) {
+                const span = Math.max(0, maxDepth - minDepth);
+                const meshMargin = Math.max(2.0, span * 0.15);
+                return { distance: (minDepth + maxDepth) * 0.5, range: Math.max(2.0, span + meshMargin) };
+            }
+        }
+        return null;
+    }
+    writeDepthOfFieldUniforms() {
+        if (!this.device || !this.dofUniformBuffer)
+            return;
+        const d = this.depthOfField;
+        const u = this.dofUniformData;
+        // `d.enabled &&`, because a foreground effect also drives this write (for
+        // projA/projB alone) and auto-focus walks every visible character's bones —
+        // work nothing would read with the gather switched off.
+        const auto = d.enabled && d.focusMode === "auto" ? this.getModelBodyFocus() : null;
+        u[0] = d.enabled ? 1 : 0;
+        u[1] = auto?.distance ?? Math.max(d.focusDistance, 0.05);
+        // In auto mode the authored range is a floor — the sharp band never cuts
+        // into the character's own depth span.
+        u[2] = Math.max(d.focusRange, auto?.range ?? 0.02, 0.02);
+        u[3] = Math.max(d.aperture, 0);
+        u[4] = Math.max(d.maxBlurRadius, 0);
+        u[5] = Math.min(12, Math.max(3, Math.round(d.bladeCount)));
+        u[6] = d.quality === "performance" ? 8 : d.quality === "cinematic" ? 24 : 16;
+        u[7] = 1; // anamorphic ratio, reserved (the shader clamps ≥ 0.25)
+        // viewZ = projB / (z − projA), the inverse of perspectiveInto's z mapping.
+        // near/far track the camera radius, so these refresh every enabled frame.
+        const near = this.camera.near;
+        const far = this.camera.far;
+        u[8] = (far + near) / (far - near);
+        u[9] = (-2 * near * far) / (far - near);
+        this.device.queue.writeBuffer(this.dofUniformBuffer, 0, u);
+    }
     setBloomOptions(patch) {
         const b = this.bloomSettings;
         if (patch.enabled !== undefined)
@@ -1794,11 +1931,18 @@ export class Engine {
         // mirroring EEVEE where bloom color/intensity are combine-stage params, not prefilter).
         this.compositeUniformBuffer = this.device.createBuffer({
             label: "composite view uniforms",
-            // 10 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
+            // 11 × vec4f: (exposure, invGamma, _, _) · (bloom tint, intensity) ·
             // (bg rgb, mode) · camera right/up/forward basis for the 360 skybox ray ·
-            // (time, _, canvas width, canvas height) for user background effects ·
-            // three grade vectors (CDL offset+contrast, power+saturation, slope+flag).
-            size: 160,
+            // (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,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.dofUniformBuffer = this.device.createBuffer({
+            label: "depth of field uniforms",
+            // 3 × vec4f — see the dofU comment in composite.ts.
+            size: 48,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
         this.bgParamsDummyBuffer = this.device.createBuffer({
@@ -1823,6 +1967,15 @@ export class Engine {
                 // User background-effect params — dummy buffer when no effect is set. The
                 // layout is explicit, so the base shader legally ignores the binding.
                 { binding: 7, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                // The scene pass's MSAA depth, depth-only aspect — read by the DoF
+                // gather. Contents are undefined while DoF is off (the scene pass
+                // discards depth then), and the shader never reads it then either.
+                {
+                    binding: 8,
+                    visibility: GPUShaderStage.FRAGMENT,
+                    texture: { sampleType: "depth", viewDimension: "2d", multisampled: true },
+                },
+                { binding: 9, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
             ],
         });
         this.fallbackEquirectTexture = this.device.createTexture({
@@ -2034,9 +2187,12 @@ export class Engine {
                 size: [width, height],
                 sampleCount: Engine.MULTISAMPLE_COUNT,
                 format: "depth24plus-stencil8",
-                usage: GPUTextureUsage.RENDER_ATTACHMENT,
+                // TEXTURE_BINDING for the DoF gather — a usage flag, not a copy; the
+                // zero-cost-when-off story lives in depthStoreOp, not here.
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
             });
             const depthTextureView = this.depthTexture.createView();
+            this.depthReadView = this.depthTexture.createView({ aspect: "depth-only" });
             // storeOp="discard" on MSAA views keeps per-sample data in Apple TBDR tile memory —
             // only the resolveTarget (hdrResolveTexture / maskResolveView) gets written to RAM.
             // With storeOp="store" Safari's Metal backend spills the full MS buffer every frame
@@ -2421,6 +2577,12 @@ export class Engine {
     hasCameraVmd() {
         return this.cameraAnimation !== null;
     }
+    /** Seconds the loaded camera VMD runs for — its last keyframe — or 0 with none
+     *  loaded. A timeline cannot draw a lane to scale without it, and the camera's
+     *  length is its own: it does not have to match any model's clip. */
+    getCameraVmdDuration() {
+        return this.cameraAnimation?.duration ?? 0;
+    }
     /** Drop the loaded camera VMD and return to orbit control. */
     clearCameraVmd() {
         this.cameraAnimation = null;
@@ -2471,24 +2633,6 @@ export class Engine {
     setCameraFov(fov) {
         this.camera.fov = fov;
     }
-    /** Fire a one-shot particle effect (see ParticleEmitOptions): "burst" scatters
-     *  glowing sparks from the given world points, "converge" condenses them onto
-     *  the points. Pair with Model.sampleSurfacePoints for dissolve/materialize
-     *  transitions shaped like the model. Stateless GPU particles — the emission
-     *  cleans itself up when it expires. */
-    emitParticles(opts) {
-        if (!this.device)
-            return;
-        if (!this.particles) {
-            this.particles = new ParticleSystem(this.device, this.cameraUniformBuffer, {
-                hdr: this.hdrFormat,
-                mask: Engine.BLOOM_MASK_FORMAT,
-                depth: "depth24plus-stencil8",
-                sampleCount: Engine.MULTISAMPLE_COUNT,
-            });
-        }
-        this.particles.emit(opts, performance.now() / 1000);
-    }
     // Step 5: Create lighting buffers
     setupLighting() {
         this.lightUniformBuffer = this.device.createBuffer({
@@ -2625,8 +2769,6 @@ export class Engine {
             Engine.instance = null;
         if (this.camera)
             this.camera.detachControl();
-        this.particles?.dispose();
-        this.particles = null;
         // Remove raycasting event listeners
         if (this.onRaycast) {
             this.canvas.removeEventListener("dblclick", this.handleCanvasDoubleClick);
@@ -4209,6 +4351,22 @@ export class Engine {
         }
         this.updateCameraUniforms();
         this.updateShadowLightVP();
+        // Depth of field's entire disabled cost is this branch: depth stays in
+        // TBDR tile memory (discard) unless something in the composite reads it this
+        // frame. Two things can — the DoF gather, and the depth handed to a
+        // foreground effect — and either one makes the pass store it.
+        //
+        // The uniform refresh is shared for the same reason: linearDepth() inverts
+        // the z-buffer with projA/projB out of dofU[2], which track the camera's
+        // near/far and so must be rewritten every frame either reader is live. A
+        // foreground with a stale pair would read metres from the wrong frustum. The
+        // write leaves dofU[0].x at 0 while DoF is off, so refreshing it does not
+        // switch the gather on.
+        const dofOn = this.depthOfField.enabled;
+        const depthRead = dofOn || (this.effect?.hasForeground ?? false);
+        this.renderPassDescriptor.depthStencilAttachment.depthStoreOp = depthRead ? "store" : "discard";
+        if (depthRead)
+            this.writeDepthOfFieldUniforms();
         const encoder = this.device.createCommandEncoder();
         // GPU vertex morphs: write morphed positions into vertex buffers before any pass reads
         // them. WebGPU inserts the storage→vertex barrier between this pass and the render passes.
@@ -4257,9 +4415,6 @@ export class Engine {
                 if (inst.model.visible)
                     this.renderModelTransparentPhase(pass, inst);
             });
-        // Particle emissions last: additive light over everything, depth-tested
-        // against the scene, feeding the bloom mask so the sparks glow.
-        this.particles?.draw(pass, performance.now() / 1000);
         pass.end();
         // Bloom pyramid (EEVEE 3.6):
         //   1. Blit: HDR → bloomDown[0] (Karis prefilter, half-res)
@@ -4838,7 +4993,7 @@ export class Engine {
         // is LEFT-HANDED (+Z forward, see Mat4.lookAtInto), so the world-space
         // right/up/FORWARD vectors are rows 0/1/2 of its rotation block directly
         // (column-major storage: row i = values[i], values[i+4], values[i+8]).
-        if ((this.backdropEquirectView || this.backgroundEffect) && this.compositeUniformBuffer) {
+        if ((this.backdropEquirectView || this.effect) && this.compositeUniformBuffer) {
             const v = viewMatrix.values;
             const u = this.compositeUniformData;
             const tanHalf = Math.tan((this.camera.fov ?? Math.PI / 4) / 2);
@@ -4856,9 +5011,15 @@ export class Engine {
             u[22] = v[10];
             u[23] = 0;
             // Effect clock + canvas size (viewU[6]) — written on the same refresh.
-            u[24] = (performance.now() - this.bgEffectEpochMs) / 1000;
+            u[24] = (performance.now() - this.effectEpochMs) / 1000;
             u[26] = this.canvas.width;
             u[27] = this.canvas.height;
+            // Camera world position (viewU[10]) — the other half of bgWorldPos. It
+            // rides this refresh rather than writeCompositeViewUniforms because it
+            // changes every frame the camera does, exactly like the basis above.
+            u[40] = cameraPos.x;
+            u[41] = cameraPos.y;
+            u[42] = cameraPos.z;
             this.device.queue.writeBuffer(this.compositeUniformBuffer, 0, u);
         }
     }

package/dist/graph/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/graph/registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEzD,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC9B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAA;IAC/C,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC,CAAA;AAMD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI1C;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,CAgBhE;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAIpE;AAMD,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAM1D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpE;AA6BD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAuPlD,CAAA"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/graph/registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEzD,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC9B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAA;IAC/C,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC,CAAA;AAMD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI1C;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,CAgBhE;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAIpE;AAMD,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAM1D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpE;AA6BD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAkQlD,CAAA"}

package/dist/graph/registry.js

@@ -126,6 +126,16 @@ export const NODE_REGISTRY = {
         outputs: { color: "color" },
         contextOutputs: { color: "material.diffuseColor" },
     },
+    // The PMX material's sphere map, which is where an MMD model keeps its
+    // highlights — every PMX ships one, and hair without it reads flat. The mode
+    // is the material's own (.sph multiplies the shaded base, .spa adds a
+    // highlight), so a graph asks for the effect and the model decides which; a
+    // material with no sphere texture is an exact no-op.
+    sphere_map: {
+        inputs: { base: C([0, 0, 0], true), strength: F(1) },
+        outputs: { color: "color" },
+        emit: (a) => `pmx_sphere_map(${a.base}, ${a.strength}, n)`,
+    },
     // ── Literals as nodes (for editor ergonomics; inlined literals work too) ──
     value: { inputs: { value: F(0) }, outputs: { value: "float" }, emit: (a) => a.value },
     rgb: { inputs: { color: C() }, outputs: { color: "color" }, emit: (a) => a.color },

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_VIEW_TRANSFORM, DEFAULT_COLOR_GRADING, type ColorGradingOptions, type EngineStats, type EngineOptions, type BloomOptions, type ViewTransformOptions, type LoadModelFromFilesOptions, type MaterialPreset, type MaterialPresetMap, type ModelTransform, type GizmoDragEvent, type GizmoDragCallback, type GizmoDragKind, type BackgroundEffectParamValue, type BackgroundEffectResult, } from "./engine";
+export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_DEPTH_OF_FIELD_OPTIONS, DEFAULT_VIEW_TRANSFORM, DEFAULT_COLOR_GRADING, type ColorGradingOptions, type EngineStats, type EngineOptions, type BloomOptions, type DepthOfFieldOptions, type ViewTransformOptions, type LoadModelFromFilesOptions, type MaterialPreset, type MaterialPresetMap, type ModelTransform, type GizmoDragEvent, type GizmoDragCallback, type GizmoDragKind, type EffectParamValue, type EffectResult, } from "./engine";
 export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload";
 export { compileGraph, validateGraph, assignStyleSlots, type CompileOptions, type CompileResult, type StyleSlot, } from "./graph/compile";
 export type { ShaderGraph, GraphNode, GraphLink, ExposedParam, SocketValue, Diagnostic, } from "./graph/schema";
@@ -26,5 +26,4 @@ export { PmxLoader } from "./pmx-loader";
 export { CameraAnimation, type CameraPose } from "./camera-animation";
 export { RezePhysics } from "./physics";
 export type { WindOptions } from "./physics/world";
-export { type ParticleEmitOptions } from "./particles";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_VIEW_TRANSFORM, DEFAULT_COLOR_GRADING, } from "./engine";
+export { Engine, DEFAULT_BLOOM_OPTIONS, DEFAULT_DEPTH_OF_FIELD_OPTIONS, DEFAULT_VIEW_TRANSFORM, DEFAULT_COLOR_GRADING, } from "./engine";
 export { parsePmxFolderInput, pmxFileAtRelativePath } from "./folder-upload";
 export { compileGraph, validateGraph, assignStyleSlots, } from "./graph/compile";
 export { NODE_REGISTRY } from "./graph/registry";

package/dist/model.d.ts

@@ -312,11 +312,6 @@ export declare class Model {
     getWorldMatrices(): Mat4[];
     getBoneWorldMatrices(): Float32Array;
     getBoneInverseBindMatrices(): Float32Array;
-    /** World-space positions of `count` vertices sampled evenly across the mesh
-     *  under the CURRENT pose — the model's skinning replayed on the CPU for
-     *  this one call, root transform included. Feed to Engine.emitParticles for
-     *  dissolve/materialize effects shaped like the model itself. */
-    sampleSurfacePoints(count: number): Float32Array;
     getSkinMatrices(): Float32Array;
     setMorphWeight(name: string, weight: number, durationMs?: number): void;
     private applyMorphs;