@woosh/meep-engine 3.3.0 → 3.5.0

package/src/engine/sound/sopra/legacy/convertLegacySoundComponents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertLegacySoundComponents.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/legacy/convertLegacySoundComponents.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,gGAVW;IAAC,WAAW,CAAC,EAAE,IAAI,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,IAAI,CAAA;CAAC,GAOvC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAmEnE"}

package/src/engine/sound/sopra/legacy/convertLegacySoundComponents.js

@@ -0,0 +1,279 @@
+import { AudioEmitter } from "../../ecs/audio/AudioEmitter.js";
+import { SoundEmitter } from "./SoundEmitter.js";
+import { SoundTrack } from "./SoundTrack.js";
+import { SoundTrackFlags } from "./SoundTrackFlags.js";
+import SoundController from "./SoundController.js";
+import { AudioEventTrigger, AudioEventTriggerRule } from "../../ecs/trigger/AudioEventTrigger.js";
+import { volume2dB } from "../../volume2dB.js";
+import { BlendContainerAudioClip } from "../definition/clip/BlendContainerAudioClip.js";
+import {
+    RandomContainerAudioClip
+} from "../definition/clip/RandomContainerAudioClip.js";
+import { SampleAudioClip } from "../definition/clip/SampleAudioClip.js";
+import { LEGACY_FALLBACK_BUS_ID, soundTrackToEventDescription } from "./soundEmitterToEventDescription.js";
+
+/**
+ * Turns legacy sound components in a deserialized dataset into their native equivalents:
+ * `SoundEmitter` → {@link AudioEmitter}, `SoundController` → {@link AudioEventTrigger}. Old saves and
+ * old scenes keep loading — their bytes still deserialize through the registered legacy adapters — and
+ * this pass is what makes what they loaded playable by the native systems.
+ *
+ * **Hosts call this themselves, after deserialization.** It is deliberately not run inside the
+ * deserializer: a host owns its load pipeline, and `populateEngineSerializationRegistry` promises only
+ * to know how to read the bytes.
+ *
+ * What is deliberately dropped, because it never survived a load anyway:
+ * - `track.time` — the legacy runtime always started a restored track from zero.
+ * - `panningModel` — the v2 binary adapter never wrote it, so a binary-sourced emitter has the HRTF
+ *   default already, which is what a conversion produces.
+ *
+ * @param {EntityComponentDataset} dataset mutated in place
+ * @param {{knownBusIds?: Set<string>|string[]|null}} [options] the bus ids the target mixer actually
+ *        has. A legacy `channel` is a free string on decade-old authored data, and sopra's
+ *        `BusGraph.getInput` THROWS on an unknown id — so a stale channel name would fail the emitter's
+ *        first play. Given this set, an unrecognised channel is logged and rewritten to
+ *        `effects`, which is the contract the legacy runtime applied at play time. Omit it only when
+ *        the channel names are already known to be good. A host on the default mixer can pass
+ *        `Object.values(SopraDefaultBus)`.
+ * @returns {{emitters: number, triggers: number, discarded: number}} what the pass did: emitters and
+ *          triggers created, and legacy components removed without a replacement (nothing to play)
+ */
+export function convertLegacySoundComponents(dataset, { knownBusIds = null } = {}) {
+    const buses = knownBusIds === null ? null : new Set(knownBusIds);
+
+    /**
+     * @param {string|null|undefined} channel
+     * @returns {string}
+     */
+    function resolveBus(channel) {
+        const busId = typeof channel === "string" && channel !== "" ? channel : LEGACY_FALLBACK_BUS_ID;
+
+        if (buses === null || buses.has(busId)) {
+            return busId;
+        }
+
+        console.error(`sopra: no bus named '${busId}', falling back to '${LEGACY_FALLBACK_BUS_ID}'`);
+
+        return LEGACY_FALLBACK_BUS_ID;
+    }
+
+    const result = { emitters: 0, triggers: 0, discarded: 0 };
+
+    const emitterEntities = collectEntities(dataset, SoundEmitter);
+    const controllerEntities = collectEntities(dataset, SoundController);
+
+    // controllers first: a rule's sound was played through the entity's emitter at runtime, so it has to
+    // read that emitter's spatialization before the emitter is taken away
+    for (let i = 0; i < controllerEntities.length; i++) {
+        const entity = controllerEntities[i];
+
+        const controller = dataset.getComponent(entity, SoundController);
+        const emitter = dataset.getComponent(entity, SoundEmitter);
+
+        const trigger = convertController(controller, emitter, resolveBus);
+
+        dataset.removeComponentFromEntity(entity, SoundController);
+
+        if (trigger === null) {
+            result.discarded++;
+            continue;
+        }
+
+        addComponent(dataset, entity, trigger);
+        result.triggers++;
+    }
+
+    for (let i = 0; i < emitterEntities.length; i++) {
+        const entity = emitterEntities[i];
+
+        const emitter = dataset.getComponent(entity, SoundEmitter);
+
+        const audioEmitter = convertEmitter(emitter, resolveBus);
+
+        dataset.removeComponentFromEntity(entity, SoundEmitter);
+
+        if (audioEmitter === null) {
+            result.discarded++;
+            continue;
+        }
+
+        addComponent(dataset, entity, audioEmitter);
+        result.emitters++;
+    }
+
+    return result;
+}
+
+/**
+ * Entity ids carrying `type`, collected up front — the pass adds and removes components as it goes,
+ * which is not safe to do while traversing.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {Class} type
+ * @returns {number[]}
+ */
+function collectEntities(dataset, type) {
+    if (!dataset.isComponentTypeRegistered(type)) {
+        // no legacy data of this kind was ever loaded into this dataset
+        return [];
+    }
+
+    const entities = [];
+
+    dataset.traverseComponents(type, (component, entity) => {
+        entities.push(entity);
+    });
+
+    return entities;
+}
+
+/**
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {AudioEmitter|AudioEventTrigger} component
+ */
+function addComponent(dataset, entity, component) {
+    const type = Object.getPrototypeOf(component).constructor;
+
+    if (!dataset.isComponentTypeRegistered(type)) {
+        dataset.registerComponentType(type);
+    }
+
+    dataset.addComponentToEntity(entity, component);
+}
+
+/**
+ * Build one legacy-equivalent event: the routing (bus, 3D, panning, distances, attenuation curve) comes
+ * from the emitter through the verified translator, so a conversion and a live translation agree by
+ * construction.
+ *
+ * @param {SoundEmitter} emitter
+ * @param {string} url
+ * @param {boolean} loop
+ * @param {boolean} [usingAlias]
+ * @returns {EventDescription}
+ */
+function legacyEventFor(emitter, url, loop, usingAlias = false) {
+    const track = new SoundTrack();
+
+    track.url = url;
+    track.writeFlag(SoundTrackFlags.Loop, loop);
+    track.writeFlag(SoundTrackFlags.UsingAliasURL, usingAlias);
+
+    return soundTrackToEventDescription(emitter, track);
+}
+
+/**
+ * @param {SoundTrack} track
+ * @returns {SampleAudioClip} with the track's own volume baked into its gain
+ */
+function clipFor(track) {
+    return SampleAudioClip.from(track.url, {
+        usingAlias: track.getFlag(SoundTrackFlags.UsingAliasURL),
+        loop: track.getFlag(SoundTrackFlags.Loop),
+        // The live translator leaves track volume out on purpose — the ECS layer composes
+        // emitter.volume x track.volume into the instance gain every frame, so there is one live volume
+        // home. A static conversion has no live track gain to compose with, so it has to bake it in.
+        gain: volume2dB(track.volume)
+    });
+}
+
+/**
+ * @param {SoundEmitter} emitter
+ * @param {function(string|null): string} resolveBus
+ * @returns {AudioEmitter|null} null when the emitter had nothing to play
+ */
+function convertEmitter(emitter, resolveBus) {
+    const tracks = emitter.tracks.asArray();
+
+    if (tracks.length === 0) {
+        // an emitter with no tracks made no sound and had no authored event of its own — most of these
+        // are the "empty emitter for a SoundController to write into" pattern, which the trigger
+        // replaces outright
+        return null;
+    }
+
+    const first = tracks[0];
+
+    const event = legacyEventFor(
+        emitter,
+        first.url,
+        first.getFlag(SoundTrackFlags.Loop),
+        first.getFlag(SoundTrackFlags.UsingAliasURL)
+    );
+
+    if (tracks.length === 1) {
+        event.rootClip = clipFor(first);
+    } else {
+        // Several tracks on one emitter played simultaneously, each at its own volume — a blend
+        // container is the engine's parallel container, so it is the shape that preserves that. No blend
+        // curves: a child without one is always fully on, which is the constant unit gain this needs.
+        console.warn(`sopra: converting a legacy SoundEmitter with ${tracks.length} concurrent tracks into a blend container`);
+
+        event.label = `${first.url} +${tracks.length - 1}`;
+        event.rootClip = BlendContainerAudioClip.from(tracks.map(clipFor));
+    }
+
+    event.busId = resolveBus(emitter.channel);
+
+    const result = new AudioEmitter();
+
+    result.event = event;
+    result.volume.set(emitter.volume.getValue());
+    result.autoplay = true;
+
+    return result;
+}
+
+/**
+ * @param {SoundController} controller
+ * @param {SoundEmitter|undefined} emitter the emitter this controller wrote its tracks into, if the
+ *        entity still has one — it is what decided whether a triggered sound was spatialized
+ * @param {function(string|null): string} resolveBus
+ * @returns {AudioEventTrigger|null} null when no rule of it could ever play anything
+ */
+function convertController(controller, emitter, resolveBus) {
+    // no emitter on the entity: its flags are all clear, which the translator reads as a 2D,
+    // unattenuated event — the same thing a controller writing into a default-constructed emitter got
+    const routingSource = emitter === undefined ? new SoundEmitter() : emitter;
+
+    const rules = [];
+
+    controller.rules.forEach(rule => {
+        if (typeof rule.startEvent !== "string") {
+            console.warn(`sopra: dropping a legacy SoundController rule with no start event`);
+            return;
+        }
+
+        const urls = rule.tracks;
+
+        if (urls === undefined || urls.length === 0) {
+            console.warn(`sopra: dropping the legacy SoundController rule for '${rule.startEvent}', it names no sound`);
+            return;
+        }
+
+        const event = legacyEventFor(routingSource, urls[0], rule.loop);
+
+        event.busId = resolveBus(rule.channel !== undefined && rule.channel !== null
+            ? rule.channel
+            : routingSource.channel);
+
+        const gain = volume2dB(rule.volume);
+
+        // the legacy system picked one url at random per trigger; a random container IS that pick, as
+        // authored data rather than as a decision the runtime remakes every time
+        event.rootClip = urls.length === 1
+            ? SampleAudioClip.from(urls[0], { loop: rule.loop, gain })
+            : RandomContainerAudioClip.from(urls.map(url => SampleAudioClip.from(url, { loop: rule.loop, gain })));
+
+        event.label = rule.startEvent;
+
+        rules.push(AudioEventTriggerRule.from(
+            rule.startEvent,
+            event,
+            typeof rule.stopEvent === "string" ? rule.stopEvent : null
+        ));
+    });
+
+    return rules.length === 0 ? null : AudioEventTrigger.from(rules);
+}

package/src/engine/sound/sopra/legacy/soundEmitterToEventDescription.d.ts

@@ -34,13 +34,13 @@ export function soundTrackToEventDescription(emitter: SoundEmitter, track: Sound
 export function soundEmitterToEventDescriptions(emitter: SoundEmitter): EventDescription[];
 /**
  * Bus a legacy emitter falls back to when its `channel` names one the mixer does not have. Applied by
- * {@link SoundEmitterComponentContext}, which can see the live bus graph; this module stays pure.
+ * {@link convertLegacySoundComponents}, which is told the live bus set; this module stays pure.
  * @type {string}
  */
 export const LEGACY_FALLBACK_BUS_ID: string;
-import { SoundAttenuationFunction } from "../../ecs/emitter/SoundAttenuationFunction.js";
+import { SoundAttenuationFunction } from "./SoundAttenuationFunction.js";
 import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
-import { SoundPanningModelType } from "../../ecs/emitter/SoundPanningModelType.js";
+import { SoundPanningModelType } from "./SoundPanningModelType.js";
 import { SopraPanningModel } from "../definition/SopraPanningModel.js";
 import { EventDescription } from "../definition/EventDescription.js";
 //# sourceMappingURL=soundEmitterToEventDescription.d.ts.map

package/src/engine/sound/sopra/legacy/soundEmitterToEventDescription.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"soundEmitterToEventDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/legacy/soundEmitterToEventDescription.js"],"names":[],"mappings":"AA2BA;;;;;GAKG;AACH,gEALW,wBAAwB,GAAC,MAAM,eAC/B,MAAM,eACN,MAAM,GACJ,cAAc,CAmB1B;AAED;;;GAGG;AACH,uDAHW,qBAAqB,GAAC,MAAM,GAC1B,iBAAiB,GAAC,MAAM,CAMpC;AASD;;;;;;;;;;;;;;GAcG;AACH,wFAFa,gBAAgB,CAwB5B;AAED;;;;GAIG;AACH,wEAFa,gBAAgB,EAAE,CAU9B;AA3DD;;;;GAIG;AACH,qCAFU,MAAM,CAEgC;yCA/DP,+CAA+C;+BADzD,4CAA4C;sCAGrC,4CAA4C;kCAKhD,oCAAoC;iCAFrC,mCAAmC"}
+{"version":3,"file":"soundEmitterToEventDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/legacy/soundEmitterToEventDescription.js"],"names":[],"mappings":"AA2BA;;;;;GAKG;AACH,gEALW,wBAAwB,GAAC,MAAM,eAC/B,MAAM,eACN,MAAM,GACJ,cAAc,CAmB1B;AAED;;;GAGG;AACH,uDAHW,qBAAqB,GAAC,MAAM,GAC1B,iBAAiB,GAAC,MAAM,CAMpC;AASD;;;;;;;;;;;;;;GAcG;AACH,wFAFa,gBAAgB,CAwB5B;AAED;;;;GAIG;AACH,wEAFa,gBAAgB,EAAE,CAU9B;AA3DD;;;;GAIG;AACH,qCAFU,MAAM,CAEgC;yCA/DP,+BAA+B;+BADzC,4CAA4C;sCAGrC,4BAA4B;kCAKhC,oCAAoC;iCAFrC,mCAAmC"}

package/src/engine/sound/sopra/legacy/soundEmitterToEventDescription.js

@@ -1,122 +1,122 @@
-import { interpolate_irradiance_linear } from "../../../../core/math/physics/irradiance/interpolate_irradiance_linear.js";
-import { interpolate_irradiance_lograrithmic } from "../../../../core/math/physics/irradiance/interpolate_irradiance_lograrithmic.js";
-import { interpolate_irradiance_smith } from "../../../../core/math/physics/irradiance/interpolate_irradiance_smith.js";
-import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
-import { SoundAttenuationFunction } from "../../ecs/emitter/SoundAttenuationFunction.js";
-import { SoundEmitterFlags } from "../../ecs/emitter/SoundEmitterFlags.js";
-import { SoundPanningModelType } from "../../ecs/emitter/SoundPanningModelType.js";
-import { SoundTrackFlags } from "../../ecs/emitter/SoundTrackFlags.js";
-import { buildAttenuationCurve } from "../util/buildAttenuationCurve.js";
-import { EventDescription } from "../definition/EventDescription.js";
-import { SampleAudioClip } from "../definition/clip/SampleAudioClip.js";
-import { SopraPanningModel } from "../definition/SopraPanningModel.js";
-
-/*
- * Pure translation from the legacy SoundEmitter/SoundTrack data into sopra EventDescriptions. No ECS,
- * no engine, no live state — just maps authored fields. Volume is intentionally NOT baked here: the
- * full live gain (emitter.volume × track.volume) is applied by the ECS layer through the instance's
- * gain (P3.5), so there is one live volume home and no double-counting.
- */
-
-/**
- * Translated legacy descriptions get a high instance cap so the legacy "play everything" behaviour is
- * preserved (the per-event VoiceManager limit effectively never trips).
- * @type {number}
- */
-const LEGACY_MAX_INSTANCES = 256;
-
-/**
- * @param {SoundAttenuationFunction|number} attenuationFunction
- * @param {number} distanceMin
- * @param {number} distanceMax
- * @returns {AnimationCurve} distance→gain curve reproducing the legacy falloff at sampled distances
- */
-export function attenuationFunctionToCurve(attenuationFunction, distanceMin, distanceMax) {
-    let falloff;
-
-    switch (attenuationFunction) {
-        case SoundAttenuationFunction.Logarithmic:
-            falloff = interpolate_irradiance_lograrithmic;
-            break;
-        case SoundAttenuationFunction.Smith:
-            falloff = interpolate_irradiance_smith;
-            break;
-        case SoundAttenuationFunction.Linear:
-        default:
-            falloff = interpolate_irradiance_linear;
-            break;
-    }
-
-    return buildAttenuationCurve(distanceMin, distanceMax, falloff);
-}
-
-/**
- * @param {SoundPanningModelType|number} panningModel
- * @returns {SopraPanningModel|number}
- */
-export function soundPanningModelToSopra(panningModel) {
-    return panningModel === SoundPanningModelType.EqualPower
-        ? SopraPanningModel.EqualPower
-        : SopraPanningModel.HRTF;
-}
-
-/**
- * Bus a legacy emitter falls back to when its `channel` names one the mixer does not have. Applied by
- * {@link SoundEmitterComponentContext}, which can see the live bus graph; this module stays pure.
- * @type {string}
- */
-export const LEGACY_FALLBACK_BUS_ID = 'effects';
-
-/**
- * Translate one legacy SoundTrack (in the context of its emitter) into a sopra EventDescription.
- *
- * The legacy component carries TWO independent spatial flags, and sopra needs both of them honoured:
- * `Spatialization` asks for panning, `Attenuation` asks for distance falloff. An emitter may set either
- * without the other — an ambience bed that fades with distance but must not swing around the listener's
- * head is precisely `Attenuation` alone, and the pre-sopra engine rendered it as a bare gain node with
- * no panner. So "positioned" here is `Spatialization || Attenuation` (sopra's `is3D`, which governs
- * distance handling), while panning is chosen separately — `SopraPanningModel.None` when the emitter
- * never asked to be panned.
- *
- * @param {SoundEmitter} emitter
- * @param {SoundTrack} track
- * @returns {EventDescription}
- */
-export function soundTrackToEventDescription(emitter, track) {
-    const clip = SampleAudioClip.from(track.url, {
-        usingAlias: track.getFlag(SoundTrackFlags.UsingAliasURL),
-        loop: track.getFlag(SoundTrackFlags.Loop)
-    });
-
-    const spatialized = emitter.getFlag(SoundEmitterFlags.Spatialization);
-    const attenuated = emitter.getFlag(SoundEmitterFlags.Attenuation);
-
-    const attenuation = attenuated
-        ? attenuationFunctionToCurve(emitter.attenuation, emitter.distanceMin, emitter.distanceMax)
-        : AnimationCurve.constant(0, 1, 1); // flat-1 = no distance attenuation
-
-    return EventDescription.from(track.url || "", clip, {
-        busId: emitter.channel || LEGACY_FALLBACK_BUS_ID,
-        is3D: spatialized || attenuated,
-        panningModel: spatialized ? soundPanningModelToSopra(emitter.panningModel) : SopraPanningModel.None,
-        distanceMin: emitter.distanceMin,
-        distanceMax: emitter.distanceMax,
-        attenuation,
-        maxInstances: LEGACY_MAX_INSTANCES
-    });
-}
-
-/**
- * Translate all of an emitter's current tracks into EventDescriptions (one per track).
- * @param {SoundEmitter} emitter
- * @returns {EventDescription[]}
- */
-export function soundEmitterToEventDescriptions(emitter) {
-    const result = [];
-
-    emitter.tracks.forEach(track => {
-        result.push(soundTrackToEventDescription(emitter, track));
-    });
-
-    return result;
-}
+import { interpolate_irradiance_linear } from "../../../../core/math/physics/irradiance/interpolate_irradiance_linear.js";
+import { interpolate_irradiance_lograrithmic } from "../../../../core/math/physics/irradiance/interpolate_irradiance_lograrithmic.js";
+import { interpolate_irradiance_smith } from "../../../../core/math/physics/irradiance/interpolate_irradiance_smith.js";
+import { AnimationCurve } from "../../../animation/curve/AnimationCurve.js";
+import { SoundAttenuationFunction } from "./SoundAttenuationFunction.js";
+import { SoundEmitterFlags } from "./SoundEmitterFlags.js";
+import { SoundPanningModelType } from "./SoundPanningModelType.js";
+import { SoundTrackFlags } from "./SoundTrackFlags.js";
+import { buildAttenuationCurve } from "../util/buildAttenuationCurve.js";
+import { EventDescription } from "../definition/EventDescription.js";
+import { SampleAudioClip } from "../definition/clip/SampleAudioClip.js";
+import { SopraPanningModel } from "../definition/SopraPanningModel.js";
+
+/*
+ * Pure translation from the legacy SoundEmitter/SoundTrack data into sopra EventDescriptions. No ECS,
+ * no engine, no live state — just maps authored fields. Volume is intentionally NOT baked here: the
+ * full live gain (emitter.volume × track.volume) is applied by the ECS layer through the instance's
+ * gain (P3.5), so there is one live volume home and no double-counting.
+ */
+
+/**
+ * Translated legacy descriptions get a high instance cap so the legacy "play everything" behaviour is
+ * preserved (the per-event VoiceManager limit effectively never trips).
+ * @type {number}
+ */
+const LEGACY_MAX_INSTANCES = 256;
+
+/**
+ * @param {SoundAttenuationFunction|number} attenuationFunction
+ * @param {number} distanceMin
+ * @param {number} distanceMax
+ * @returns {AnimationCurve} distance→gain curve reproducing the legacy falloff at sampled distances
+ */
+export function attenuationFunctionToCurve(attenuationFunction, distanceMin, distanceMax) {
+    let falloff;
+
+    switch (attenuationFunction) {
+        case SoundAttenuationFunction.Logarithmic:
+            falloff = interpolate_irradiance_lograrithmic;
+            break;
+        case SoundAttenuationFunction.Smith:
+            falloff = interpolate_irradiance_smith;
+            break;
+        case SoundAttenuationFunction.Linear:
+        default:
+            falloff = interpolate_irradiance_linear;
+            break;
+    }
+
+    return buildAttenuationCurve(distanceMin, distanceMax, falloff);
+}
+
+/**
+ * @param {SoundPanningModelType|number} panningModel
+ * @returns {SopraPanningModel|number}
+ */
+export function soundPanningModelToSopra(panningModel) {
+    return panningModel === SoundPanningModelType.EqualPower
+        ? SopraPanningModel.EqualPower
+        : SopraPanningModel.HRTF;
+}
+
+/**
+ * Bus a legacy emitter falls back to when its `channel` names one the mixer does not have. Applied by
+ * {@link convertLegacySoundComponents}, which is told the live bus set; this module stays pure.
+ * @type {string}
+ */
+export const LEGACY_FALLBACK_BUS_ID = 'effects';
+
+/**
+ * Translate one legacy SoundTrack (in the context of its emitter) into a sopra EventDescription.
+ *
+ * The legacy component carries TWO independent spatial flags, and sopra needs both of them honoured:
+ * `Spatialization` asks for panning, `Attenuation` asks for distance falloff. An emitter may set either
+ * without the other — an ambience bed that fades with distance but must not swing around the listener's
+ * head is precisely `Attenuation` alone, and the pre-sopra engine rendered it as a bare gain node with
+ * no panner. So "positioned" here is `Spatialization || Attenuation` (sopra's `is3D`, which governs
+ * distance handling), while panning is chosen separately — `SopraPanningModel.None` when the emitter
+ * never asked to be panned.
+ *
+ * @param {SoundEmitter} emitter
+ * @param {SoundTrack} track
+ * @returns {EventDescription}
+ */
+export function soundTrackToEventDescription(emitter, track) {
+    const clip = SampleAudioClip.from(track.url, {
+        usingAlias: track.getFlag(SoundTrackFlags.UsingAliasURL),
+        loop: track.getFlag(SoundTrackFlags.Loop)
+    });
+
+    const spatialized = emitter.getFlag(SoundEmitterFlags.Spatialization);
+    const attenuated = emitter.getFlag(SoundEmitterFlags.Attenuation);
+
+    const attenuation = attenuated
+        ? attenuationFunctionToCurve(emitter.attenuation, emitter.distanceMin, emitter.distanceMax)
+        : AnimationCurve.constant(0, 1, 1); // flat-1 = no distance attenuation
+
+    return EventDescription.from(track.url || "", clip, {
+        busId: emitter.channel || LEGACY_FALLBACK_BUS_ID,
+        is3D: spatialized || attenuated,
+        panningModel: spatialized ? soundPanningModelToSopra(emitter.panningModel) : SopraPanningModel.None,
+        distanceMin: emitter.distanceMin,
+        distanceMax: emitter.distanceMax,
+        attenuation,
+        maxInstances: LEGACY_MAX_INSTANCES
+    });
+}
+
+/**
+ * Translate all of an emitter's current tracks into EventDescriptions (one per track).
+ * @param {SoundEmitter} emitter
+ * @returns {EventDescription[]}
+ */
+export function soundEmitterToEventDescriptions(emitter) {
+    const result = [];
+
+    emitter.tracks.forEach(track => {
+        result.push(soundTrackToEventDescription(emitter, track));
+    });
+
+    return result;
+}

package/src/shade/device/mock/SoftwareGPUDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AAmOA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;;;OAUG;IACH;QAT+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAyBrC;IAzDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAmCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmHD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;OAGG;IACH,kEAEC;IAED;;;OAGG;IACH,iFAEC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAvnBa,mBAAiB,IAAI;;sCAlOG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}
+{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AAyOA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;;;OAUG;IACH;QAT+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAyBrC;IAzDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAmCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmHD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;OAGG;IACH,kEAEC;IAED;;;OAGG;IACH,iFAEC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAvnBa,mBAAiB,IAAI;;sCAxOG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}

package/src/shade/device/mock/SoftwareGPUDevice.js

@@ -177,9 +177,15 @@ const CORE_FEATURE = "core-features-and-limits";
  * construction rather than silently granted — a device that claims a feature it does not emulate
  * sends the code under test down a path this mock cannot honour.
  *
+ * `subgroups` is here on the opposite argument: it changes nothing but which WGSL a shader module
+ * is allowed to contain, and this device runs no WGSL at all. Subgroups being a baseline engine
+ * requirement, refusing it would leave the orchestration of every subgroup-using pass — which is
+ * most of the compute ones — untestable at this tier for a reason that has nothing to do with what
+ * the tier asserts.
+ *
  * @type {GPUFeatureName[]}
  */
-const SUPPORTED_OPTIONAL_FEATURES = ["timestamp-query"];
+const SUPPORTED_OPTIONAL_FEATURES = ["timestamp-query", "subgroups"];
 
 /**
  * A buffer that can be mapped for reading may combine that with nothing but `COPY_DST`, and one

package/src/shade/device/timing/GPUTimerArray.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUTimerArray.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimerArray.js"],"names":[],"mappings":"AAGA;IA8FI;;;;OAIG;IACH,sCAFW,MAAM,EAoChB;IA/ED;;;;OAIG;IACH,wBAHW,MAAM,iCAgBhB;IAED;;;;OAIG;IACH,uBAHW,MAAM,gCAgBhB;IA2CD,gBAQC;IAED;;;OAGG;IACH,0CAQC;IAED,kCAcC;IAED;;;OAGG;IACH,gCAqBC;;CAEJ"}
+{"version":3,"file":"GPUTimerArray.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/timing/GPUTimerArray.js"],"names":[],"mappings":"AAGA;IA8FI;;;;OAIG;IACH,sCAFW,MAAM,EAoChB;IA/ED;;;;OAIG;IACH,wBAHW,MAAM,iCAgBhB;IAED;;;;OAIG;IACH,uBAHW,MAAM,gCAgBhB;IA2CD,gBAQC;IAED;;;OAGG;IACH,0CAQC;IAED,kCAwBC;IAED;;;OAGG;IACH,gCAqBC;;CAEJ"}

package/src/shade/device/timing/GPUTimerArray.js

@@ -164,6 +164,16 @@ export class GPUTimerArray {
 
         const results_buffer = this.#results_buffer;
 
+        if (results_buffer === undefined) {
+            // Same guard as `resolve` and `destroy`: with the profiling feature withheld there is no
+            // query set and no buffers, and the timers are supposed to go quiet rather than take the
+            // frame down with them. Without it, `enable_debug_timers` on such a device raises an
+            // unhandled rejection out of `ShadeGPUCommandContext.finish`, which calls this
+            // unconditionally — `results_to_console_table` then reports an empty table, which is
+            // what "quiet" means.
+            return;
+        }
+
         await results_buffer.mapAsync(GPUMapMode.READ)
 
         const mapped = results_buffer.getMappedRange(

package/src/shade/playground/add_random_meshes.d.ts

@@ -1,10 +1,26 @@
 /**
+ * Scatter `count` instances of `geometries` through `region`, randomly oriented, at sizes spread
+ * across `geometry_scale_range`.
+ *
+ * This exists to build a workload the acceleration structures have to work for. Quantity moves
+ * traversal cost out of the per-mesh BLAS and into the TLAS — at a typical scene's hundred-odd
+ * instances a traced frame is entirely BLAS and shading, and the TLAS's shape is invisible in it.
+ * Size variety is the case a Morton order handles worst, since a Morton code sees a centroid and
+ * nothing about extent.
+ *
+ * Sizes are drawn as a *world-space diagonal* and divided down by each geometry's own, so the
+ * interval means the same thing whatever size the geometries were authored at, and a mixed list
+ * does not scatter one shape at a hundred times the size of another by accident.
  *
  * @param {InstanceBatch} batch
- * @param {Geometry[]} geometries
+ * @param {MeshletGeometry[]} geometries not plain `Geometry` — see {@link BoxGeometry} and
+ * {@link meshlet_geometry_build_from_geometry}
  * @param {ShadeMaterial[]} [materials]
  * @param {number} [count]
- * @param {NumericInterval} [geometry_scale_range]
+ * @param {NumericInterval} [geometry_scale_range] world-space bounding-box diagonal, in scene units
+ * @param {AABB3} [region] where instance origins land
+ * @param {function():number} [random] pass one shared generator to keep successive calls from
+ * scattering the same instances in the same places
  */
-export function add_random_meshes({ batch, geometries, materials, count, geometry_scale_range }: InstanceBatch): void;
+export function add_random_meshes({ batch, geometries, materials, count, geometry_scale_range, region, random }: InstanceBatch): void;
 //# sourceMappingURL=add_random_meshes.d.ts.map

package/src/shade/playground/add_random_meshes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add_random_meshes.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/add_random_meshes.js"],"names":[],"mappings":"AAcA;;;;;;;GAOG;AACH,sHA6DC"}
+{"version":3,"file":"add_random_meshes.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/add_random_meshes.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,sIAoFC"}