@driftengine/audio 3.61.0

package/dist/spatial/source.js

@@ -0,0 +1,366 @@
+import { ProbeScheduler, occlusionCutoffHz, occlusionGainFor, smoothToward } from './occlusion.js';
+import { SourceZoneSend, busFeeds } from './zones.js';
+/**
+ * How long a zone send takes to reach a new value, as `setTargetAtTime`'s time constant.
+ *
+ * The same shape `MixBus` ramps its own sends with, and for the same reason: a send stepping to a
+ * new value is a click, and a source crossing a threshold is exactly when that would happen.
+ */
+const ZONE_RAMP = 0.03;
+/**
+ * Buses already warned about, so the refusal is once per misconfigured bus rather than once per
+ * source. A game with two hundred sources on one wrong bus is one line, not two hundred; a game
+ * with two wrong buses is two lines, which is two things to fix. See `attachZone`.
+ */
+const warnedDoubleZoneBuses = new Set();
+const DEFAULT_SPEED_OF_SOUND = 343;
+const DEFAULT_MAX_DOPPLER_CENTS = 200;
+const DEFAULT_OCCLUSION_RATE = 6;
+export class SpatialSource {
+    listener;
+    options;
+    node;
+    filter;
+    gain;
+    panner;
+    probes = new ProbeScheduler();
+    slot;
+    posX = 0;
+    posY = 0;
+    posZ = 0;
+    velX = 0;
+    velY = 0;
+    velZ = 0;
+    placed = false;
+    occlusionTarget = 0;
+    occlusionNow = 0;
+    cents = 0;
+    started = false;
+    stopped = false;
+    /**
+     * The zones this source carries the tail of, from its own position.
+     *
+     * An array rather than a map, because it is walked every frame and never looked up by key — the
+     * budget below caps it at a handful, and `resolveZones`'s own reason for a two-slot scan over a
+     * sort applies here one level down.
+     */
+    zoneSends = [];
+    constructor(listener, buffer, options = {}) {
+        this.listener = listener;
+        this.options = options;
+        const mix = listener.console;
+        const context = mix.context;
+        this.slot = listener.claimProbeSlot();
+        this.node = context.createBufferSource();
+        this.node.buffer = buffer;
+        this.node.loop = options.loop === true;
+        this.filter = context.createBiquadFilter();
+        this.filter.type = 'lowpass';
+        this.filter.frequency.value = occlusionCutoffHz(0);
+        this.filter.Q.value = 0.707;
+        this.gain = context.createGain();
+        this.gain.gain.value = 1;
+        this.panner = context.createPanner();
+        /*
+         * The whole reason this class exists. `equalpower` is a stereo balance and says nothing about
+         * front, back or height; `HRTF` convolves against a head model, which is what puts a sound
+         * *behind* somebody. It costs a convolution per source, which is why the cheap path is kept
+         * beside it rather than replaced by it.
+         */
+        this.panner.panningModel = 'HRTF';
+        this.panner.distanceModel = 'inverse';
+        this.panner.refDistance = options.refDistance ?? 1;
+        this.panner.maxDistance = options.maxDistance ?? 10000;
+        this.panner.rolloffFactor = options.rolloff ?? 1;
+        this.node.connect(this.filter);
+        this.filter.connect(this.gain);
+        this.gain.connect(this.panner);
+        this.bus = options.bus ?? mix.bus('effects');
+        this.panner.connect(this.bus.input);
+    }
+    /** Where this source's dry signal lands, which is what decides whether a zone would double. */
+    bus;
+    /**
+     * Carry the tail of a space this **source** is in, rather than one the listener is in.
+     *
+     * The case `zones.ts` names as the one its own model cannot serve: a sound inside a cave heard
+     * from outside carries whatever space the *listener* stands in, which is wrong exactly when
+     * somebody is listening *into* a space. A source-attached zone is a second **routing** into a
+     * return that already carries a convolver, so it costs one `GainNode` rather than one convolution.
+     *
+     * **`MAX_OPEN_ZONES` still binds, and it binds per source.** The budget is not about the sends,
+     * which are nearly free; it is about how many convolvers are audible at once, and a source driving
+     * four returns makes four of them audible. Two is the space being left and the space being
+     * entered, here as for the listener.
+     *
+     * The send is taken from the **occluded, unpanned** signal: a reverb send comes off the channel on
+     * any console, and the return is itself a stereo space, so a point-panned tail would arrive from
+     * the source's direction rather than from the room. Occlusion is upstream because a sound behind a
+     * wall has a muffled tail too.
+     */
+    attachZone(zone) {
+        if (this.zoneSends.some((send) => send.zone === zone))
+            return;
+        /*
+         * **Both routings into one return double the tail, and it is silent.** The listener's zones send
+         * from a whole bus, so a source sitting on that bus — or on a descendant of it — is already
+         * reaching this return whenever the listener is in the same space. Said here, which is setup,
+         * once per process rather than once per source.
+         */
+        if (!warnedDoubleZoneBuses.has(this.bus.name) && busFeeds(this.bus, zone.from)) {
+            warnedDoubleZoneBuses.add(this.bus.name);
+            console.warn(`[driftengine] a source on bus "${this.bus.name}" attached the zone "${zone.name}", which ` +
+                `is fed from "${zone.from.name}" — the same signal reaches that return twice whenever ` +
+                'the listener is in the same space. Put source-zoned sources on a bus outside the ' +
+                "zone's own feed.");
+        }
+        const context = this.listener.console.context;
+        const gain = context.createGain();
+        gain.gain.value = 0;
+        this.gain.connect(gain);
+        gain.connect(zone.bus.input);
+        this.zoneSends.push(new SourceZoneSend(zone, gain, (param, value) => {
+            const at = this.listener.console.scheduleAt();
+            param.cancelScheduledValues(at);
+            param.setTargetAtTime(value, at, ZONE_RAMP);
+        }));
+    }
+    /** What this source is currently sending into that zone's return. */
+    zoneSend(zone) {
+        return this.zoneSends.find((send) => send.zone === zone)?.value ?? 0;
+    }
+    /** The pitch shift currently applied, in cents. Zero with doppler off. */
+    get detuneCents() {
+        return this.cents;
+    }
+    /** How blocked this source is right now, after smoothing. */
+    get occlusion() {
+        return this.occlusionNow;
+    }
+    /**
+     * Where this source is, this frame.
+     *
+     * Velocity is derived here exactly as the listener derives its own, and for the same reason. A
+     * source that teleports should be moved with `warp`.
+     */
+    place(x, y, z, dtSec) {
+        if (this.placed && dtSec > 0) {
+            this.velX = (x - this.posX) / dtSec;
+            this.velY = (y - this.posY) / dtSec;
+            this.velZ = (z - this.posZ) / dtSec;
+        }
+        this.posX = x;
+        this.posY = y;
+        this.posZ = z;
+        this.placed = true;
+        this.writePosition(x, y, z);
+        this.updateDoppler();
+        this.updateOcclusion(dtSec);
+        this.updateZones(x, y, z);
+    }
+    /** Move without having travelled: a respawn, a cut, an object put back at the start. */
+    warp(x, y, z) {
+        this.posX = x;
+        this.posY = y;
+        this.posZ = z;
+        this.velX = 0;
+        this.velY = 0;
+        this.velZ = 0;
+        this.placed = true;
+    }
+    /**
+     * Say how blocked this source is, 0 clear to 1 solid.
+     *
+     * For a consumer that already knows — a door with a state, a sound that is definitionally
+     * indoors — and for anyone who would rather not hand the listener a probe. Overrides whatever the
+     * probe last answered until the probe answers again.
+     */
+    setOcclusion(amount) {
+        this.occlusionTarget = Number.isFinite(amount) ? Math.min(Math.max(amount, 0), 1) : 0;
+    }
+    start(when = 0) {
+        if (this.started)
+            return;
+        this.started = true;
+        this.node.start(when);
+    }
+    stop() {
+        if (!this.started || this.stopped)
+            return;
+        this.stopped = true;
+        try {
+            this.node.stop();
+        }
+        catch {
+            // Already ended. Nothing to undo about a node we were about to discard.
+        }
+    }
+    /**
+     * Which of this source's zones sound, from where the source is standing.
+     *
+     * The same two-slot scan `resolveZones` makes for the listener, written out here rather than
+     * shared because the listener's version fills a `Map` keyed by zone and this one walks an array
+     * of sends — the ranking is six lines and a shared version taking both shapes would be longer
+     * than either. What would make that wrong is a third caller.
+     *
+     * **Two slots is `MAX_OPEN_ZONES`**, written out rather than looped because two is what a
+     * crossfade needs. `sourceZone.test.ts` asserts the constant is still two, so raising it fails
+     * there and sends whoever raised it to read this.
+     */
+    updateZones(x, y, z) {
+        if (this.zoneSends.length === 0)
+            return;
+        let best = null;
+        let bestAmount = 0;
+        let second = null;
+        let secondAmount = 0;
+        for (const send of this.zoneSends) {
+            const amount = send.zone.amountAt(x, y, z);
+            if (amount <= 0)
+                continue;
+            if (amount > bestAmount) {
+                second = best;
+                secondAmount = bestAmount;
+                best = send;
+                bestAmount = amount;
+            }
+            else if (amount > secondAmount) {
+                second = send;
+                secondAmount = amount;
+            }
+        }
+        for (const send of this.zoneSends) {
+            if (send === best)
+                send.set(bestAmount);
+            else if (send === second)
+                send.set(secondAmount);
+            else
+                send.set(0);
+        }
+    }
+    dispose() {
+        this.stop();
+        for (const send of this.zoneSends)
+            send.dispose();
+        this.zoneSends.length = 0;
+        try {
+            this.panner.disconnect();
+            this.gain.disconnect();
+            this.filter.disconnect();
+            this.node.disconnect();
+        }
+        catch {
+            // The graph was torn down under us; there is nothing left to disconnect from.
+        }
+        this.probes.forget(this.slot);
+    }
+    /**
+     * Where the panner thinks this source is, through whichever surface the browser has.
+     *
+     * The same pair as the listener's, for the same reason and with the same cost: the deprecated
+     * setter steps where the parameters can glide. Assigned rather than ramped on both paths, because
+     * this is written every frame and the interpolation that matters is the panner's own, between
+     * render blocks.
+     */
+    writePosition(x, y, z) {
+        const modern = this.panner;
+        if (modern.positionX !== undefined) {
+            modern.positionX.value = x;
+            if (modern.positionY !== undefined)
+                modern.positionY.value = y;
+            if (modern.positionZ !== undefined)
+                modern.positionZ.value = z;
+            return;
+        }
+        this.panner.setPosition?.(x, y, z);
+    }
+    /**
+     * The doppler ratio, and why it is ours to compute.
+     *
+     * `PannerNode` carried `dopplerFactor` and `speedOfSound` and the specification removed both, so
+     * there is nothing to configure and nothing to fall back to: the shift is arithmetic on two
+     * velocities projected onto the line between the two objects.
+     *
+     * With `d` the unit vector from listener to source, the ratio is
+     * `(c + vListener·d) / (c + vSource·d)` — a listener closing on a source raises the numerator, a
+     * source closing on the listener lowers the denominator, and both raise the pitch.
+     *
+     * Clamped in cents rather than in ratio, because cents are what a listener hears: a whole tone
+     * each way is a strong, obviously-moving effect and anything past it stops reading as motion.
+     * Cost: a deliberately supersonic source stops shifting at the clamp instead of doing something
+     * dramatic. What would make this wrong is a game whose subject *is* the sonic boom, which wants a
+     * different model rather than a wider clamp.
+     */
+    updateDoppler() {
+        if (this.options.doppler !== true) {
+            this.cents = 0;
+            return;
+        }
+        const dx = this.posX - this.listener.x;
+        const dy = this.posY - this.listener.y;
+        const dz = this.posZ - this.listener.z;
+        const distance = Math.hypot(dx, dy, dz);
+        if (distance < 1e-4) {
+            this.cents = 0;
+            return;
+        }
+        const ux = dx / distance;
+        const uy = dy / distance;
+        const uz = dz / distance;
+        const c = this.options.speedOfSound ?? DEFAULT_SPEED_OF_SOUND;
+        const towardListener = this.listener.velocityX * ux + this.listener.velocityY * uy + this.listener.velocityZ * uz;
+        const towardSource = this.velX * ux + this.velY * uy + this.velZ * uz;
+        const denominator = c + towardSource;
+        if (!(denominator > 1e-3)) {
+            this.cents = this.options.maxDopplerCents ?? DEFAULT_MAX_DOPPLER_CENTS;
+            this.writeDetune();
+            return;
+        }
+        const ratio = (c + towardListener) / denominator;
+        const limit = this.options.maxDopplerCents ?? DEFAULT_MAX_DOPPLER_CENTS;
+        this.cents = Math.min(Math.max(1200 * Math.log2(ratio), -limit), limit);
+        this.writeDetune();
+    }
+    /**
+     * Apply the shift, through `detune` where the browser has it and `playbackRate` where it does not.
+     *
+     * `detune` is in cents, which is the unit the arithmetic above produces and the unit a musician
+     * would state it in. `playbackRate` is the ratio, and it is the older surface: converting back is
+     * exact, so the fallback is a different spelling rather than a different effect.
+     */
+    writeDetune() {
+        const detune = this.node.detune;
+        if (detune !== undefined) {
+            detune.value = this.cents;
+            return;
+        }
+        this.node.playbackRate.value = 2 ** (this.cents / 1200);
+    }
+    /**
+     * Ask the world whether something is in the way, at most once per period, then approach it.
+     *
+     * The probe is the consumer's own collision code and is the expensive part; the smoothing is what
+     * keeps a probe that lands on a different answer from clicking.
+     */
+    updateOcclusion(dtSec) {
+        const probe = this.listener.probe;
+        if (probe !== null &&
+            this.probes.due(this.slot, this.listener.probeSlots, this.listener.elapsedSec)) {
+            const blocked = probe(this.listener.x, this.listener.y, this.listener.z, this.posX, this.posY, this.posZ);
+            this.occlusionTarget = Number.isFinite(blocked) ? Math.min(Math.max(blocked, 0), 1) : 0;
+        }
+        const rate = this.options.occlusionRate ?? DEFAULT_OCCLUSION_RATE;
+        const next = smoothToward(this.occlusionNow, this.occlusionTarget, rate, dtSec);
+        if (Math.abs(next - this.occlusionNow) < 1e-4)
+            return;
+        this.occlusionNow = next;
+        // Assigned rather than ramped: this is already a smoothed value written every frame, and a ramp
+        // per frame on top of it would schedule sixty events a second to reach a target that has moved.
+        this.filter.frequency.value = occlusionCutoffHz(next);
+        this.gain.gain.value = occlusionGainFor(next);
+    }
+}
+/** Place a sound in the world. See `SpatialSource` for when this is the right tool and when it is not. */
+export function createSpatialSource(listener, buffer, options) {
+    return new SpatialSource(listener, buffer, options);
+}

package/dist/spatial/zones.d.ts

@@ -0,0 +1,129 @@
+import type { MixBus } from '../mix/bus.ts';
+import type { AudioListenerGraph } from './listener.ts';
+/**
+ * A space the listener can be inside, and the tail it lends to everything heard there.
+ *
+ * A zone is a **return bus carrying a convolver**, which is the point of having built a mix tree
+ * rather than a fixed set of sends: a room is not a special case in the mixer, it is a bus like any
+ * other, and the listener simply decides how much goes to it.
+ *
+ * **Listener-based, and that is the whole model.** Whichever space the listener occupies decides
+ * the reverb, for every source at once. Cost: a sound inside a cave heard from *outside* it does
+ * not carry the cave's tail — it carries whatever space the listener is standing in, which is wrong
+ * in exactly the case where somebody is listening into a space rather than standing in one. The
+ * alternative is a convolver per source, which is the general answer and is priced accordingly.
+ * What would make this wrong is a scene whose drama is standing at a threshold listening in; that
+ * is when to pay for the other model.
+ */
+export interface ZoneShape {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    /** Inside this, the zone is at full wet. */
+    readonly radius: number;
+    /** Metres beyond the radius over which it fades out. Zero is a hard edge, which is audible. */
+    readonly blend: number;
+}
+export interface ZoneOptions {
+    /** How long the tail is. */
+    readonly seconds: number;
+    /** How fast it decays inside that. Larger is a drier, tighter room. */
+    readonly decay: number;
+    /** How much reaches the return when the listener is fully inside. */
+    readonly wet: number;
+    /**
+     * What feeds this zone. The console's `effects` bus when omitted.
+     *
+     * A zone is a property of the *world*, so what it should carry is the world's own sound. A
+     * consumer with its own tree names the bus; one using the default layout gets the bus every
+     * placed source and ambient loop already lands on.
+     */
+    readonly from?: MixBus;
+}
+/**
+ * How many zones may sound at once.
+ *
+ * Two: the space being left and the space being entered. A convolver is the most expensive node in
+ * this graph and N of them is N times that, and a third is inaudible under a crossfade between the
+ * first two while costing everything a second one costs.
+ */
+export declare const MAX_OPEN_ZONES = 2;
+export declare class ReverbZone {
+    readonly name: string;
+    readonly shape: ZoneShape;
+    readonly wet: number;
+    /** The return, carrying the convolver. */
+    readonly bus: MixBus;
+    /** What feeds it. */
+    readonly from: MixBus;
+    constructor(name: string, shape: ZoneShape, wet: number, 
+    /** The return, carrying the convolver. */
+    bus: MixBus, 
+    /** What feeds it. */
+    from: MixBus);
+    /**
+     * How much of the world this zone should be carrying, from a listener at this point.
+     *
+     * Full inside the radius, fading to nothing across `blend`, zero beyond. A hard edge is audible
+     * as the room switching on, which is the one thing a reverb must never do.
+     */
+    amountAt(x: number, y: number, z: number): number;
+}
+/**
+ * Register a space. **Its convolver is built here and never on entry.**
+ *
+ * Building an impulse allocates a stereo buffer and fills it sample by sample, which costs
+ * milliseconds; doing that when a player crosses a threshold would put both the allocation and the
+ * cost on the input path at the exact moment something is supposed to happen. `graph.ts` already
+ * refuses to do it on a jump for the same reason.
+ *
+ * The return is parented to `master`, so a zone's tail goes through the master filter. **That is
+ * deliberately unlike the three legacy returns**, which join downstream of it: those carry the
+ * score, and a score is not in the world. A zone is the world, and the master filter is what "under
+ * water" means for it — a room whose tail stayed bright while everything else muffled would read as
+ * the reverb having come from somewhere else.
+ */
+export declare function addReverbZone(listener: AudioListenerGraph, name: string, shape: ZoneShape, options: ZoneOptions): ReverbZone;
+/**
+ * A source's own routing into one zone's return.
+ *
+ * **A second routing, not a second convolver**, which is the whole reason this is affordable: the
+ * zone's return already carries a convolver built at registration, and this is one `GainNode` from
+ * the source into that same input. A convolver per source is the general answer to spatial reverb
+ * and is priced accordingly — `zones.ts` has said so since it was written, and this row is what
+ * that sentence was waiting for.
+ *
+ * **Taken before the panner and after the occlusion.** A reverb send is taken from the channel on
+ * any console, and the return is itself a stereo space: a tail that arrived point-panned would come
+ * from the source's direction rather than from the room. Occlusion is upstream on purpose, because
+ * a sound behind a wall has a muffled tail too.
+ */
+export declare class SourceZoneSend {
+    readonly zone: ReverbZone;
+    private readonly gain;
+    private readonly rampTo;
+    private amount;
+    constructor(zone: ReverbZone, gain: GainNode, rampTo: (param: AudioParam, value: number) => void);
+    /** What this source is currently sending into that return. */
+    get value(): number;
+    /** Ramped rather than assigned, because a send stepping to a new value is a click. */
+    set(value: number): void;
+    dispose(): void;
+}
+/**
+ * Whether `bus` reaches `target` by its parent chain, so a send into `target` would double.
+ *
+ * The listener's zones send from a whole bus, so anything landing on that bus **or on a descendant
+ * of it** is already reaching the return whenever the listener is in the same space. Walking the
+ * chain rather than comparing one reference is the difference between catching the obvious case and
+ * catching the case a consumer with its own tree actually builds.
+ */
+export declare function busFeeds(bus: MixBus, target: MixBus): boolean;
+/**
+ * Decide what every zone should be sending, and close everything past the nearest two.
+ *
+ * Called once per listener move. Allocation-free: the ranking is a two-slot scan rather than a
+ * sort, because this runs every frame and a sort of a small array still allocates a comparator's
+ * worth of work sixty times a second.
+ */
+export declare function resolveZones(zones: readonly ReverbZone[], x: number, y: number, z: number, out: Map<ReverbZone, number>): void;

package/dist/spatial/zones.js

@@ -0,0 +1,166 @@
+import { convolverInsert } from '../mix/returns.js';
+/**
+ * How many zones may sound at once.
+ *
+ * Two: the space being left and the space being entered. A convolver is the most expensive node in
+ * this graph and N of them is N times that, and a third is inaudible under a crossfade between the
+ * first two while costing everything a second one costs.
+ */
+export const MAX_OPEN_ZONES = 2;
+export class ReverbZone {
+    name;
+    shape;
+    wet;
+    bus;
+    from;
+    constructor(name, shape, wet, 
+    /** The return, carrying the convolver. */
+    bus, 
+    /** What feeds it. */
+    from) {
+        this.name = name;
+        this.shape = shape;
+        this.wet = wet;
+        this.bus = bus;
+        this.from = from;
+    }
+    /**
+     * How much of the world this zone should be carrying, from a listener at this point.
+     *
+     * Full inside the radius, fading to nothing across `blend`, zero beyond. A hard edge is audible
+     * as the room switching on, which is the one thing a reverb must never do.
+     */
+    amountAt(x, y, z) {
+        const distance = Math.hypot(x - this.shape.x, y - this.shape.y, z - this.shape.z);
+        if (distance <= this.shape.radius)
+            return this.wet;
+        if (!(this.shape.blend > 0))
+            return 0;
+        const past = distance - this.shape.radius;
+        if (past >= this.shape.blend)
+            return 0;
+        return this.wet * (1 - past / this.shape.blend);
+    }
+}
+/**
+ * Register a space. **Its convolver is built here and never on entry.**
+ *
+ * Building an impulse allocates a stereo buffer and fills it sample by sample, which costs
+ * milliseconds; doing that when a player crosses a threshold would put both the allocation and the
+ * cost on the input path at the exact moment something is supposed to happen. `graph.ts` already
+ * refuses to do it on a jump for the same reason.
+ *
+ * The return is parented to `master`, so a zone's tail goes through the master filter. **That is
+ * deliberately unlike the three legacy returns**, which join downstream of it: those carry the
+ * score, and a score is not in the world. A zone is the world, and the master filter is what "under
+ * water" means for it — a room whose tail stayed bright while everything else muffled would read as
+ * the reverb having come from somewhere else.
+ */
+export function addReverbZone(listener, name, shape, options) {
+    const mix = listener.console;
+    const bus = mix.bus(name);
+    bus.insert(convolverInsert(mix.context, options.seconds, options.decay, () => mix.random()));
+    const from = options.from ?? mix.bus('effects');
+    // At zero: a zone that springs into existence sending is a room that switches on.
+    from.send(bus, 0);
+    const zone = new ReverbZone(name, shape, options.wet, bus, from);
+    listener.addZone(zone);
+    return zone;
+}
+/**
+ * A source's own routing into one zone's return.
+ *
+ * **A second routing, not a second convolver**, which is the whole reason this is affordable: the
+ * zone's return already carries a convolver built at registration, and this is one `GainNode` from
+ * the source into that same input. A convolver per source is the general answer to spatial reverb
+ * and is priced accordingly — `zones.ts` has said so since it was written, and this row is what
+ * that sentence was waiting for.
+ *
+ * **Taken before the panner and after the occlusion.** A reverb send is taken from the channel on
+ * any console, and the return is itself a stereo space: a tail that arrived point-panned would come
+ * from the source's direction rather than from the room. Occlusion is upstream on purpose, because
+ * a sound behind a wall has a muffled tail too.
+ */
+export class SourceZoneSend {
+    zone;
+    gain;
+    rampTo;
+    amount = 0;
+    constructor(zone, gain, rampTo) {
+        this.zone = zone;
+        this.gain = gain;
+        this.rampTo = rampTo;
+    }
+    /** What this source is currently sending into that return. */
+    get value() {
+        return this.amount;
+    }
+    /** Ramped rather than assigned, because a send stepping to a new value is a click. */
+    set(value) {
+        const floored = Number.isFinite(value) ? Math.max(0, value) : 0;
+        if (floored === this.amount)
+            return;
+        this.amount = floored;
+        this.rampTo(this.gain.gain, floored);
+    }
+    dispose() {
+        this.amount = 0;
+        try {
+            this.gain.disconnect();
+        }
+        catch {
+            // The graph was torn down under us; there is nothing left to disconnect from.
+        }
+    }
+}
+/**
+ * Whether `bus` reaches `target` by its parent chain, so a send into `target` would double.
+ *
+ * The listener's zones send from a whole bus, so anything landing on that bus **or on a descendant
+ * of it** is already reaching the return whenever the listener is in the same space. Walking the
+ * chain rather than comparing one reference is the difference between catching the obvious case and
+ * catching the case a consumer with its own tree actually builds.
+ */
+export function busFeeds(bus, target) {
+    for (let at = bus; at !== null; at = at.parent) {
+        if (at === target)
+            return true;
+    }
+    return false;
+}
+/**
+ * Decide what every zone should be sending, and close everything past the nearest two.
+ *
+ * Called once per listener move. Allocation-free: the ranking is a two-slot scan rather than a
+ * sort, because this runs every frame and a sort of a small array still allocates a comparator's
+ * worth of work sixty times a second.
+ */
+export function resolveZones(zones, x, y, z, out) {
+    let bestZone = null;
+    let bestAmount = 0;
+    let secondZone = null;
+    let secondAmount = 0;
+    for (const zone of zones) {
+        const amount = zone.amountAt(x, y, z);
+        if (amount <= 0)
+            continue;
+        if (amount > bestAmount) {
+            secondZone = bestZone;
+            secondAmount = bestAmount;
+            bestZone = zone;
+            bestAmount = amount;
+        }
+        else if (amount > secondAmount) {
+            secondZone = zone;
+            secondAmount = amount;
+        }
+    }
+    for (const zone of zones) {
+        if (zone === bestZone)
+            out.set(zone, bestAmount);
+        else if (zone === secondZone)
+            out.set(zone, secondAmount);
+        else
+            out.set(zone, 0);
+    }
+}