A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
refactor(audio): expose shared playback ownership
yhh5ee212bdbca5
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 48b9118ee..e2287dfee 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1104,6 +1104,9 @@ ResourceDef<AudioAPI>## AudioAPI — class @experimental```+@internal getVoiceState: (handle: AudioHandle) => "playing" | "paused" | "ended" | "stopped" | "untracked"+@internal onPlaybackStop: (callback: (generation: number) => void) => () => void+@internal playbackGeneration: numberbaseUrl: stringbufferBudget: numberdelivery: AudioDeliverydiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c6c60f167..72ce0b61a 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1104,6 +1104,9 @@ ResourceDef<AudioAPI>## AudioAPI — class @experimental```+@internal getVoiceState: (handle: AudioHandle) => "playing" | "paused" | "ended" | "stopped" | "untracked"+@internal onPlaybackStop: (callback: (generation: number) => void) => () => void+@internal playbackGeneration: numberbaseUrl: stringbufferBudget: numberdelivery: AudioDeliverydiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 6eae56df9..0b720e5ed 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1099,6 +1099,9 @@ ResourceDef<AudioAPI>## AudioAPI — class @experimental```+@internal getVoiceState: (handle: AudioHandle) => "playing" | "paused" | "ended" | "stopped" | "untracked"+@internal onPlaybackStop: (callback: (generation: number) => void) => () => void+@internal playbackGeneration: numberbaseUrl: stringbufferBudget: numberdelivery: AudioDeliverydiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex ed80ab140..777f73385 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1099,6 +1099,9 @@ ResourceDef<AudioAPI>## AudioAPI — class @experimental```+@internal getVoiceState: (handle: AudioHandle) => "playing" | "paused" | "ended" | "stopped" | "untracked"+@internal onPlaybackStop: (callback: (generation: number) => void) => () => void+@internal playbackGeneration: numberbaseUrl: stringbufferBudget: numberdelivery: AudioDeliverydiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d2090df1e..babcc6ca7 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1099,6 +1099,9 @@ ResourceDef<AudioAPI>## AudioAPI — class @experimental```+@internal getVoiceState: (handle: AudioHandle) => "playing" | "paused" | "ended" | "stopped" | "untracked"+@internal onPlaybackStop: (callback: (generation: number) => void) => () => void+@internal playbackGeneration: numberbaseUrl: stringbufferBudget: numberdelivery: AudioDeliverydiff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.tsindex b64049b8e..209bbfb2c 100644--- a/sdk/src/audio/Audio.ts+++ b/sdk/src/audio/Audio.ts@@ -6,6 +6,7 @@ import type { BusEffectDef } from './BusEffects';import { defineResource } from '../ecs/resource';import { RuntimeConfig } from '../defaults';import { log } from '../util/logger';+import { disposeAll } from '../util/disposeAll';const hostSuspensions = new WeakMap<AudioAPI, { owners: Set<object>; sync(): void }>();@@ -87,6 +88,7 @@ interface SoftVoice {handle: AudioHandle;publicHandle?: AudioHandle;paused: boolean;+ retired?: boolean;bus: string;base: number;fade: number;@@ -111,6 +113,8 @@ interface Fade {}export class AudioAPI {+ private readonly voiceStates_ = new WeakMap<AudioHandle, SoftVoice>();+ private readonly playbackStops_ = new Set<(generation: number) => void>();private readonly backend_: PlatformAudioBackend;private readonly mixer_: AudioMixer | null;private readonly bufferCache_ = new Map<string, BufferEntry>();@@ -528,20 +532,40 @@ export class AudioAPI {stopAll(): void {this.bgmRequest_++;- this.playbackEpoch_++;+ const generation = ++this.playbackEpoch_;const voices = this.softVoices_;this.softVoices_ = [];this.bgmHandle_ = null;this.fades_.length = 0;this.fadingOut_.clear();const stopped = new Set<AudioHandle>();+ const actions: Array<() => void> = [];for (const voice of voices) {- voice.paused = false;+ voice.paused = false; voice.retired = true;if (!stopped.has(voice.handle)) {stopped.add(voice.handle);- voice.handle.stop();+ actions.push(() => voice.handle.stop());}}+ for (const callback of this.playbackStops_) actions.push(() => callback(generation));+ disposeAll(actions, action => action());+ }++ /** @internal Generation boundary for pending playback intents. */+ get playbackGeneration(): number { return this.playbackEpoch_; }++ /** @internal Terminal and paused ownership comes from the global voice pool. */+ getVoiceState(handle: AudioHandle): 'playing' | 'paused' | 'ended' | 'stopped' | 'untracked' {+ const voice = this.voiceStates_.get(handle);+ if (!voice) return 'untracked';+ if (voice.retired) return 'stopped';+ return voice.paused ? 'paused' : voice.handle.isPlaying ? 'playing' : 'ended';+ }++ /** @internal Stop pending consumers after every old backend voice was stopped. */+ onPlaybackStop(callback: (generation: number) => void): () => void {+ this.playbackStops_.add(callback);+ return () => { this.playbackStops_.delete(callback); };}stopBGM(fadeOut?: number): void {@@ -718,7 +742,7 @@ export class AudioAPI {const api = this;const managed: AudioHandle = {get id() { return handle.id; },- stop() { voice.paused = false; handle.stop(); },+ stop() { if (!voice.retired) { voice.retired = true; voice.paused = false; handle.stop(); } },pause() {if (!handle.isPlaying) return;handle.pause();@@ -743,6 +767,7 @@ export class AudioAPI {set onEnd(callback) { handle.onEnd = callback; },};voice.publicHandle = managed;+ this.voiceStates_.set(managed, voice);this.softVoices_.push(voice);return managed;}@@ -768,6 +793,7 @@ export class AudioAPI {}if (!weakest || weakest.priority > priority) return false;weakest.paused = false;+ weakest.retired = true;weakest.handle.stop();this.softVoices_ = this.softVoices_.filter((v) => v !== weakest);return true;@@ -861,13 +887,11 @@ export class AudioAPI {// Scripted effects and AudioSource voices also belong to this device.// Closing a Web Audio context alone leaves their handles marked playing,// and a different backend may require explicit stops before disposal.- this.stopAll();- this.loadingBuffers_.clear();- for (const [url, entry] of this.bufferCache_) this.freeBuffer_(url, entry);- this.bufferSources_.clear();- this.evictOrder_.clear();- this.residentBytes_ = 0;- this.backend_?.dispose();+ disposeAll([() => this.stopAll(), () => this.playbackStops_.clear(), () => {+ this.loadingBuffers_.clear();+ try { disposeAll([...this.bufferCache_], ([url, entry]) => { this.freeBuffer_(url, entry); }); }+ finally { this.bufferCache_.clear(); this.bufferSources_.clear(); this.evictOrder_.clear(); this.residentBytes_ = 0; }+ }, () => this.backend_?.dispose()], action => action());}/**diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex f48b72d27..dba1db288 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'refactor(audio): expose shared playback ownership':+ { internal: 'Provides canonical voice-state lookup, stop generations and complete cleanup for leased consumers without adding another global voice pool.' },'feat(audio): add deterministic sound event definitions':{ note: 'Sound event definitions share deterministic selection.' },'feat(editor): recognize sound event definitions':