reze-engine 0.39.0 → 0.40.0

package/dist/shaders/passes/composite.js

@@ -44,10 +44,51 @@ override APPLY_GAMMA: bool = true;
 // viewU[9] = (grade slope.rgb, grade on/off) — see grade() below.
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
 @group(0) @binding(6) var bgEquirect: texture_2d<f32>;
+// The scene pass's own MSAA depth buffer, bound depth-only. NOT an extra
+// render target: when depth of field is off the scene pass discards depth
+// (TBDR tile memory never spills) and this binding is never read — the whole
+// feature costs one uniform branch. When on, the pass stores depth and the
+// gather below reads sample 0.
+@group(0) @binding(8) var depthTex: texture_depth_multisampled_2d;
+// dofU[0] = (enabled, focusDistance, focusRange, aperture)
+// dofU[1] = (maxBlurRadiusPx, bladeCount, sampleCount, anamorphicRatio)
+// dofU[2] = (projA, projB, _, _) — z-buffer → camera-space depth inversion,
+//           viewZ = projB / (z - projA), rebuilt per frame because near/far
+//           track the camera radius. Cleared depth (1.0) inverts to the far
+//           plane, so empty sky reads as maximally defocused background.
+@group(0) @binding(9) var<uniform> dofU: array<vec4<f32>, 3>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
 
+fn linearDepth(coord: vec2<i32>) -> f32 {
+  let z = textureLoad(depthTex, coord, 0);
+  // projA > 1 for every valid z in [0,1], so the divisor never crosses zero.
+  return clamp(dofU[2].y / (z - dofU[2].x), 0.05, 100000.0);
+}
+
+/** Signed circle of confusion in device pixels — negative in front of the
+ *  focus band, positive behind it, zero inside it. */
+fn circleOfConfusion(depth: f32) -> f32 {
+  let focus = max(dofU[0].y, 0.05);
+  let halfRange = max(dofU[0].z * 0.5, 0.01);
+  let delta = depth - focus;
+  let outside = max(abs(delta) - halfRange, 0.0);
+  let radius = min(outside / max(depth, 0.05) * dofU[0].w * dofU[1].x, dofU[1].x);
+  return select(-radius, radius, delta >= 0.0);
+}
+
+/** Premultiplied scene color (HDR + bloom) at an arbitrary pixel, for the
+ *  bokeh gather. Explicit-LOD sampling only — legal in non-uniform flow. */
+fn sceneSample(coord: vec2<i32>, fullSzI: vec2<i32>, fullSz: vec2f) -> vec4f {
+  let p = clamp(coord, vec2<i32>(0), fullSzI - vec2<i32>(1));
+  let sAlpha = textureLoad(maskTex, p, 0).g;
+  let sHdr = textureLoad(hdrTex, p, 0).rgb / max(sAlpha, 1e-6);
+  let sUv = (vec2f(p) + vec2f(0.5)) / fullSz;
+  let sBloom = textureSampleLevel(bloomTex, bloomSamp, sUv, 0.0).rgb * viewU[1].xyz * viewU[1].w;
+  return vec4f((sHdr + sBloom) * sAlpha, sAlpha);
+}
+
 fn filmic(x: f32) -> f32 {
   // Reference checkpoints (Blender 3.6 Filmic MHC, sobotka/filmic-blender
   // look_medium-high-contrast.spi1d): linear 0.18 → ~0.395, linear 1.0 → ~0.83.
@@ -101,7 +142,59 @@ const COMPOSITE_BODY = /* wgsl */ `
   let intensity = viewU[1].w;
   let bloom = textureSampleLevel(bloomTex, bloomSamp, bloomUv, 0.0).rgb * tint * intensity;
   let combined = straight + bloom;
-  let exposed = combined * exp2(viewU[0].x);
+
+  // ── Depth of field ──
+  // Single-pass golden-angle gather over a polygonal (bladed) disk, in
+  // premultiplied HDR before tonemap. Near-field taps that see focused
+  // background are heavily down-weighted so a sharp subject doesn't bleed into
+  // a blurred foreground; the reverse leak (background bokeh over the subject
+  // edge) is damped less — that soft halo is what real lenses do. Scene layer
+  // only: the composited background (solid / 360 / effect) stays sharp, which
+  // is invisible while it sits at infinity behind a far-blurred stage.
+  var scenePm = vec4f(combined * alpha, alpha);
+  if (dofU[0].x > 0.5) {
+    let centerDepth = linearDepth(coord);
+    let centerCoc = circleOfConfusion(centerDepth);
+    let radius = abs(centerCoc);
+    if (radius > 0.35) {
+      let fullSzI = vec2<i32>(fullSz);
+      let sampleCount = clamp(dofU[1].z, 6.0, 24.0);
+      let blades = clamp(dofU[1].y, 3.0, 12.0);
+      let sector = 6.28318530718 / blades;
+      var accum = scenePm;
+      var weightSum = 1.0;
+      for (var i = 0u; i < 24u; i++) {
+        if (f32(i) >= sampleCount) { break; }
+        let fi = f32(i) + 0.5;
+        let ring = sqrt(fi / sampleCount);
+        let angle = fi * 2.39996323;
+        let localAngle = (fract((angle + 3.14159265359) / sector) - 0.5) * sector;
+        let polygonRadius = cos(3.14159265359 / blades) / max(cos(localAngle), 0.01);
+        var disk = vec2f(cos(angle), sin(angle)) * ring * polygonRadius;
+        disk.x *= max(dofU[1].w, 0.25);
+        let sp = coord + vec2<i32>(round(disk * radius));
+        let cp = clamp(sp, vec2<i32>(0), fullSzI - vec2<i32>(1));
+        let sampleDepth = linearDepth(cp);
+        let sampleCoc = circleOfConfusion(sampleDepth);
+        var w = 1.0;
+        if (centerCoc < 0.0 && sampleDepth > centerDepth + dofU[0].z) {
+          w *= 0.08;
+        } else if (centerCoc > 0.0 && sampleDepth > centerDepth + dofU[0].z * 2.0) {
+          w *= 0.35;
+        }
+        // A tap only contributes where its own blur circle reaches this pixel.
+        let sampleRadius = abs(sampleCoc);
+        w *= mix(0.2, 1.0, smoothstep(ring * radius - 1.0, ring * radius + 1.0, sampleRadius));
+        accum += sceneSample(cp, fullSzI, fullSz) * w;
+        weightSum += w;
+      }
+      scenePm = mix(scenePm, accum / max(weightSum, 1e-5), smoothstep(0.35, 1.75, radius));
+    }
+  }
+  let sceneAlpha = scenePm.a;
+  let sceneStraight = scenePm.rgb / max(sceneAlpha, 1e-6);
+
+  let exposed = sceneStraight * exp2(viewU[0].x);
   let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));
   var disp = max(tm, vec3f(0.0));
   // Grade the SCENE only, before the display gamma. Deliberately not applied to
@@ -135,7 +228,7 @@ const COMPOSITE_BODY = /* wgsl */ `
     }
     BG_EFFECT_CALL
   }
-  return vec4f(disp * alpha + bgPm * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
+  return vec4f(disp * sceneAlpha + bgPm * (1.0 - sceneAlpha), sceneAlpha + bgA * (1.0 - sceneAlpha));
 }
 `;
 // Base variant: no effect installed, the flag is never set — the ray block only
@@ -165,7 +258,9 @@ const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/;
  *  uniform control flow and forgo the gate. */
 function coverageGate(effect) {
     const gated = !effect || !USES_DERIVATIVES.test(effect.wgsl);
-    return gated ? "&& alpha < 0.999" : "";
+    // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
+    // sharp scene fully covered can end up needing background behind its blur.
+    return gated ? "&& sceneAlpha < 0.999" : "";
 }
 export function buildCompositeShader(effect) {
     if (!effect)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -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"
@@ -276,6 +275,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 +753,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,6 +764,12 @@ 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)
@@ -1082,7 +1121,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,
@@ -1095,6 +1134,8 @@ export class Engine {
         { binding: 5, resource: this.filmicLutView },
         { binding: 6, resource: this.backdropEquirectView ?? this.fallbackEquirectView },
         { binding: 7, resource: { buffer: this.backgroundEffect?.paramsBuffer ?? this.bgParamsDummyBuffer } },
+        { binding: 8, resource: this.depthReadView },
+        { binding: 9, resource: { buffer: this.dofUniformBuffer } },
       ],
     })
   }
@@ -1306,6 +1347,86 @@ 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
+    const auto = 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
@@ -2172,6 +2293,12 @@ export class Engine {
       size: 160,
       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({
       label: "bg effect params (dummy)",
       size: 16,
@@ -2194,6 +2321,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 +2575,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.
@@ -2923,24 +3062,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 +3217,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 +5212,14 @@ 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 the composite gather reads it this
+    // frame. Enabled frames also refresh the uniforms — auto-focus tracks the
+    // character and the depth-inversion constants track near/far.
+    const dofOn = this.depthOfField.enabled
+    this.renderPassDescriptor.depthStencilAttachment!.depthStoreOp = dofOn ? "store" : "discard"
+    if (dofOn) this.writeDepthOfFieldUniforms()
+
     const encoder = this.device.createCommandEncoder()
 
     // GPU vertex morphs: write morphed positions into vertex buffers before any pass reads
@@ -5139,9 +5266,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):

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,
@@ -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"

package/src/model.ts

@@ -1141,42 +1141,6 @@ export class Model {
     return this.skeleton.inverseBindMatrices
   }
 
-  /** 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 {
-    const skin = this.getSkinMatrices()
-    const joints = this.skinning.joints
-    const weights = this.skinning.weights
-    const n = this.vertexCount
-    const c = Math.max(1, Math.min(count, n))
-    const out = new Float32Array(c * 3)
-    const step = n / c
-    for (let i = 0; i < c; i++) {
-      const v = Math.min(n - 1, Math.floor(i * step + Math.random() * step))
-      const vi = v * VERTEX_STRIDE
-      const px = this.vertexData[vi]
-      const py = this.vertexData[vi + 1]
-      const pz = this.vertexData[vi + 2]
-      let x = 0
-      let y = 0
-      let z = 0
-      for (let j = 0; j < 4; j++) {
-        const w = weights[v * 4 + j] / 255
-        if (w === 0) continue
-        const m = joints[v * 4 + j] * 16
-        x += w * (skin[m] * px + skin[m + 4] * py + skin[m + 8] * pz + skin[m + 12])
-        y += w * (skin[m + 1] * px + skin[m + 5] * py + skin[m + 9] * pz + skin[m + 13])
-        z += w * (skin[m + 2] * px + skin[m + 6] * py + skin[m + 10] * pz + skin[m + 14])
-      }
-      out[i * 3] = x
-      out[i * 3 + 1] = y
-      out[i * 3 + 2] = z
-    }
-    return out
-  }
-
   getSkinMatrices(): Float32Array {
     const boneCount = this.skeleton.bones.length
     const worldMats = this.runtimeSkeleton.worldMatrices

package/src/shaders/passes/composite.ts

@@ -66,10 +66,51 @@ override APPLY_GAMMA: bool = true;
 // viewU[9] = (grade slope.rgb, grade on/off) — see grade() below.
 // invGamma = 1/gamma precomputed on CPU — avoids a per-pixel divide.
 @group(0) @binding(6) var bgEquirect: texture_2d<f32>;
+// The scene pass's own MSAA depth buffer, bound depth-only. NOT an extra
+// render target: when depth of field is off the scene pass discards depth
+// (TBDR tile memory never spills) and this binding is never read — the whole
+// feature costs one uniform branch. When on, the pass stores depth and the
+// gather below reads sample 0.
+@group(0) @binding(8) var depthTex: texture_depth_multisampled_2d;
+// dofU[0] = (enabled, focusDistance, focusRange, aperture)
+// dofU[1] = (maxBlurRadiusPx, bladeCount, sampleCount, anamorphicRatio)
+// dofU[2] = (projA, projB, _, _) — z-buffer → camera-space depth inversion,
+//           viewZ = projB / (z - projA), rebuilt per frame because near/far
+//           track the camera radius. Cleared depth (1.0) inverts to the far
+//           plane, so empty sky reads as maximally defocused background.
+@group(0) @binding(9) var<uniform> dofU: array<vec4<f32>, 3>;
 
 // Must match FILMIC_LUT_WIDTH in engine.ts (bakeFilmicLut).
 const FILMIC_LUT_W: f32 = 256.0;
 
+fn linearDepth(coord: vec2<i32>) -> f32 {
+  let z = textureLoad(depthTex, coord, 0);
+  // projA > 1 for every valid z in [0,1], so the divisor never crosses zero.
+  return clamp(dofU[2].y / (z - dofU[2].x), 0.05, 100000.0);
+}
+
+/** Signed circle of confusion in device pixels — negative in front of the
+ *  focus band, positive behind it, zero inside it. */
+fn circleOfConfusion(depth: f32) -> f32 {
+  let focus = max(dofU[0].y, 0.05);
+  let halfRange = max(dofU[0].z * 0.5, 0.01);
+  let delta = depth - focus;
+  let outside = max(abs(delta) - halfRange, 0.0);
+  let radius = min(outside / max(depth, 0.05) * dofU[0].w * dofU[1].x, dofU[1].x);
+  return select(-radius, radius, delta >= 0.0);
+}
+
+/** Premultiplied scene color (HDR + bloom) at an arbitrary pixel, for the
+ *  bokeh gather. Explicit-LOD sampling only — legal in non-uniform flow. */
+fn sceneSample(coord: vec2<i32>, fullSzI: vec2<i32>, fullSz: vec2f) -> vec4f {
+  let p = clamp(coord, vec2<i32>(0), fullSzI - vec2<i32>(1));
+  let sAlpha = textureLoad(maskTex, p, 0).g;
+  let sHdr = textureLoad(hdrTex, p, 0).rgb / max(sAlpha, 1e-6);
+  let sUv = (vec2f(p) + vec2f(0.5)) / fullSz;
+  let sBloom = textureSampleLevel(bloomTex, bloomSamp, sUv, 0.0).rgb * viewU[1].xyz * viewU[1].w;
+  return vec4f((sHdr + sBloom) * sAlpha, sAlpha);
+}
+
 fn filmic(x: f32) -> f32 {
   // Reference checkpoints (Blender 3.6 Filmic MHC, sobotka/filmic-blender
   // look_medium-high-contrast.spi1d): linear 0.18 → ~0.395, linear 1.0 → ~0.83.
@@ -124,7 +165,59 @@ const COMPOSITE_BODY = /* wgsl */ `
   let intensity = viewU[1].w;
   let bloom = textureSampleLevel(bloomTex, bloomSamp, bloomUv, 0.0).rgb * tint * intensity;
   let combined = straight + bloom;
-  let exposed = combined * exp2(viewU[0].x);
+
+  // ── Depth of field ──
+  // Single-pass golden-angle gather over a polygonal (bladed) disk, in
+  // premultiplied HDR before tonemap. Near-field taps that see focused
+  // background are heavily down-weighted so a sharp subject doesn't bleed into
+  // a blurred foreground; the reverse leak (background bokeh over the subject
+  // edge) is damped less — that soft halo is what real lenses do. Scene layer
+  // only: the composited background (solid / 360 / effect) stays sharp, which
+  // is invisible while it sits at infinity behind a far-blurred stage.
+  var scenePm = vec4f(combined * alpha, alpha);
+  if (dofU[0].x > 0.5) {
+    let centerDepth = linearDepth(coord);
+    let centerCoc = circleOfConfusion(centerDepth);
+    let radius = abs(centerCoc);
+    if (radius > 0.35) {
+      let fullSzI = vec2<i32>(fullSz);
+      let sampleCount = clamp(dofU[1].z, 6.0, 24.0);
+      let blades = clamp(dofU[1].y, 3.0, 12.0);
+      let sector = 6.28318530718 / blades;
+      var accum = scenePm;
+      var weightSum = 1.0;
+      for (var i = 0u; i < 24u; i++) {
+        if (f32(i) >= sampleCount) { break; }
+        let fi = f32(i) + 0.5;
+        let ring = sqrt(fi / sampleCount);
+        let angle = fi * 2.39996323;
+        let localAngle = (fract((angle + 3.14159265359) / sector) - 0.5) * sector;
+        let polygonRadius = cos(3.14159265359 / blades) / max(cos(localAngle), 0.01);
+        var disk = vec2f(cos(angle), sin(angle)) * ring * polygonRadius;
+        disk.x *= max(dofU[1].w, 0.25);
+        let sp = coord + vec2<i32>(round(disk * radius));
+        let cp = clamp(sp, vec2<i32>(0), fullSzI - vec2<i32>(1));
+        let sampleDepth = linearDepth(cp);
+        let sampleCoc = circleOfConfusion(sampleDepth);
+        var w = 1.0;
+        if (centerCoc < 0.0 && sampleDepth > centerDepth + dofU[0].z) {
+          w *= 0.08;
+        } else if (centerCoc > 0.0 && sampleDepth > centerDepth + dofU[0].z * 2.0) {
+          w *= 0.35;
+        }
+        // A tap only contributes where its own blur circle reaches this pixel.
+        let sampleRadius = abs(sampleCoc);
+        w *= mix(0.2, 1.0, smoothstep(ring * radius - 1.0, ring * radius + 1.0, sampleRadius));
+        accum += sceneSample(cp, fullSzI, fullSz) * w;
+        weightSum += w;
+      }
+      scenePm = mix(scenePm, accum / max(weightSum, 1e-5), smoothstep(0.35, 1.75, radius));
+    }
+  }
+  let sceneAlpha = scenePm.a;
+  let sceneStraight = scenePm.rgb / max(sceneAlpha, 1e-6);
+
+  let exposed = sceneStraight * exp2(viewU[0].x);
   let tm = vec3f(filmic(exposed.r), filmic(exposed.g), filmic(exposed.b));
   var disp = max(tm, vec3f(0.0));
   // Grade the SCENE only, before the display gamma. Deliberately not applied to
@@ -158,7 +251,7 @@ const COMPOSITE_BODY = /* wgsl */ `
     }
     BG_EFFECT_CALL
   }
-  return vec4f(disp * alpha + bgPm * (1.0 - alpha), alpha + bgA * (1.0 - alpha));
+  return vec4f(disp * sceneAlpha + bgPm * (1.0 - sceneAlpha), sceneAlpha + bgA * (1.0 - sceneAlpha));
 }
 `
 
@@ -192,7 +285,9 @@ const USES_DERIVATIVES = /\b(?:fwidth|dpdx|dpdy)(?:Fine|Coarse)?\s*\(/
  *  uniform control flow and forgo the gate. */
 function coverageGate(effect?: CompositeEffectSource | null): string {
   const gated = !effect || !USES_DERIVATIVES.test(effect.wgsl)
-  return gated ? "&& alpha < 0.999" : ""
+  // sceneAlpha, not alpha: the bokeh gather spreads coverage, so a pixel the
+  // sharp scene fully covered can end up needing background behind its blur.
+  return gated ? "&& sceneAlpha < 0.999" : ""
 }
 
 export function buildCompositeShader(effect?: CompositeEffectSource | null): string {

package/dist/particles.d.ts

@@ -1,43 +0,0 @@
-import { Vec3 } from "./math";
-export interface ParticleEmitOptions {
-    /** World-space anchor points, xyz-packed (see Model.sampleSurfacePoints).
-     *  One particle spawns per point. */
-    points: Float32Array;
-    /** "burst" flies point → scattered and fades (dissolve); "converge" flies
-     *  scattered → point and vanishes on arrival (materialize). Default burst. */
-    mode?: "burst" | "converge";
-    /** Seconds the full effect lasts, staggers included (default 1.6). */
-    duration?: number;
-    /** HDR color — components above 1 glow through bloom (default warm gold). */
-    color?: Vec3;
-    /** Particle radius in world units (default 0.5). */
-    size?: number;
-    /** Scatter distance in world units at the far end of the flight (default 14). */
-    scatter?: number;
-    /** Upward drift across the flight, world units (default 6). */
-    lift?: number;
-    /** Radians the cloud winds around its centroid across the flight (default 2). */
-    swirl?: number;
-}
-export declare class ParticleSystem {
-    private readonly device;
-    private readonly pipeline;
-    private readonly bindGroupLayout;
-    private readonly cameraBuffer;
-    private readonly timeBuffer;
-    private readonly timeData;
-    private emissions;
-    constructor(device: GPUDevice, cameraBuffer: GPUBuffer, formats: {
-        hdr: GPUTextureFormat;
-        mask: GPUTextureFormat;
-        depth: GPUTextureFormat;
-        sampleCount: number;
-    });
-    /** Upload one emission. `now` is the shared clock (seconds) draw() receives. */
-    emit(opts: ParticleEmitOptions, now: number): void;
-    get active(): boolean;
-    /** Record draws into the main pass (after the transparent phase). */
-    draw(pass: GPURenderPassEncoder, now: number): void;
-    dispose(): void;
-}
-//# sourceMappingURL=particles.d.ts.map

package/dist/particles.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../src/particles.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAG7B,MAAM,WAAW,mBAAmB;IAClC;yCACqC;IACrC,MAAM,EAAE,YAAY,CAAA;IACpB;kFAC8E;IAC9E,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAaD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAW;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,SAAS,CAAiB;gBAGhC,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,SAAS,EACvB,OAAO,EAAE;QAAE,GAAG,EAAE,gBAAgB,CAAC;QAAC,IAAI,EAAE,gBAAgB,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;IAwD1G,gFAAgF;IAChF,IAAI,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAoFlD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAwBnD,OAAO,IAAI,IAAI;CAQhB"}