reze-engine 0.39.0 → 0.41.0

package/src/engine.ts

@@ -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, type ParticleEmitOptions } from "./particles"
 import { PmxLoader } from "./pmx-loader"
 import { RezePhysics } from "./physics"
 import type { WindOptions } from "./physics/world"
@@ -236,14 +235,17 @@ export type SunOptions = {
   direction?: Vec3
 }
 
-/** A background-effect param: number → f32, vector-like → vec3f (see
- *  setBackgroundEffect). Structural {x,y,z} rather than the Vec3 class so
- *  JSON-derived values (a shared scene document's params) pass straight in. */
-export type BackgroundEffectParamValue = number | { x: number; y: number; z: number }
-export type BackgroundEffectResult = {
+/** An effect param: number → f32, vector-like → vec3f (see setEffect).
+ *  Structural {x,y,z} rather than the Vec3 class so JSON-derived values (a
+ *  shared scene document's params) pass straight in. */
+export type EffectParamValue = number | { x: number; y: number; z: number }
+export type EffectResult = {
   ok: boolean
   /** Compile/validation errors, line:col relative to the USER's WGSL. */
   diagnostics: string[]
+  /** Which mounts the WGSL declared — `fn background` / `fn foreground`. Both
+   *  false only on a failed compile, since defining neither IS the failure. */
+  mounts: { background: boolean; foreground: boolean }
 }
 
 export type CameraOptions = {
@@ -276,6 +278,42 @@ export const DEFAULT_BLOOM_OPTIONS: BloomOptions = {
   clamp: 0.0,
 }
 
+/** Camera depth of field — a bokeh gather in the composite pass. Costs nothing
+ *  while disabled: the scene pass discards its depth buffer and the composite
+ *  branch never runs. Enabled, the pass stores depth and the gather reads it. */
+export type DepthOfFieldOptions = {
+  enabled: boolean
+  /** "auto" focuses the first visible character each frame — the camera-space
+   *  depth span of its bones sets both distance and a floor on range — so a
+   *  dancer stays sharp without anyone touching a slider. "manual" uses
+   *  focusDistance/focusRange as given. */
+  focusMode: "auto" | "manual"
+  /** Camera-space distance to the focus plane (MMD units). */
+  focusDistance: number
+  /** Depth band that stays perfectly sharp, centered on focusDistance. In auto
+   *  mode this is a minimum — the band never cuts into the subject. */
+  focusRange: number
+  /** Blur strength scale; 1 is a natural lens, higher is dreamier. */
+  aperture: number
+  /** Largest blur circle, in device pixels. */
+  maxBlurRadius: number
+  /** Bokeh polygon blade count (3–12); 6 is the classic hexagon. */
+  bladeCount: number
+  /** Gather tap count: 8 / 16 / 24. */
+  quality: "performance" | "balanced" | "cinematic"
+}
+
+export const DEFAULT_DEPTH_OF_FIELD_OPTIONS: DepthOfFieldOptions = {
+  enabled: false,
+  focusMode: "auto",
+  focusDistance: 25,
+  focusRange: 2,
+  aperture: 1,
+  maxBlurRadius: 18,
+  bladeCount: 6,
+  quality: "balanced",
+}
+
 /** Blender Color Management / View (rendering.txt: Filmic, exposure, gamma). `look` is reserved for future curve tweaks. */
 export type ViewTransformOptions = {
   /** Stops applied before Filmic: `linear *= 2^exposure`. */
@@ -718,8 +756,6 @@ export class Engine {
   private multisampleMaskTexture!: GPUTexture
   private maskResolveTexture!: GPUTexture
   private maskResolveView!: GPUTextureView
-  /** One-shot particle emissions (emitParticles); lazily built on first emit. */
-  private particles: ParticleSystem | null = null
   private renderPassDescriptor!: GPURenderPassDescriptor
   private compositePassDescriptor!: GPURenderPassDescriptor
   // Two specialized composite pipelines via WGSL pipeline-override constants.
@@ -731,9 +767,18 @@ export class Engine {
   private morphComputeBindGroupLayout!: GPUBindGroupLayout
   private compositeBindGroupLayout!: GPUBindGroupLayout
   private compositeBindGroup!: GPUBindGroup
+  private depthOfField: DepthOfFieldOptions = { ...DEFAULT_DEPTH_OF_FIELD_OPTIONS }
+  private dofUniformBuffer!: GPUBuffer
+  private dofUniformData = new Float32Array(12)
+  private dofFocusScratch = new Vec3(0, 0, 0)
+  /** Depth-only view of the scene's MSAA depth buffer, read by the DoF gather. */
+  private depthReadView: GPUTextureView | null = null
   private compositeUniformBuffer!: GPUBuffer
   // [exposure, invGamma, _, _,  bloomTint.x, bloomTint.y, bloomTint.z, bloomIntensity]
-  private readonly 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.
+  private readonly compositeUniformData = new Float32Array(44)
   /** Composite background (display-space sRGB 0–1) — null = transparent canvas. */
   private backgroundColor: Vec3 | null = null
   // 360 backdrop (equirectangular skybox, sampled by view ray in composite).
@@ -741,21 +786,27 @@ export class Engine {
   private backdropEquirectView: GPUTextureView | null = null
   private fallbackEquirectTexture!: GPUTexture
   private fallbackEquirectView!: GPUTextureView
-  // 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).
-  private backgroundEffect: {
+  private effect: {
     wgsl: string
     paramLayout: Map<string, { offset: number; comps: 1 | 3 }>
     paramsBuffer: GPUBuffer | null
     paramsData: Float32Array<ArrayBuffer>
+    /** Mounted under the scene. */
+    hasBackground: boolean
+    /** Mounted over the finished frame — and the reason the scene pass has to
+     *  STORE its depth, which it otherwise discards into tile memory. */
+    hasForeground: boolean
   } | null = null
   /** Bound at composite binding 7 when no effect (or a param-less one) is set. */
   private bgParamsDummyBuffer!: GPUBuffer
   private compositePipelineLayout!: GPUPipelineLayout
-  /** time=0 origin for the active effect — reset each setBackgroundEffect. */
-  private bgEffectEpochMs = 0
+  /** time=0 origin for the active effect — reset each setEffect. */
+  private effectEpochMs = 0
   private compositeBloomView: GPUTextureView | null = null
 
   // EEVEE-style bloom pyramid (mirrors Blender 3.6 effect_bloom_frag.glsl):
@@ -1023,10 +1074,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,
@@ -1082,7 +1133,7 @@ export class Engine {
   }
 
   private rebuildCompositeBindGroup(): void {
-    if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView) return
+    if (!this.device || !this.hdrResolveTexture || !this.compositeBloomView || !this.depthReadView) return
     this.compositeBindGroup = this.device.createBindGroup({
       label: "composite bind group",
       layout: this.compositeBindGroupLayout,
@@ -1094,7 +1145,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 } },
       ],
     })
   }
@@ -1159,45 +1212,72 @@ 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
    *
-   * 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.
+   * `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.
    *
-   * 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.
+   * `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.
+   *
+   * 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: string | null,
-    params?: Record<string, BackgroundEffectParamValue>,
-  ): Promise<BackgroundEffectResult> {
-    if (!this.device) return { ok: false, diagnostics: ["setBackgroundEffect requires init() to have run"] }
+  async setEffect(wgsl: string | null, params?: Record<string, EffectParamValue>): Promise<EffectResult> {
+    const noMounts = { background: false, foreground: false }
+    if (!this.device) 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
@@ -1209,7 +1289,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
@@ -1229,22 +1309,22 @@ 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
       .filter((m) => m.type === "error")
       .map((m) => `${Math.max(0, m.lineNum - userLineOffset)}:${m.linePos} ${m.message}`)
     if (diagnostics.length === 0 && scopeErr) diagnostics.push(scopeErr.message)
-    if (diagnostics.length > 0) return { ok: false, diagnostics }
+    if (diagnostics.length > 0) return { ok: false, diagnostics, mounts }
     let identity: GPURenderPipeline
     let gamma: GPURenderPipeline
     try {
@@ -1262,37 +1342,42 @@ 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: GPUBuffer | null = 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(): { background: boolean; foreground: boolean } {
+    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: string, value: BackgroundEffectParamValue): void {
-    const fx = this.backgroundEffect
+  /** Write one effect param (declared at setEffect) — a uniform write, no
+   *  recompile; the instant tier, like setStyleParam. */
+  setEffectParam(name: string, value: EffectParamValue): void {
+    const fx = this.effect
     if (!fx || !fx.paramsBuffer) return
     const slot = fx.paramLayout.get(name)
     if (!slot) return
@@ -1306,6 +1391,89 @@ export class Engine {
   }
 
   /** 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: Partial<DepthOfFieldOptions>): void {
+    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(): DepthOfFieldOptions {
+    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). */
+  private getModelBodyFocus(): { distance: number; range: number } | null {
+    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
+  }
+
+  private writeDepthOfFieldUniforms(): void {
+    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: Partial<BloomOptions>): void {
     const b = this.bloomSettings
     if (patch.enabled !== undefined) b.enabled = patch.enabled
@@ -2165,11 +2333,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({
@@ -2194,6 +2369,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({
@@ -2439,10 +2623,13 @@ 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.
@@ -2871,6 +3058,13 @@ export class Engine {
     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(): number {
+    return this.cameraAnimation?.duration ?? 0
+  }
+
   /** Drop the loaded camera VMD and return to orbit control. */
   clearCameraVmd(): void {
     this.cameraAnimation = null
@@ -2923,24 +3117,6 @@ export class Engine {
     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: ParticleEmitOptions): void {
-    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
   private setupLighting() {
     this.lightUniformBuffer = this.device.createBuffer({
@@ -3096,8 +3272,6 @@ export class Engine {
     this.forEachInstance((inst) => inst.model.stop())
     if (Engine.instance === this) Engine.instance = null
     if (this.camera) this.camera.detachControl()
-    this.particles?.dispose()
-    this.particles = null
 
     // Remove raycasting event listeners
     if (this.onRaycast) {
@@ -5093,6 +5267,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
@@ -5139,9 +5329,6 @@ export class Engine {
       this.forEachInstance((inst) => {
         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):
@@ -5757,7 +5944,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)
@@ -5775,9 +5962,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/src/graph/registry.ts

@@ -146,6 +146,17 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     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/src/index.ts

@@ -1,12 +1,14 @@
 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,
@@ -15,8 +17,8 @@ export {
   type GizmoDragEvent,
   type GizmoDragCallback,
   type GizmoDragKind,
-  type BackgroundEffectParamValue,
-  type BackgroundEffectResult,
+  type EffectParamValue,
+  type EffectResult,
 } from "./engine"
 export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload"
 export {
@@ -99,4 +101,3 @@ 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"