reze-engine 0.56.5 → 0.56.7

package/src/engine.ts

@@ -30,7 +30,19 @@ import { LTC_MAG_LUT_SIZE, LTC_MAG_LUT_DATA } from "./shaders/ltc_mag_lut"
 import { SHADOW_DEPTH_SHADER_WGSL } from "./shaders/passes/shadow"
 import { ID_DEBUG_SHADER_WGSL } from "./shaders/passes/id-debug"
 import { paramChanged, sampleParamTrack, type ParamKey, type ParamValue } from "./param-track"
-import { effectState, type EffectWindow } from "./effect-schedule"
+import {
+  advanceSim,
+  DISSOLVE_PARAMS,
+  dissolveConstants,
+  dissolveCycleOf,
+  effectState,
+  sampleDissolveCycle,
+  scheduledDissolve,
+  type DissolveCycle,
+  type DissolveTimings,
+  type EffectWindow,
+  type SimClock,
+} from "./effect-schedule"
 import { parentKeySpan, type ModelParentKey } from "./parent-keys"
 import { SHADOW_CASCADES, buildShadowVP } from "./shadow-cascades"
 import { REFLECTION_DEBUG_WGSL, buildMirrorCamera, planeFromPointNormal } from "./reflection"
@@ -745,24 +757,8 @@ interface PickDrawCall {
   bindGroup: GPUBindGroup
 }
 
-/**
- * A repeating dissolve, in seconds within one cycle.
- *
- * Four moments rather than a duration and a delay: every one of them is a thing
- * you can see happen, and an author tuning this is watching for exactly those
- * four frames.
- */
-export interface DissolveCycle {
-  period: number
-  /** She starts to come apart. */
-  breakAt: number
-  /** Fully gone. */
-  hiddenAt: number
-  /** She starts to come back. */
-  backAt: number
-  /** Whole again. */
-  doneAt: number
-}
+/** Authored in effect-schedule, beside the evaluator that performs it. */
+export type { DissolveCycle }
 
 interface ModelInstance {
   name: string
@@ -1533,6 +1529,19 @@ interface EffectInstance {
    * is what makes a scheduled effect cost nothing outside its window.
    */
   weight: number
+  /** Where this effect's simulation stood last frame, while scheduled. See advanceSim. */
+  sim: SimClock
+  /** This frame's particle and grid step in seconds, from the transport. Read
+   *  only while the effect is scheduled; an unscheduled one steps by the render delta. */
+  simStep: number
+  /** Empty the particle pool and the grid before this frame's step. */
+  simReset: boolean
+  /**
+   * The four durations this effect's `#dissolve` takes the cast apart over, as
+   * its source wrote them. Null unless it declared one. A dial of the same name
+   * wins over the constant — see dissolveTimingsOf.
+   */
+  dissolve: DissolveTimings | null
   /** This effect's OWN clock, as a uniform the field shader reads. Per effect
    *  because the shared one (viewU[6].x) is measured from the first installed
    *  effect's epoch, so everything later started mid-stream. Null when the
@@ -4547,6 +4556,10 @@ export class Engine {
         influence: 1,
         window: null,
         weight: 1,
+        sim: { start: null, time: null },
+        simStep: 0,
+        simReset: false,
+        dissolve: d.dissolve ? dissolveConstants(authored) : null,
         // Its OWN resolution, no longer the scene's: an effect that never asked
         // for full res is not promoted because a neighbour did.
         // FULL RESOLUTION UNLESS TOLD OTHERWISE.
@@ -4823,10 +4836,11 @@ export class Engine {
     const renderModule = await compile(buildParticleRenderShader(src, cast), "particle render")
     if (Array.isArray(renderModule)) return { ok: false, diagnostics: renderModule }
 
+    // COPY_DST so a scheduled effect can empty its pool when its window starts.
     const buffer = this.device.createBuffer({
       label: "particle pool",
       size: count * PARTICLE_STRIDE,
-      usage: GPUBufferUsage.STORAGE,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
     })
     const uniform = this.device.createBuffer({
       label: "particle uniforms",
@@ -5092,6 +5106,14 @@ export class Engine {
     for (const e of this.effects) {
       const p = e.particles
       if (!p) continue
+      const scheduled = e.window !== null
+      // A scheduled pool that has not moved holds still: a paused transport, or
+      // a time outside every window. A dispatch at dt 0 would still run the
+      // author's step, and not every step is a function of dt.
+      if (scheduled && !e.simReset && e.simStep === 0) continue
+      // Entering its window, or going back in it: the pool starts empty, and
+      // every slot spawns on this dispatch from the effect's own local time.
+      if (e.simReset) encoder.clearBuffer(p.buffer)
       p.data[0] = this.sceneClock - e.epochScene
       // The SIMULATION runs at every weight, 0 included — only the draw stops.
       // A scheduled effect that froze while faded out would resume from the
@@ -5100,7 +5122,9 @@ export class Engine {
       p.data[4] = e.weight
       // Clamped: a backgrounded tab returns with a delta of whole seconds, and an
       // unclamped step flings every particle out of the scene in one frame.
-      p.data[1] = Math.min(0.1, Math.max(0, deltaTime))
+      // A scheduled effect steps by the transport instead, clamped the same way
+      // in advanceSim, so a pause freezes it and an export steps it exactly.
+      p.data[1] = scheduled ? e.simStep : Math.min(0.1, Math.max(0, deltaTime))
       p.counts[2] = p.count
       p.counts[3] = this.particleFrame++
       this.device.queue.writeBuffer(p.uniform, 0, p.data.buffer as ArrayBuffer)
@@ -5554,7 +5578,8 @@ export class Engine {
         label: `grid grid ${n}`,
         size: [size, size],
         format: SIM_FORMAT,
-        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+        // RENDER_ATTACHMENT so a scheduled effect can clear it when its window starts.
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
       })
     const textures: [GPUTexture, GPUTexture] = [make(0), make(1)]
     const read: [GPUTextureView, GPUTextureView] = [textures[0].createView(), textures[1].createView()]
@@ -5624,11 +5649,28 @@ export class Engine {
     for (const e of this.effects) {
     const grid = e.grid
     if (!grid) continue
+    const scheduled = e.window !== null
+    // Held still like the particles, for the same reason.
+    if (scheduled && !e.simReset && e.simStep === 0) continue
+    if (e.simReset) {
+      // Back to how install left it: both textures empty and frame 0 again,
+      // the frame an effect seeds its grid on.
+      for (const view of grid.read) {
+        encoder
+          .beginRenderPass({
+            label: "grid reset",
+            colorAttachments: [{ view, loadOp: "clear", storeOp: "store", clearValue: { r: 0, g: 0, b: 0, a: 0 } }],
+          })
+          .end()
+      }
+      grid.frame = 0
+      grid.parity = 0
+    }
     grid.data[0] = this.sceneClock - e.epochScene
     // Clamped like the particle step: a backgrounded tab returns with a delta of
     // whole seconds, and one unclamped step of an advection kernel throws the
     // whole grid off its own edge.
-    grid.data[1] = Math.min(0.1, Math.max(0, deltaTime))
+    grid.data[1] = scheduled ? e.simStep : Math.min(0.1, Math.max(0, deltaTime))
     grid.data[2] = grid.size
     grid.data[3] = grid.frame++
     this.device.queue.writeBuffer(grid.uniform, 0, grid.data.buffer as ArrayBuffer)
@@ -5727,6 +5769,11 @@ export class Engine {
     const fx = this.effects[index]
     if (!fx) return
     fx.window = windows && windows.length ? windows : null
+    // Unscheduled forgets where its simulation stood. A changed lane keeps it:
+    // advanceSim restarts the pool only if the window the transport is in now
+    // starts somewhere else, so trimming a block, or turning the influence
+    // that is sent with every lane, does not restart a burst mid-flight.
+    if (!fx.window) fx.sim = { start: null, time: null }
   }
 
   getEffectSchedule(index: number): readonly EffectWindow[] | null {
@@ -5745,12 +5792,20 @@ export class Engine {
     // Read ONCE: it walks the cast, and every effect wants the same answer.
     const transport = this.transportTime()
     for (const fx of this.effects) {
+      fx.simReset = false
       if (!fx.window || fx.window.length === 0) {
         fx.weight = fx.influence
         continue
       }
       const at = effectState(fx.window, fx.influence, transport)
       fx.weight = at.weight
+      // The particles and the grid carry state from frame to frame, so they get
+      // more than a clock: a restart on entering a window or going back in one,
+      // and a step measured on the transport. See advanceSim.
+      const sim = advanceSim(fx.sim, fx.window, transport)
+      fx.sim = sim.clock
+      fx.simStep = sim.step
+      fx.simReset = sim.reset
       // Its own clock, expressed the way the mounts read it. Every mount
       // derives time from the epoch against sceneClock, so this one write moves
       // the field, the particles, the ribbons, lightEmit and the grid together
@@ -14338,6 +14393,9 @@ export class Engine {
       if (pose) this.camera.setVmdPose(pose)
     }
 
+    // Before the cast is written, which carries every subject's dissolve to the
+    // effects reading it.
+    this.evaluateDissolves()
     this.updateCameraUniforms()
     this.updateShadowLightVP()
 
@@ -14479,7 +14537,6 @@ export class Engine {
     // and a grid stepped after them is one frame stale in everything that used it.
     // Material parameters on the scene clock, before anything reads their
     // uniforms this frame.
-    this.evaluateDissolveCycles()
     this.evaluateParamTracks()
     // FIRST among the things that read an effect, because every one of them
     // reads what this writes: the sim's clock, the particle uniform's weight,
@@ -14960,22 +15017,6 @@ export class Engine {
     return true
   }
 
-  /**
-   * A repeating dissolve, on the scene clock.
-   *
-   * The alternative was a host calling setModelDissolve every frame, and it is
-   * the wrong shape twice: an exported take stepped at another rate would land
-   * on different values than the preview did, and the effect drawing the sparks
-   * would be reading a number some other clock wrote. Here the engine samples it
-   * where it samples everything else time-driven, so a take reproduces exactly
-   * and rzSubject().dissolve is the same value the material shell used on that
-   * very frame.
-   *
-   * The five numbers are seconds within one cycle: when she starts to go, when
-   * she is fully gone, when she starts to come back, and when she is whole. The
-   * gaps between them are the timing, and the hold between the middle two is how
-   * long she is away.
-   */
   /**
    * Eyes on the camera, per model — see Model.setEyeTracking. Live: solved
    * every frame against wherever the camera is, orbit or motion alike. Null
@@ -14988,6 +15029,20 @@ export class Engine {
     return true
   }
 
+  /**
+   * A repeating dissolve on one model, on the scene clock.
+   *
+   * The alternative was a host calling setModelDissolve every frame, and it is
+   * the wrong shape twice: an exported take stepped at another rate would land
+   * on different values than the preview did, and the effect drawing the sparks
+   * would be reading a number some other clock wrote. Here the engine samples it
+   * where it samples everything else time-driven, so a take reproduces exactly
+   * and rzSubject().dissolve is the same value the material shell used on that
+   * very frame.
+   *
+   * An effect that declares `#dissolve` needs none of this: it carries its own
+   * cycle and follows its own clips — see evaluateDissolves.
+   */
   setModelDissolveCycle(modelName: string, cycle: DissolveCycle | null): boolean {
     if (!this.modelInstances.has(modelName)) return false
     if (!cycle) {
@@ -14998,23 +15053,65 @@ export class Engine {
     return true
   }
 
-  /** Every dissolve cycle, at the current scene clock. Once per frame, before
-   *  the cast is written and long before any effect reads it. */
-  private evaluateDissolveCycles(): void {
-    if (this.dissolveCycles.size === 0) return
-    for (const [name, c] of this.dissolveCycles) {
-      const period = Math.max(c.period, 1e-3)
-      const t = this.sceneClock - Math.floor(this.sceneClock / period) * period
-      let v = 1
-      if (t >= c.breakAt && t < c.hiddenAt) {
-        v = 1 - (t - c.breakAt) / Math.max(c.hiddenAt - c.breakAt, 1e-4)
-      } else if (t >= c.hiddenAt && t < c.backAt) {
-        v = 0
-      } else if (t >= c.backAt && t < c.doneAt) {
-        v = (t - c.backAt) / Math.max(c.doneAt - c.backAt, 1e-4)
+  /** The model at one cast slot — the subject rzSubject(index) reads. */
+  private castSubjectName(index: number): string | null {
+    let n = 0
+    let found: string | null = null
+    this.forEachInstance((inst) => {
+      if (found !== null || n >= MAX_EFFECT_SUBJECTS || inst.isStage || inst.isPlane || inst.isProp) return
+      if (n === index) found = inst.name
+      n++
+    })
+    return found
+  }
+
+  /** One effect's four durations: its dials where it declares them, the
+   *  constants it wrote where it does not. */
+  private dissolveTimingsOf(fx: EffectInstance, wrote: DissolveTimings): DissolveTimings {
+    const t = { ...wrote }
+    for (const [key, name] of DISSOLVE_PARAMS) {
+      const slot = fx.paramLayout.get(name)
+      if (slot) t[key] = Math.max(0, fx.paramsData[slot.offset])
+    }
+    return t
+  }
+
+  /** Models this wrote a dissolve onto last frame, so one nothing asks for any
+   *  more comes back whole instead of holding wherever it was left. */
+  private dissolveTouched = new Set<string>()
+
+  /**
+   * Every dissolve, once a frame, before the cast is written — so the value a
+   * mote reads as rzSubject(i).dissolve is the one her materials wore on that
+   * very frame, rather than the one they wore on the last.
+   *
+   * Two things ask for one. A cycle set on a model (setModelDissolveCycle) runs
+   * on the scene clock and repeats, as it always has. An effect declaring
+   * `#dissolve` takes subject 0 apart on ITS OWN terms: scheduled, the cycle on
+   * each clip's clock with her whole between clips; unscheduled, the same
+   * repeating cycle as before. Where both ask, the more dissolved wins — two
+   * answers about one body, and half a body is not one of them.
+   */
+  private evaluateDissolves(): void {
+    const want = new Map<string, number>()
+    const put = (name: string, v: number) => want.set(name, Math.min(want.get(name) ?? 1, v))
+    for (const [name, c] of this.dissolveCycles) put(name, sampleDissolveCycle(c, this.sceneClock))
+    let transport: number | null = null
+    for (const fx of this.effects) {
+      if (!fx.dissolve) continue
+      const cycle = dissolveCycleOf(this.dissolveTimingsOf(fx, fx.dissolve))
+      const subject = this.castSubjectName(0)
+      if (!cycle || !subject) continue
+      if (fx.window && fx.window.length > 0) {
+        transport ??= this.transportTime()
+        put(subject, scheduledDissolve(fx.window, cycle, transport))
+      } else {
+        put(subject, sampleDissolveCycle(cycle, this.sceneClock))
       }
-      this.setModelDissolve(name, v)
     }
+    for (const name of this.dissolveTouched) if (!want.has(name)) this.setModelDissolve(name, 1)
+    this.dissolveTouched = new Set(want.keys())
+    for (const [name, v] of want) this.setModelDissolve(name, v)
   }
 
   /** What setModelDissolve last set, or 1 for a model that has never dissolved. */

package/src/index.ts

@@ -39,7 +39,15 @@ export { sampleParamTrack, type ParamKey, type ParamValue } from "./param-track"
 // The strip an effect is scheduled by, and the pure evaluator behind it —
 // exported so a caller can draw a lane against the same numbers the engine
 // renders from, rather than a second copy of the ramp maths.
-export { effectState, type EffectWindow, type EffectState } from "./effect-schedule"
+export {
+  activeWindow,
+  advanceSim,
+  effectState,
+  SIM_MAX_STEP,
+  type EffectWindow,
+  type EffectState,
+  type SimClock,
+} from "./effect-schedule"
 // Who a model hangs from over time, and the lookup behind it — exported so a
 // timeline draws its holds from the same rule the engine switches by.
 export { parentKeyIndex, type ModelParentKey } from "./parent-keys"