Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
index 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.js
index 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.js
index 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);
+});