reze-engine 0.37.0 → 0.39.0

package/dist/particles.d.ts

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1 @@
+{"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"}

package/dist/particles.js

@@ -0,0 +1,183 @@
+// One-shot GPU particle emissions (model dissolve/materialize, hit sparks…).
+// Stateless by construction: emit() uploads static per-particle attributes
+// once, the vertex shader evaluates each particle's whole flight from the
+// elapsed time, and the emission frees itself when it expires. Zero per-frame
+// CPU work beyond a single time-uniform write shared by every emission.
+import { Vec3 } from "./math";
+import { PARTICLES_SHADER_WGSL } from "./shaders/passes/particles";
+/** Floats per particle: point.xyz, scatter.xyz, rand(delay, lifeScale, seed, sizeScale). */
+const PARTICLE_STRIDE = 10;
+export class ParticleSystem {
+    constructor(device, cameraBuffer, formats) {
+        this.timeData = new Float32Array(1);
+        this.emissions = [];
+        this.device = device;
+        this.cameraBuffer = cameraBuffer;
+        this.timeBuffer = device.createBuffer({
+            label: "particle time",
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.bindGroupLayout = device.createBindGroupLayout({
+            label: "particle bind group layout",
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                { binding: 2, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+            ],
+        });
+        const module = device.createShaderModule({ label: "particles", code: PARTICLES_SHADER_WGSL });
+        const additive = {
+            color: { srcFactor: "one", dstFactor: "one" },
+            alpha: { srcFactor: "one", dstFactor: "one" },
+        };
+        this.pipeline = device.createRenderPipeline({
+            label: "particle pipeline",
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] }),
+            vertex: {
+                module,
+                entryPoint: "vs_main",
+                buffers: [
+                    {
+                        arrayStride: PARTICLE_STRIDE * 4,
+                        stepMode: "instance",
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                            { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            { shaderLocation: 2, offset: 24, format: "float32x4" },
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module,
+                entryPoint: "fs_main",
+                targets: [
+                    { format: formats.hdr, blend: additive },
+                    { format: formats.mask, blend: additive },
+                ],
+            },
+            primitive: { topology: "triangle-list" },
+            // Occluded by the scene, never occluding: glitter reads as light, and
+            // light writing depth would punch holes into the transparent phase.
+            depthStencil: { format: formats.depth, depthWriteEnabled: false, depthCompare: "less-equal" },
+            multisample: { count: formats.sampleCount },
+        });
+    }
+    /** Upload one emission. `now` is the shared clock (seconds) draw() receives. */
+    emit(opts, now) {
+        const count = Math.floor(opts.points.length / 3);
+        if (count === 0)
+            return;
+        const mode = opts.mode === "converge" ? 1 : 0;
+        const duration = opts.duration ?? 1.6;
+        const color = opts.color ?? new Vec3(4.0, 3.0, 1.6);
+        const size = opts.size ?? 0.5;
+        const scatter = opts.scatter ?? 14;
+        const lift = opts.lift ?? 6;
+        const swirl = opts.swirl ?? 2;
+        // Delays stagger the front so the cloud dissolves as a sweep, and each
+        // particle's life fits delay + flight inside the emission's duration.
+        const data = new Float32Array(count * PARTICLE_STRIDE);
+        let cx = 0;
+        let cy = 0;
+        let cz = 0;
+        for (let i = 0; i < count; i++) {
+            const o = i * PARTICLE_STRIDE;
+            const px = opts.points[i * 3];
+            const py = opts.points[i * 3 + 1];
+            const pz = opts.points[i * 3 + 2];
+            cx += px;
+            cy += py;
+            cz += pz;
+            data[o] = px;
+            data[o + 1] = py;
+            data[o + 2] = pz;
+            // Random direction on the sphere, mildly flattened so the cloud spreads
+            // outward more than it dives into the floor.
+            const theta = Math.random() * Math.PI * 2;
+            const zr = Math.random() * 2 - 1;
+            const r = Math.sqrt(Math.max(0, 1 - zr * zr));
+            const dist = scatter * (0.35 + 0.65 * Math.random());
+            data[o + 3] = Math.cos(theta) * r * dist;
+            data[o + 4] = zr * 0.5 * dist;
+            data[o + 5] = Math.sin(theta) * r * dist;
+            const delay = Math.random() * duration * 0.3;
+            data[o + 6] = delay;
+            data[o + 7] = (duration - delay) / duration; // lifeScale: everyone lands inside duration
+            data[o + 8] = Math.random();
+            data[o + 9] = 0.5 + Math.random();
+        }
+        const particleBuffer = this.device.createBuffer({
+            label: "particle emission",
+            size: data.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(particleBuffer, 0, data);
+        const uni = new Float32Array(12);
+        uni[0] = color.x;
+        uni[1] = color.y;
+        uni[2] = color.z;
+        uni[3] = size;
+        uni[4] = cx / count;
+        uni[5] = cy / count;
+        uni[6] = cz / count;
+        uni[7] = mode;
+        uni[8] = now;
+        uni[9] = duration;
+        uni[10] = lift;
+        uni[11] = swirl;
+        const uniformBuffer = this.device.createBuffer({
+            label: "particle emission uniforms",
+            size: uni.byteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(uniformBuffer, 0, uni);
+        const bindGroup = this.device.createBindGroup({
+            label: "particle emission bind group",
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraBuffer } },
+                { binding: 1, resource: { buffer: uniformBuffer } },
+                { binding: 2, resource: { buffer: this.timeBuffer } },
+            ],
+        });
+        this.emissions.push({ particleBuffer, uniformBuffer, bindGroup, count, endTime: now + duration + 0.1 });
+    }
+    get active() {
+        return this.emissions.length > 0;
+    }
+    /** Record draws into the main pass (after the transparent phase). */
+    draw(pass, now) {
+        if (this.emissions.length === 0)
+            return;
+        const live = [];
+        let bound = false;
+        for (const e of this.emissions) {
+            if (now >= e.endTime) {
+                e.particleBuffer.destroy();
+                e.uniformBuffer.destroy();
+                continue;
+            }
+            if (!bound) {
+                this.timeData[0] = now;
+                this.device.queue.writeBuffer(this.timeBuffer, 0, this.timeData);
+                pass.setPipeline(this.pipeline);
+                bound = true;
+            }
+            pass.setBindGroup(0, e.bindGroup);
+            pass.setVertexBuffer(0, e.particleBuffer);
+            pass.draw(6, e.count);
+            live.push(e);
+        }
+        this.emissions = live;
+    }
+    dispose() {
+        for (const e of this.emissions) {
+            e.particleBuffer.destroy();
+            e.uniformBuffer.destroy();
+        }
+        this.emissions = [];
+        this.timeBuffer.destroy();
+    }
+}

package/dist/shaders/passes/particles.d.ts

@@ -0,0 +1,2 @@
+export declare const PARTICLES_SHADER_WGSL = "\nstruct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };\nstruct EmissionUniforms {\n  color: vec3f, size: f32,\n  centroidPos: vec3f, mode: f32,      // 0 = burst (point -> scatter), 1 = converge (scatter -> point)\n  startTime: f32, duration: f32, lift: f32, swirl: f32,\n};\nstruct TimeUniforms { now: f32, };\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> emission: EmissionUniforms;\n@group(0) @binding(2) var<uniform> timeU: TimeUniforms;\n\nstruct VSOut {\n  @builtin(position) position: vec4f,\n  @location(0) uv: vec2f,\n  @location(1) fade: f32,\n};\n\nfn easeOutCubic(t: f32) -> f32 { let u = 1.0 - t; return 1.0 - u * u * u; }\nfn easeInOut(t: f32) -> f32 { return t * t * (3.0 - 2.0 * t); }\n\n@vertex\nfn vs_main(\n  @builtin(vertex_index) vi: u32,\n  @location(0) point: vec3f,       // mesh anchor (spawn for burst, target for converge)\n  @location(1) scatter: vec3f,     // pre-scaled scatter offset at the far end\n  @location(2) rand: vec4f,        // delay, lifeScale, seed, sizeScale\n) -> VSOut {\n  var o: VSOut;\n  let elapsed = timeU.now - emission.startTime;\n  let life = max(emission.duration * rand.y, 1e-3);\n  let t = clamp((elapsed - rand.x) / life, 0.0, 1.0);\n\n  // Flight progress k runs point->scatter for burst, the reverse for converge;\n  // the whole cloud winds around its centroid as it goes.\n  var k: f32;\n  if (emission.mode < 0.5) { k = easeOutCubic(t); } else { k = 1.0 - easeInOut(t); }\n  let base = point + scatter * k + vec3f(0.0, emission.lift * k, 0.0);\n  let rel = base - emission.centroidPos;\n  let a = emission.swirl * k;\n  let c = cos(a);\n  let s = sin(a);\n  let world0 = emission.centroidPos + vec3f(rel.x * c + rel.z * s, rel.y, -rel.x * s + rel.z * c);\n\n  // Burst dies as it scatters; converge lights up fast and vanishes on arrival\n  // (the reveal underneath takes over).\n  var alpha: f32;\n  if (emission.mode < 0.5) {\n    alpha = (1.0 - t) * (1.0 - t);\n  } else {\n    alpha = min(t * 6.0, 1.0) * (1.0 - smoothstep(0.9, 1.0, t));\n  }\n  alpha *= 0.7 + 0.3 * sin(rand.z * 251.0 + elapsed * 24.0); // sparkle flicker\n  let alive = select(0.0, 1.0, elapsed >= rand.x && t < 1.0);\n\n  let size = emission.size * rand.w * (0.7 + 0.6 * (1.0 - t)) * alive;\n  // Camera-facing quad from the view matrix's right/up rows.\n  let right = vec3f(camera.view[0][0], camera.view[1][0], camera.view[2][0]);\n  let up = vec3f(camera.view[0][1], camera.view[1][1], camera.view[2][1]);\n  var corner = vec2f(-1.0, -1.0);\n  switch (vi) {\n    case 1u, 4u: { corner = vec2f(1.0, -1.0); }\n    case 2u, 3u: { corner = vec2f(-1.0, 1.0); }\n    case 5u: { corner = vec2f(1.0, 1.0); }\n    default: {}\n  }\n  let world = world0 + (right * corner.x + up * corner.y) * size;\n  o.position = camera.projection * camera.view * vec4f(world, 1.0);\n  o.uv = corner;\n  o.fade = alpha;\n  return o;\n}\n\nstruct FSOut {\n  @location(0) color: vec4f,\n  @location(1) mask: vec2f, // r = bloom mask, g = scene alpha (HDR has none)\n};\n\n@fragment\nfn fs_main(i: VSOut) -> FSOut {\n  let d2 = dot(i.uv, i.uv);\n  if (d2 > 1.0) { discard; }\n  var o: FSOut;\n  // Quadratic falloff to EXACT zero at the rim (a gaussian alone leaves a\n  // visible cutoff ring at the quad edge) with a hot bloom-feeding center.\n  let t = 1.0 - d2;\n  let core = t * t * (0.3 + 0.7 * exp(-d2 * 6.0));\n  let w = core * i.fade;\n  o.color = vec4f(emission.color * w, 0.0);\n  o.mask = vec2f(w, w);\n  return o;\n}\n";
+//# sourceMappingURL=particles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/particles.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,qBAAqB,88GA4FjC,CAAA"}

package/dist/shaders/passes/particles.js

@@ -0,0 +1,99 @@
+// Stateless one-shot particle pass: every particle's position at time t is a
+// pure function of its static per-instance attributes — no compute, no
+// ping-pong buffers, nothing to update per frame but one time uniform.
+// Draws additively into the HDR target inside the main pass (after the
+// transparent phase), writing bloom mask + alpha so the sparks glow through
+// the existing pyramid and survive the composite.
+export const PARTICLES_SHADER_WGSL = /* wgsl */ `
+struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };
+struct EmissionUniforms {
+  color: vec3f, size: f32,
+  centroidPos: vec3f, mode: f32,      // 0 = burst (point -> scatter), 1 = converge (scatter -> point)
+  startTime: f32, duration: f32, lift: f32, swirl: f32,
+};
+struct TimeUniforms { now: f32, };
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var<uniform> emission: EmissionUniforms;
+@group(0) @binding(2) var<uniform> timeU: TimeUniforms;
+
+struct VSOut {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) fade: f32,
+};
+
+fn easeOutCubic(t: f32) -> f32 { let u = 1.0 - t; return 1.0 - u * u * u; }
+fn easeInOut(t: f32) -> f32 { return t * t * (3.0 - 2.0 * t); }
+
+@vertex
+fn vs_main(
+  @builtin(vertex_index) vi: u32,
+  @location(0) point: vec3f,       // mesh anchor (spawn for burst, target for converge)
+  @location(1) scatter: vec3f,     // pre-scaled scatter offset at the far end
+  @location(2) rand: vec4f,        // delay, lifeScale, seed, sizeScale
+) -> VSOut {
+  var o: VSOut;
+  let elapsed = timeU.now - emission.startTime;
+  let life = max(emission.duration * rand.y, 1e-3);
+  let t = clamp((elapsed - rand.x) / life, 0.0, 1.0);
+
+  // Flight progress k runs point->scatter for burst, the reverse for converge;
+  // the whole cloud winds around its centroid as it goes.
+  var k: f32;
+  if (emission.mode < 0.5) { k = easeOutCubic(t); } else { k = 1.0 - easeInOut(t); }
+  let base = point + scatter * k + vec3f(0.0, emission.lift * k, 0.0);
+  let rel = base - emission.centroidPos;
+  let a = emission.swirl * k;
+  let c = cos(a);
+  let s = sin(a);
+  let world0 = emission.centroidPos + vec3f(rel.x * c + rel.z * s, rel.y, -rel.x * s + rel.z * c);
+
+  // Burst dies as it scatters; converge lights up fast and vanishes on arrival
+  // (the reveal underneath takes over).
+  var alpha: f32;
+  if (emission.mode < 0.5) {
+    alpha = (1.0 - t) * (1.0 - t);
+  } else {
+    alpha = min(t * 6.0, 1.0) * (1.0 - smoothstep(0.9, 1.0, t));
+  }
+  alpha *= 0.7 + 0.3 * sin(rand.z * 251.0 + elapsed * 24.0); // sparkle flicker
+  let alive = select(0.0, 1.0, elapsed >= rand.x && t < 1.0);
+
+  let size = emission.size * rand.w * (0.7 + 0.6 * (1.0 - t)) * alive;
+  // Camera-facing quad from the view matrix's right/up rows.
+  let right = vec3f(camera.view[0][0], camera.view[1][0], camera.view[2][0]);
+  let up = vec3f(camera.view[0][1], camera.view[1][1], camera.view[2][1]);
+  var corner = vec2f(-1.0, -1.0);
+  switch (vi) {
+    case 1u, 4u: { corner = vec2f(1.0, -1.0); }
+    case 2u, 3u: { corner = vec2f(-1.0, 1.0); }
+    case 5u: { corner = vec2f(1.0, 1.0); }
+    default: {}
+  }
+  let world = world0 + (right * corner.x + up * corner.y) * size;
+  o.position = camera.projection * camera.view * vec4f(world, 1.0);
+  o.uv = corner;
+  o.fade = alpha;
+  return o;
+}
+
+struct FSOut {
+  @location(0) color: vec4f,
+  @location(1) mask: vec2f, // r = bloom mask, g = scene alpha (HDR has none)
+};
+
+@fragment
+fn fs_main(i: VSOut) -> FSOut {
+  let d2 = dot(i.uv, i.uv);
+  if (d2 > 1.0) { discard; }
+  var o: FSOut;
+  // Quadratic falloff to EXACT zero at the rim (a gaussian alone leaves a
+  // visible cutoff ring at the quad edge) with a hot bloom-feeding center.
+  let t = 1.0 - d2;
+  let core = t * t * (0.3 + 0.7 * exp(-d2 * 6.0));
+  let w = core * i.fade;
+  o.color = vec4f(emission.color * w, 0.0);
+  o.mask = vec2f(w, w);
+  return o;
+}
+`;

package/dist/state-machine.d.ts

@@ -46,8 +46,12 @@ export declare class AnimationStateMachine {
     get state(): string;
     /** Seconds the current state has been active. */
     get stateTime(): number;
-    /** Force a transition now, regardless of the transition table. */
-    go(to: string, fade?: number): void;
+    /** Force a transition now, regardless of the transition table. `atTime`
+     *  enters the state with its clock already at that many seconds — for
+     *  handoffs that must continue a clip mid-flight (e.g. swapping model
+     *  skins mid-action: the new machine picks up exactly where the old
+     *  one's state stood). */
+    go(to: string, fade?: number, atTime?: number): void;
     update(dt: number): void;
     private transitionReady;
     private begin;

package/dist/state-machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAK7C,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;6EAEyE;IACzE,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,UAAU,EAAE,GAAG,IAAI,CAAA;IAC7C,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACvC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAA;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,OAAO,CAAA;IACpB;;;+BAG2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAQD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAEpC,OAAO,CAAC,OAAO,CAAa;IAC5B,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAyE;IAIvF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAE9B,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,WAAW,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,mBAAmB;IAW9H,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,iDAAiD;IACjD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,kEAAkE;IAClE,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAInC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAgCxB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,KAAK;IAYb;yEACqE;IACrE,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmD;IAC7E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmD;IAE9E;kDAC8C;IAC9C,OAAO,CAAC,KAAK;IAyBb,OAAO,CAAC,YAAY;CAIrB"}
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAK7C,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;6EAEyE;IACzE,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,UAAU,EAAE,GAAG,IAAI,CAAA;IAC7C,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACvC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAA;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,OAAO,CAAA;IACpB;;;+BAG2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAQD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAEpC,OAAO,CAAC,OAAO,CAAa;IAC5B,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAyE;IAIvF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAE9B,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,WAAW,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,mBAAmB;IAW9H,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,iDAAiD;IACjD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;8BAI0B;IAC1B,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAIpD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAgCxB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,KAAK;IAYb;yEACqE;IACrE,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmD;IAC7E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmD;IAE9E;kDAC8C;IAC9C,OAAO,CAAC,KAAK;IAyBb,OAAO,CAAC,YAAY;CAIrB"}

package/dist/state-machine.js

@@ -26,9 +26,13 @@ export class AnimationStateMachine {
     get stateTime() {
         return this.current.time;
     }
-    /** Force a transition now, regardless of the transition table. */
-    go(to, fade) {
-        this.begin(to, fade ?? this.defaultFade);
+    /** Force a transition now, regardless of the transition table. `atTime`
+     *  enters the state with its clock already at that many seconds — for
+     *  handoffs that must continue a clip mid-flight (e.g. swapping model
+     *  skins mid-action: the new machine picks up exactly where the old
+     *  one's state stood). */
+    go(to, fade, atTime) {
+        this.begin(to, fade ?? this.defaultFade, atTime);
     }
     update(dt) {
         this.current.time += dt;
@@ -79,7 +83,7 @@ export class AnimationStateMachine {
         }
         return true;
     }
-    begin(to, fade) {
+    begin(to, fade, atTime = 0) {
         const def = this.states[to];
         if (!def)
             throw new Error(`Unknown state "${to}"`);
@@ -88,7 +92,7 @@ export class AnimationStateMachine {
         // three-way mixes) — the current state becomes the outgoing one.
         this.fading = fade > 0 ? { state: this.current, elapsed: 0, duration: fade } : null;
         const from = this.current.name;
-        this.current = { name: to, def, time: 0 };
+        this.current = { name: to, def, time: atTime };
         def.onEnter?.(from);
     }
     /** This frame's entries for a state: clip states own a one-entry pose;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.37.0",
+  "version": "0.39.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,6 +5,7 @@ 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"
@@ -110,7 +111,8 @@ const PRESET_NAME_HINTS: Array<[MaterialPreset, string[]]> = [
       "带", // straps and bands: 头带/发带/背带/腰带
       "绳", // ropes: 背绳/腰绳
       "纱", // gauze/veils: 头纱
-      "肩布", // shoulder cloth/drape
+      "巾", // kerchiefs/scarves: 头巾/领巾/围巾
+      "布", // cloth panels: 肩布/腰布
       "背球", // back ornament sphere
       "腰花", // waist flower
       "花蕊", // flower pistil ornament
@@ -716,6 +718,8 @@ 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.
@@ -2909,6 +2913,33 @@ export class Engine {
   setCameraBeta(b: number): void {
     this.camera.beta = b
   }
+  /** Vertical field of view in radians (default π/4). While a camera VMD
+   *  drives the view it animates fov itself; the orbit value set here is
+   *  restored when the VMD releases the camera. */
+  getCameraFov(): number {
+    return this.camera.fov
+  }
+  setCameraFov(fov: number): void {
+    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() {
@@ -3065,6 +3096,8 @@ 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) {
@@ -3466,7 +3499,11 @@ export class Engine {
       } else if (verticesChanged) {
         inst.vertexBufferNeedsUpdate = true
       }
-      if (inst.physics && this.physicsEnabled) {
+      // Hidden models keep animating (cheap, and a reveal must not pop a stale
+      // pose) but skip cloth simulation entirely — a roster of resident
+      // alternate skins would otherwise pay full physics for invisible cloth.
+      // Hosts that reveal after long hiding reset physics anyway (resetPhysics).
+      if (inst.physics && this.physicsEnabled && inst.model.visible) {
         const tPhys = performance.now()
         inst.physics.step(deltaTime, inst.model.getWorldMatrices(), inst.model.getBoneInverseBindMatrices())
         physicsMs += performance.now() - tPhys
@@ -5102,6 +5139,9 @@ 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

@@ -57,6 +57,7 @@ export {
   MATERIAL_MORPH_MULTIPLY,
   MATERIAL_MORPH_ADD,
   type ClipEventInfo,
+  type RootMotionProfile,
   type Morph,
   type Morphing,
   type BoneMorphOffset,
@@ -97,4 +98,5 @@ export { VMDWriter } from "./vmd-writer"
 export { PmxLoader } from "./pmx-loader"
 export { CameraAnimation, type CameraPose } from "./camera-animation"
 export { RezePhysics } from "./physics"
-export type { WindOptions } from "./physics/world"
+export type { WindOptions } from "./physics/world"
+export { type ParticleEmitOptions } from "./particles"

package/src/locomotion.ts

@@ -291,6 +291,34 @@ export class LocomotionController {
     this.yaw = yaw
   }
 
+  /** Teleport PLUS a hard reset of every transient motion commitment: any
+   *  in-flight authored stop/turn (whose stored start position would otherwise
+   *  keep driving the root from where it began), the exit ghost, speed and
+   *  momentum, the heading-hold gate, and the held inputs. For handing the
+   *  root back after an externally-driven action (a root-motion clip state):
+   *  wherever the action ended is simply where she now stands. */
+  reset(x: number, y: number, z: number, yaw = 0): void {
+    this.position.setXYZ(x, y, z)
+    this.yaw = wrapAngle(yaw)
+    this.dirX = Math.sin(this.yaw)
+    this.dirZ = Math.cos(this.yaw)
+    this.speedLevel = 0
+    this.recentSpeed = 0
+    this.headingHold = 0
+    this.headingDirX = 0
+    this.headingDirY = 0
+    this.gaitPhase = 0
+    this.stopping = null
+    this.turning = null
+    this.runTurning = null
+    this.exitGhost = null
+    this.inputX = 0
+    this.inputY = 0
+    this.inputSprint = false
+    this.inputForward = 0
+    this.inputSteer = 0
+  }
+
   /** Strafe mode: hold the body at this world yaw (a camera forward, a lock-on target)
    *  while setMove's vector drives the directional strafe ring — requires
    *  clips.strafeRun. null returns to turn-toward-movement. */