3D engine that AI agents drive
Poll audio actions per runtime mode, keep the frame path from throwing, bound linear rolloff (#775)
Nguyen Xuan An3211df376326
diff --git a/docs/audio.md b/docs/audio.mdindex 7b89e5de..7aea527d 100644--- a/docs/audio.md+++ b/docs/audio.md@@ -25,7 +25,7 @@ Browsers keep audio silent until the page has had a user gesture. The audio star`defineSound(name, { buffer, bus, volume, pitch, pitchVariance, loop, maximumInstances, spatial })` takes a decoded `AudioBuffer`. `await load(name, source, definition)` decodes a URL, an `ArrayBuffer` or an `AudioBuffer` first. `volume` is 0 to 4, `pitch` is a playback-rate multiplier from 0.1 to 4, and `pitchVariance` (0 to 1) varies the pitch of each play from a seeded generator (`createAudio({ seed })`), so a replay sounds the same. `maximumInstances` (default 8) stops the oldest copy of a sound when it plays again.-A sound without `spatial` is flat, like music or a menu click. `spatial: true` or `{ referenceDistance, maximumDistance, rolloff, model, occlusion }` places it in the world with HRTF panning. `model` is `'inverse'` (default), `'linear'` or `'exponential'`, as in the Web Audio specification.+A sound without `spatial` is flat, like music or a menu click. `spatial: true` or `{ referenceDistance, maximumDistance, rolloff, model, occlusion }` places it in the world with HRTF panning. `model` is `'inverse'` (default), `'linear'` or `'exponential'`, as in the Web Audio specification. `rolloff` is 0 to 20, or 0 to 1 for `'linear'`. A voice whose node function stops returning a position is stopped, and a bad occlusion result is clamped to 0 to 1.## Playing@@ -40,7 +40,7 @@ A sound without `spatial` is flat, like music or a menu click. `spatial: true` o| Source | Call | Event fired || --- | --- | --- |-| Input action | `bindAction('jump', 'hop')`; the system checks `input.wasPressed` each fixed step | `input:jump`, once per press |+| Input action | `bindAction('jump', 'hop')`; the system checks `input.wasPressed` each fixed step, or each frame when the runtime mode is `'variable'` | `input:jump`, once per press || Physics contacts | `emitContacts(scene.contactEvents, { position })` | `contact` or `sensor` for each started event, plus `contact:<collider>` for both colliders || Animation markers | `emitMarkers(markers, previousTime, currentTime, { loop, duration, data })` | `marker:<name>` for each `{ time, name }` crossed |diff --git a/src/audio.js b/src/audio.jsindex c0a35864..23fa9bdf 100644--- a/src/audio.js+++ b/src/audio.js@@ -51,15 +51,19 @@ function requireVector(value, label) {return [value[0], value[1], value[2]];}+function clampUnit(value) {+ return Math.min(Math.max(value, 0), 1);+}+// Distance gain from the Web Audio specification, so the level measured here matches what a PannerNode applies.export function distanceGain(distance, { model = 'inverse', referenceDistance = 1, maximumDistance = 50, rolloff = 1 } = {}) {const clamped = Math.min(Math.max(distance, referenceDistance), maximumDistance);if (model === 'linear') {const span = maximumDistance - referenceDistance;- return span <= 0 ? 1 : 1 - rolloff * (clamped - referenceDistance) / span;+ return span <= 0 ? 1 : clampUnit(1 - rolloff * (clamped - referenceDistance) / span);}- if (model === 'exponential') return (clamped / referenceDistance) ** -rolloff;- return referenceDistance / (referenceDistance + rolloff * (clamped - referenceDistance));+ if (model === 'exponential') return clampUnit((clamped / referenceDistance) ** -rolloff);+ return clampUnit(referenceDistance / (referenceDistance + rolloff * (clamped - referenceDistance)));}function normalizeSpatial(spatial, label) {@@ -74,7 +78,9 @@ function normalizeSpatial(spatial, label) {}const referenceDistance = requireNumberInRange(options.referenceDistance ?? 1, `${label} spatial referenceDistance`, 0.01, 1000);const maximumDistance = requireNumberInRange(options.maximumDistance ?? 50, `${label} spatial maximumDistance`, referenceDistance, 100000);- const rolloff = requireNumberInRange(options.rolloff ?? 1, `${label} spatial rolloff`, 0, 20);+ // A real PannerNode rejects a linear rolloff above 1, so the range is narrower for that model.+ const maximumRolloff = model === 'linear' ? 1 : 20;+ const rolloff = requireNumberInRange(options.rolloff ?? 1, `${label} spatial rolloff`, 0, maximumRolloff);return Object.freeze({ model, referenceDistance, maximumDistance, rolloff, occlusion: options.occlusion === true });}@@ -455,6 +461,13 @@ export function createAudio(options = {}) {return requireNumberInRange(occluder(listenerPose.position, voice.position), 'occlusion function result', 0, 1);}+ // The per-frame path never throws: a bad occlusion value is clamped so one callback cannot halt the runtime loop.+ function measureOcclusionSafely(voice) {+ if (!occluder || !voice.sound.spatial?.occlusion || !voice.position) return 0;+ const measured = Number(occluder(listenerPose.position, voice.position));+ return Number.isFinite(measured) ? Math.min(Math.max(measured, 0), 1) : 0;+ }+function removeVoice(voice) {const index = voices.indexOf(voice);if (index >= 0) voices.splice(index, 1);@@ -671,15 +684,36 @@ export function createAudio(options = {}) {}function synchronize() {- if (listenerSource) setListener(listenerSource());+ if (listenerSource) {+ try {+ setListener(listenerSource());+ } catch {+ // Keep the last good listener pose when the source returns a bad frame.+ }+ }for (const voice of [...voices]) {- if (voice.node !== null && voice.sound.spatial) voice.position = resolveVoicePosition(voice);- voice.occlusion = measureOcclusion(voice);+ if (voice.node !== null && voice.sound.spatial) {+ try {+ voice.position = resolveVoicePosition(voice);+ } catch {+ // The node is gone (a destroyed entity): end this voice and keep the others playing.+ stopVoice(voice);+ continue;+ }+ }+ voice.occlusion = measureOcclusionSafely(voice);voice.level = voiceLevel(voice);voice.backendVoice.update({ volume: voice.volume, pitch: voice.pitch, position: voice.position, occlusion: voice.occlusion });}}+ function pollActions() {+ if (!input) return;+ for (const [actionName, eventName] of actionEvents) {+ if (input.wasPressed(actionName)) emit(eventName, { action: actionName });+ }+ }+// ---- Runtime system ----function startBackend() {@@ -699,14 +733,12 @@ export function createAudio(options = {}) {startBackend();},fixedUpdate(step, context) {- if (input) {- for (const [actionName, eventName] of actionEvents) {- if (input.wasPressed(actionName)) emit(eventName, { action: actionName });- }- }+ // The input system samples in fixed steps in every mode except 'variable', so actions are read where it samples.+ if (context?.mode !== 'variable') pollActions();if (context?.mode === 'fixed') synchronize();},- update() {+ update(delta, context) {+ if (context?.mode === 'variable') pollActions();synchronize();},dispose() {diff --git a/tests/audio.test.js b/tests/audio.test.jsindex 494b93e8..4396a0d0 100644--- a/tests/audio.test.js+++ b/tests/audio.test.js@@ -387,3 +387,65 @@ test('a different backend plugs in behind the same calls', () => {assert.ok(calls.includes('voice:voice'));assert.ok(calls.includes('bus:music'));});++function createActionRuntime(mode, input, audio) {+ return createRuntime({ render() {} }, {+ mode,+ fixedRate: 60,+ systems: [input, audio],+ scheduler: { request: () => 1, cancel() {} },+ clock: () => 0,+ visibility: { hidden: false, subscribe: () => () => {} },+ });+}++for (const mode of ['variable', 'both']) {+ test(`input actions trigger sounds once per press in runtime mode ${mode}`, () => {+ const input = createInput({ actions: { jump: ['script/jump'] } });+ const { audio } = createFixture({ input });+ audio.defineSound('hop', { buffer });+ audio.bindAction('jump', 'hop');+ const runtime = createActionRuntime(mode, input, audio);+ runtime.start();+ input.press('script/jump');+ runtime.step(17);+ assert.equal(audio.activeVoices().length, 1);+ runtime.step(17);+ assert.equal(audio.activeVoices().length, 1, 'a held key does not retrigger');+ runtime.dispose();+ });+}++test('a node that starts returning null stops its voice without throwing, and the others keep playing', () => {+ const { audio } = createFixture();+ audio.defineSound('hum', { buffer, spatial: true });+ let position = [1, 0, 0];+ const dying = audio.attach(() => position, 'hum');+ const steady = audio.attach({ position: [2, 0, 0] }, 'hum');+ position = null;+ assert.doesNotThrow(() => audio.synchronize());+ assert.equal(dying.playing, false);+ assert.equal(steady.playing, true);+});++test('a bad occlusion result in a frame update is clamped, while play keeps the strict check', () => {+ let blocked = 0;+ const { audio } = createFixture({ occlusion: () => blocked });+ audio.defineSound('shot', { buffer, spatial: { occlusion: true } });+ const handle = audio.play('shot', { position: [0, 0, -1] });+ blocked = 5;+ assert.doesNotThrow(() => audio.synchronize());+ assert.ok(Math.abs(handle.level - (1 - OCCLUDED_GAIN_LOSS)) < 1e-9, 'a value above 1 clamps to 1');+ blocked = Number.NaN;+ assert.doesNotThrow(() => audio.synchronize());+ assert.equal(handle.level, 1, 'NaN reads as open');+ assert.throws(() => audio.play('shot', { position: [0, 0, -1] }), /occlusion function result/);+});++test('a linear rolloff above 1 is rejected, other models keep up to 20, and gain never goes negative', () => {+ const { audio } = createFixture();+ assert.throws(() => audio.defineSound('far', { buffer, spatial: { model: 'linear', rolloff: 2 } }), /rolloff/);+ assert.doesNotThrow(() => audio.defineSound('wide', { buffer, spatial: { model: 'inverse', rolloff: 5 } }));+ assert.equal(distanceGain(1000, { model: 'linear', rolloff: 1, referenceDistance: 1, maximumDistance: 50 }), 0);+ assert.equal(distanceGain(1000, { model: 'linear', rolloff: 5, referenceDistance: 1, maximumDistance: 50 }), 0);+});