@jgengine/shell 0.8.0 → 0.10.0

package/dist/audio/musicVoices.js

@@ -0,0 +1,338 @@
+import { mtof } from "@jgengine/core/audio/music";
+function adsr(ctx, when, dur, peak, attack, release) {
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(peak, when + attack);
+    g.gain.setValueAtTime(peak, Math.max(when + attack, when + dur - release));
+    g.gain.exponentialRampToValueAtTime(0.0001, when + dur + release);
+    return g;
+}
+function stack(ctx, when, freq, dur, out, type, dets, tail) {
+    for (const det of dets) {
+        const o = ctx.createOscillator();
+        o.type = type;
+        o.frequency.value = freq;
+        o.detune.value = det;
+        o.connect(out);
+        o.start(when);
+        o.stop(when + dur + tail);
+    }
+}
+function strings(ctx, when, freq, dur, vel, out, attack = 0.3) {
+    const g = adsr(ctx, when, dur, vel * 0.16, attack, 0.7);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 750 + freq * 2;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-6, 5], 0.9);
+}
+function pad(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.11, 0.6, 1.1);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 520 + freq * 1.4;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-9, -3, 4, 10], 1.2);
+}
+function reed(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.14, 0.08, 0.25);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 1600 + freq;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-3, 4], 0.35);
+}
+function horn(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.15, 0.09, 0.3);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 900 + freq * 1.5;
+    lp.Q.value = 0.6;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "sawtooth", [-4, 3], 0.4);
+    const sub = ctx.createOscillator();
+    sub.type = "sine";
+    sub.frequency.value = freq;
+    const sg = ctx.createGain();
+    sg.gain.value = 0.4;
+    sub.connect(sg).connect(lp);
+    sub.start(when);
+    sub.stop(when + dur + 0.4);
+}
+function brassStab(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, Math.min(dur, 0.4), vel * 0.17, 0.02, 0.14);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 1400 + freq * 2;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, Math.min(dur, 0.4), lp, "sawtooth", [-5, 6], 0.2);
+}
+function flute(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.15, 0.06, 0.2);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2600;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = "sine";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + dur + 0.25);
+    const breath = ctx.createBufferSource();
+    const len = Math.floor(ctx.sampleRate * Math.min(dur, 0.4));
+    const buf = ctx.createBuffer(1, len, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < len; i += 1)
+        data[i] = (Math.random() * 2 - 1) * 0.5;
+    breath.buffer = buf;
+    const bp = ctx.createBiquadFilter();
+    bp.type = "bandpass";
+    bp.frequency.value = freq * 2;
+    const bg = ctx.createGain();
+    bg.gain.value = vel * 0.02;
+    breath.connect(bp).connect(bg).connect(out);
+    breath.start(when);
+}
+function pipe(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.13, 0.03, 0.15);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 3000;
+    lp.connect(g).connect(out);
+    stack(ctx, when, freq, dur, lp, "triangle", [0, 7], 0.2);
+}
+function squareLead(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.1, 0.02, 0.12);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2200 + freq;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = "square";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + dur + 0.2);
+}
+function choir(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.12, 0.25, 0.6);
+    const formant = ctx.createBiquadFilter();
+    formant.type = "bandpass";
+    formant.frequency.value = Math.min(1800, 500 + freq * 1.6);
+    formant.Q.value = 0.7;
+    formant.connect(g).connect(out);
+    stack(ctx, when, freq, dur, formant, "sawtooth", [-8, -2, 6], 0.8);
+    stack(ctx, when, freq * 2, dur, formant, "triangle", [3], 0.8);
+}
+function oboe(ctx, when, freq, dur, vel, out) {
+    const g = adsr(ctx, when, dur, vel * 0.17, 0.055, 0.22);
+    const formant = ctx.createBiquadFilter();
+    formant.type = "bandpass";
+    formant.frequency.value = Math.min(2400, 600 + freq * 2.2);
+    formant.Q.value = 0.9;
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = 2800;
+    formant.connect(lp).connect(g).connect(out);
+    const vib = ctx.createOscillator();
+    vib.frequency.value = 5.2;
+    const vibGain = ctx.createGain();
+    vibGain.gain.setValueAtTime(0, when);
+    vibGain.gain.linearRampToValueAtTime(freq * 0.004, when + 0.3);
+    vib.connect(vibGain);
+    for (const det of [-5, 4]) {
+        const o = ctx.createOscillator();
+        o.type = "sawtooth";
+        o.frequency.value = freq;
+        o.detune.value = det;
+        vibGain.connect(o.frequency);
+        o.connect(formant);
+        o.start(when);
+        o.stop(when + dur + 0.4);
+    }
+    vib.start(when);
+    vib.stop(when + dur + 0.4);
+}
+function pluck(ctx, when, freq, vel, out, decay, bassy = false) {
+    const g = ctx.createGain();
+    const peak = vel * (bassy ? 0.26 : 0.2);
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(peak, when + 0.004);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + decay);
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = bassy ? 900 : 2600 + freq;
+    lp.connect(g).connect(out);
+    const o = ctx.createOscillator();
+    o.type = bassy ? "triangle" : "sawtooth";
+    o.frequency.value = freq;
+    o.connect(lp);
+    o.start(when);
+    o.stop(when + decay + 0.1);
+    if (!bassy) {
+        const o2 = ctx.createOscillator();
+        o2.type = "triangle";
+        o2.frequency.value = freq * 2.001;
+        const g2 = ctx.createGain();
+        g2.gain.setValueAtTime(peak * 0.4, when);
+        g2.gain.exponentialRampToValueAtTime(0.0001, when + decay * 0.6);
+        o2.connect(g2).connect(out);
+        o2.start(when);
+        o2.stop(when + decay);
+    }
+}
+function bell(ctx, when, freq, vel, out, decay = 1.8) {
+    for (const [ratio, amp] of [[1, 1], [2.76, 0.5], [5.4, 0.25], [8.9, 0.12]]) {
+        const g = ctx.createGain();
+        g.gain.setValueAtTime(0.0001, when);
+        g.gain.linearRampToValueAtTime(vel * 0.14 * amp, when + 0.005);
+        g.gain.exponentialRampToValueAtTime(0.0001, when + decay * (1 - (ratio - 1) * 0.06));
+        const o = ctx.createOscillator();
+        o.type = "sine";
+        o.frequency.value = freq * ratio;
+        o.connect(g).connect(out);
+        o.start(when);
+        o.stop(when + decay + 0.2);
+    }
+}
+function piano(ctx, when, freq, dur, vel, out) {
+    const naturalDecay = Math.min(5.2, Math.max(1.2, 380 / freq));
+    const body = ctx.createBiquadFilter();
+    body.type = "lowpass";
+    body.frequency.value = Math.min(5600, 1400 + freq * 4);
+    body.Q.value = 0.35;
+    body.connect(out);
+    const partials = [
+        [1, 0.62, 1, -3],
+        [1.0005, 0.62, 1, 3],
+        [2.003, 0.5, 0.58, 2],
+        [3.006, 0.2, 0.36, -4],
+        [4.012, 0.09, 0.24, 5],
+        [5.02, 0.05, 0.17, -6],
+        [7.03, 0.025, 0.12, 4],
+    ];
+    for (const [ratio, amp, decayMul, cents] of partials) {
+        const decay = Math.min(naturalDecay * decayMul, dur + 0.35);
+        const g = ctx.createGain();
+        const peak = vel * 0.24 * amp;
+        g.gain.setValueAtTime(0.0001, when);
+        g.gain.linearRampToValueAtTime(peak, when + 0.004);
+        g.gain.exponentialRampToValueAtTime(0.0001, when + Math.max(0.14, decay));
+        const o = ctx.createOscillator();
+        o.type = ratio < 1.01 ? "triangle" : "sine";
+        o.frequency.value = freq * ratio;
+        o.detune.value = cents;
+        o.connect(g).connect(body);
+        o.start(when);
+        o.stop(when + Math.max(0.14, decay) + 0.1);
+    }
+}
+function noiseHit(ctx, when, vel, out, hp, len, curve) {
+    const n = Math.floor(ctx.sampleRate * len);
+    const buf = ctx.createBuffer(1, n, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < n; i += 1)
+        data[i] = (Math.random() * 2 - 1) * (1 - i / n) ** curve;
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const f = ctx.createBiquadFilter();
+    f.type = "highpass";
+    f.frequency.value = hp;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.22, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + len);
+    src.connect(f).connect(g).connect(out);
+    src.start(when);
+}
+function drum(ctx, when, freq, vel, out, decay, punch) {
+    const o = ctx.createOscillator();
+    o.type = "sine";
+    o.frequency.setValueAtTime(freq * punch, when);
+    o.frequency.exponentialRampToValueAtTime(freq, when + 0.06);
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.5, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + decay);
+    o.connect(g).connect(out);
+    o.start(when);
+    o.stop(when + decay + 0.05);
+    noiseHit(ctx, when, vel * 0.4, out, 200, Math.min(decay, 0.12), 2);
+}
+function woodBlock(ctx, when, vel, out) {
+    const o = ctx.createOscillator();
+    o.type = "square";
+    o.frequency.value = 1100;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(vel * 0.2, when);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + 0.05);
+    const bp = ctx.createBiquadFilter();
+    bp.type = "bandpass";
+    bp.frequency.value = 1100;
+    o.connect(bp).connect(g).connect(out);
+    o.start(when);
+    o.stop(when + 0.07);
+}
+function cymSwell(ctx, when, dur, vel, out) {
+    const n = Math.floor(ctx.sampleRate * (dur + 0.3));
+    const buf = ctx.createBuffer(1, n, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < n; i += 1)
+        data[i] = Math.random() * 2 - 1;
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const hp = ctx.createBiquadFilter();
+    hp.type = "highpass";
+    hp.frequency.value = 6000;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0.0001, when);
+    g.gain.linearRampToValueAtTime(vel * 0.1, when + dur);
+    g.gain.exponentialRampToValueAtTime(0.0001, when + dur + 0.3);
+    src.connect(hp).connect(g).connect(out);
+    src.start(when);
+}
+/**
+ * Play one theme note through its instrument voice into `out` (a per-layer gain
+ * node the director wires to master + reverb). `spb` is seconds-per-beat and
+ * `transpose` shifts the note in semitones for per-zone key changes. This is the
+ * engine's reusable instrument library; unknown instruments fall back to a sine.
+ */
+export function playMusicNote(ctx, event, when, spb, out, transpose = 0) {
+    const freq = mtof(event.midi + transpose);
+    const dur = Math.max(0.1, event.dur * spb);
+    const vel = event.vel;
+    const inst = event.inst;
+    switch (inst) {
+        case "strings": return strings(ctx, when, freq, dur, vel, out);
+        case "stacc": return strings(ctx, when, freq, Math.min(dur, 0.22), vel, out, 0.02);
+        case "pad": return pad(ctx, when, freq, dur, vel, out);
+        case "reed": return reed(ctx, when, freq, dur, vel, out);
+        case "horn": return horn(ctx, when, freq, dur, vel, out);
+        case "brassStab": return brassStab(ctx, when, freq, dur, vel, out);
+        case "flute": return flute(ctx, when, freq, dur, vel, out);
+        case "pipe": return pipe(ctx, when, freq, dur, vel, out);
+        case "squareLead": return squareLead(ctx, when, freq, dur, vel, out);
+        case "choir": return choir(ctx, when, freq, dur, vel, out);
+        case "oboe": return oboe(ctx, when, freq, dur, vel, out);
+        case "harp": return pluck(ctx, when, freq, vel, out, 1.4);
+        case "lute": return pluck(ctx, when, freq, vel, out, 0.7);
+        case "dulcimer": return pluck(ctx, when, freq, vel, out, 1.0);
+        case "bass": return pluck(ctx, when, freq, vel, out, 0.9, true);
+        case "bell": return bell(ctx, when, freq, vel, out);
+        case "tinyBell": return bell(ctx, when, freq, vel, out, 0.7);
+        case "piano": return piano(ctx, when, freq, dur, vel, out);
+        case "timpani": return drum(ctx, when, freq, vel, out, 0.6, 1.5);
+        case "warDrum": return drum(ctx, when, Math.max(50, freq * 0.5), vel, out, 0.35, 1.8);
+        case "frameDrum": return drum(ctx, when, Math.max(70, freq * 0.6), vel, out, 0.25, 1.6);
+        case "shaker": return noiseHit(ctx, when, vel, out, 6800, 0.055, 1.8);
+        case "woodBlock": return woodBlock(ctx, when, vel, out);
+        case "cymSwell": return cymSwell(ctx, when, dur, vel, out);
+        default: {
+            const o = ctx.createOscillator();
+            o.frequency.value = freq;
+            const g = adsr(ctx, when, dur, vel * 0.12, 0.02, 0.2);
+            o.connect(g).connect(out);
+            o.start(when);
+            o.stop(when + dur + 0.3);
+        }
+    }
+}

package/dist/audio/synthEngine.d.ts

@@ -0,0 +1,9 @@
+import type { SynthPatch } from "@jgengine/core/audio/synth";
+/** Build the shared 1-second mono white-noise buffer every noise voice samples from. */
+export declare function createNoiseBuffer(ctx: BaseAudioContext): AudioBuffer;
+/**
+ * Realise a procedural cue on Web Audio: every voice is scheduled at
+ * `ctx.currentTime + delay` into `out`, summed into one one-shot. `noiseBuf` is
+ * the shared buffer from {@link createNoiseBuffer}.
+ */
+export declare function realizeSynthPatch(ctx: BaseAudioContext, out: AudioNode, noiseBuf: AudioBuffer, patch: SynthPatch): void;

package/dist/audio/synthEngine.js

@@ -0,0 +1,57 @@
+/** Build the shared 1-second mono white-noise buffer every noise voice samples from. */
+export function createNoiseBuffer(ctx) {
+    const len = Math.floor(ctx.sampleRate);
+    const buf = ctx.createBuffer(1, len, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < len; i += 1)
+        data[i] = Math.random() * 2 - 1;
+    return buf;
+}
+function realizeTone(ctx, out, voice, cueGain, at) {
+    const t = at + (voice.delay ?? 0);
+    const peak = (voice.gain ?? 1) * cueGain;
+    const attack = voice.attack ?? 0.012;
+    const osc = ctx.createOscillator();
+    osc.type = voice.wave ?? "sine";
+    osc.frequency.setValueAtTime(voice.freq, t);
+    if (voice.slideTo !== undefined)
+        osc.frequency.exponentialRampToValueAtTime(Math.max(1, voice.slideTo), t + voice.duration);
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(0, t);
+    g.gain.linearRampToValueAtTime(peak, t + attack);
+    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration);
+    osc.connect(g).connect(out);
+    osc.start(t);
+    osc.stop(t + voice.duration + 0.05);
+}
+function realizeNoise(ctx, out, noiseBuf, voice, cueGain, at) {
+    const t = at + (voice.delay ?? 0);
+    const peak = (voice.gain ?? 1) * cueGain;
+    const decay = voice.decay ?? 0.9;
+    const src = ctx.createBufferSource();
+    src.buffer = noiseBuf;
+    src.playbackRate.value = 0.8 + Math.random() * 0.4;
+    const filter = ctx.createBiquadFilter();
+    filter.type = voice.filterType ?? "lowpass";
+    filter.frequency.value = voice.filterFreq;
+    const g = ctx.createGain();
+    g.gain.setValueAtTime(peak, t);
+    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration * decay);
+    src.connect(filter).connect(g).connect(out);
+    src.start(t, Math.random() * 0.5, voice.duration);
+}
+/**
+ * Realise a procedural cue on Web Audio: every voice is scheduled at
+ * `ctx.currentTime + delay` into `out`, summed into one one-shot. `noiseBuf` is
+ * the shared buffer from {@link createNoiseBuffer}.
+ */
+export function realizeSynthPatch(ctx, out, noiseBuf, patch) {
+    const cueGain = patch.gain ?? 1;
+    const at = ctx.currentTime;
+    for (const voice of patch.voices) {
+        if (voice.kind === "tone")
+            realizeTone(ctx, out, voice, cueGain, at);
+        else
+            realizeNoise(ctx, out, noiseBuf, voice, cueGain, at);
+    }
+}

package/dist/behaviour.d.ts

@@ -1,29 +1,10 @@
-import type { Object3D } from "three";
-import { Behaviour, type BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
-/**
- * A core `Behaviour` bound to a three.js object. `onBeforeRender`/`onAfterRender`
- * ride the object's own three.js render callbacks, so they only fire for renderable
- * objects (Mesh, Line, Points, Sprite) that are visible and in frustum — attach to
- * the mesh itself, not a parent Group, when you need them.
- */
-export declare class Object3DBehaviour extends Behaviour {
-    /** @internal */ _object: Object3D | null;
-    /** The bound three.js object; available from `onAwake` onward. */
-    get object(): Object3D;
-    onBeforeRender(): void;
-    onAfterRender(): void;
-}
-/**
- * Binds `behaviour` to `object` and attaches it to `world` under `nodeId`
- * (default: the object's uuid). Render hooks are chained onto the object's
- * existing `onBeforeRender`/`onAfterRender` only when actually overridden, and
- * are gated on the behaviour being active; the update lifecycle still flows
- * through `world.update`.
- */
-export declare function attachObject3D<T extends Object3DBehaviour>(world: BehaviourWorld, object: Object3D, behaviour: T, nodeId?: string): T;
+import type { BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+export { createBehaviourWorldDriver } from "./behaviourDriver.js";
+export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
 /**
  * Bootstraps `world` on mount and dispatches `world.update` every frame at
- * simulation priority. `scaleDt` maps the raw frame delta to the dt behaviours
+ * simulation priority. Stops driving updates on unmount so remount does not
+ * double-step. `scaleDt` maps the raw frame delta to the dt behaviours
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.

package/dist/behaviour.js

@@ -1,63 +1,27 @@
 import { useFrame } from "@react-three/fiber";
-import { useEffect } from "react";
-import { Behaviour } from "@jgengine/core/behaviour/behaviour";
-/**
- * A core `Behaviour` bound to a three.js object. `onBeforeRender`/`onAfterRender`
- * ride the object's own three.js render callbacks, so they only fire for renderable
- * objects (Mesh, Line, Points, Sprite) that are visible and in frustum — attach to
- * the mesh itself, not a parent Group, when you need them.
- */
-export class Object3DBehaviour extends Behaviour {
-    /** @internal */ _object = null;
-    /** The bound three.js object; available from `onAwake` onward. */
-    get object() {
-        if (this._object === null)
-            throw new Error("behaviour is not bound to an Object3D");
-        return this._object;
-    }
-    onBeforeRender() { }
-    onAfterRender() { }
-}
-/**
- * Binds `behaviour` to `object` and attaches it to `world` under `nodeId`
- * (default: the object's uuid). Render hooks are chained onto the object's
- * existing `onBeforeRender`/`onAfterRender` only when actually overridden, and
- * are gated on the behaviour being active; the update lifecycle still flows
- * through `world.update`.
- */
-export function attachObject3D(world, object, behaviour, nodeId = object.uuid) {
-    behaviour._object = object;
-    world.attach(nodeId, behaviour);
-    if (behaviour.onBeforeRender !== Object3DBehaviour.prototype.onBeforeRender) {
-        const previous = object.onBeforeRender;
-        object.onBeforeRender = function chainedBeforeRender(...args) {
-            previous.apply(this, args);
-            if (behaviour.isActive)
-                behaviour.onBeforeRender();
-        };
-    }
-    if (behaviour.onAfterRender !== Object3DBehaviour.prototype.onAfterRender) {
-        const previous = object.onAfterRender;
-        object.onAfterRender = function chainedAfterRender(...args) {
-            previous.apply(this, args);
-            if (behaviour.isActive)
-                behaviour.onAfterRender();
-        };
-    }
-    return behaviour;
-}
+import { useEffect, useRef } from "react";
+import { createBehaviourWorldDriver } from "./behaviourDriver.js";
+export { createBehaviourWorldDriver } from "./behaviourDriver.js";
+export { attachObject3D, Object3DBehaviour } from "./behaviourAttach.js";
 /**
  * Bootstraps `world` on mount and dispatches `world.update` every frame at
- * simulation priority. `scaleDt` maps the raw frame delta to the dt behaviours
+ * simulation priority. Stops driving updates on unmount so remount does not
+ * double-step. `scaleDt` maps the raw frame delta to the dt behaviours
  * receive — pass the game clock's scaling to keep behaviours on game time, or
  * omit for real-time seconds. Games driving `world.update` themselves from
  * `loop.onTick` should not also render this.
  */
 export function useBehaviourWorld(world, scaleDt) {
+    const driverRef = useRef(createBehaviourWorldDriver(world));
     useEffect(() => {
-        world.start();
+        const driver = createBehaviourWorldDriver(world);
+        driverRef.current = driver;
+        driver.start();
+        return () => {
+            driver.stop();
+        };
     }, [world]);
     useFrame((_state, rawDt) => {
-        world.update(scaleDt === undefined ? rawDt : scaleDt(rawDt));
+        driverRef.current.step(scaleDt === undefined ? rawDt : scaleDt(rawDt));
     });
 }

package/dist/behaviourAttach.d.ts

@@ -0,0 +1,9 @@
+import type { Object3D } from "three";
+import { Behaviour, type BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+export declare class Object3DBehaviour extends Behaviour {
+    /** @internal */ _object: Object3D | null;
+    get object(): Object3D;
+    onBeforeRender(): void;
+    onAfterRender(): void;
+}
+export declare function attachObject3D<T extends Object3DBehaviour>(world: BehaviourWorld, object: Object3D, behaviour: T, nodeId?: string): T;

package/dist/behaviourAttach.js

@@ -0,0 +1,32 @@
+import { Behaviour } from "@jgengine/core/behaviour/behaviour";
+export class Object3DBehaviour extends Behaviour {
+    /** @internal */ _object = null;
+    get object() {
+        if (this._object === null)
+            throw new Error("behaviour is not bound to an Object3D");
+        return this._object;
+    }
+    onBeforeRender() { }
+    onAfterRender() { }
+}
+export function attachObject3D(world, object, behaviour, nodeId = object.uuid) {
+    behaviour._object = object;
+    world.attach(nodeId, behaviour);
+    if (behaviour.onBeforeRender !== Object3DBehaviour.prototype.onBeforeRender) {
+        const previous = object.onBeforeRender;
+        object.onBeforeRender = function chainedBeforeRender(...args) {
+            previous.apply(this, args);
+            if (behaviour.isActive)
+                behaviour.onBeforeRender();
+        };
+    }
+    if (behaviour.onAfterRender !== Object3DBehaviour.prototype.onAfterRender) {
+        const previous = object.onAfterRender;
+        object.onAfterRender = function chainedAfterRender(...args) {
+            previous.apply(this, args);
+            if (behaviour.isActive)
+                behaviour.onAfterRender();
+        };
+    }
+    return behaviour;
+}

package/dist/behaviourDriver.d.ts

@@ -0,0 +1,7 @@
+import type { BehaviourWorld } from "@jgengine/core/behaviour/behaviour";
+export declare function createBehaviourWorldDriver(world: BehaviourWorld): {
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    step(dt: number): void;
+};

package/dist/behaviourDriver.js

@@ -0,0 +1,21 @@
+export function createBehaviourWorldDriver(world) {
+    let running = false;
+    return {
+        start() {
+            if (!world.started())
+                world.start();
+            running = true;
+        },
+        stop() {
+            running = false;
+        },
+        isRunning() {
+            return running;
+        },
+        step(dt) {
+            if (!running)
+                return;
+            world.update(dt);
+        },
+    };
+}

package/dist/camera/GameCameraRig.js

@@ -22,7 +22,7 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
     const followEntityId = directed.followEntityId;
     const rig = (() => {
         if (directed.cinematic !== undefined) {
-            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId }));
+            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true }));
         }
         const kind = resolveRigKind(config);
         switch (kind) {

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -1,5 +1,8 @@
 import { type MutableRefObject } from "react";
+import * as THREE from "three";
 import type { FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
+/** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
+export declare function readFirstPersonMuzzle(target: THREE.Vector3): boolean;
 export interface GameFirstPersonCameraProps {
     yawRef: MutableRefObject<number>;
     pitchRef: MutableRefObject<number>;