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
fix(audio): share decoded ownership across source aliases
yhhe5241916b30e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 55ae9ad9e..29af71bff 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **Audio aliases share decoded buffer ownership.** References resolving to one source share pending decoding and PCM accounting while retaining independent asset leases. Releasing one reference leaves other holders playable; source invalidation retires all aliases without unloading a replacement, and trimming frees each physical allocation once.+- **Loading sound-effect handles preserve playback controls.** Stopping before load completion prevents voice allocation and cannot be undone by Resume. Volume, pan, loop and playback rate apply to the initial backend play; queued Pause starts muted before pausing and restores the intended bus-adjusted gain. Resolved handles expose the real voice ID and forward completion callbacks, while later controls keep delegating normally.- **Stop All stops every owned audio voice and pending start.** Scripted effects, explicit tracks, paused voices and outgoing music fades are stopped once, and stopped handles cannot resume outside the voice registry. Pending effects and tracks requested before Stop All cannot start on load completion; cached buffers and the device remain reusable, and disposal uses the same shutdown path.diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.tsindex 679056112..b64049b8e 100644--- a/sdk/src/audio/Audio.ts+++ b/sdk/src/audio/Audio.ts@@ -18,23 +18,37 @@ export function setAudioHostSuspended(audio: AudioAPI, owner: object, suspended:}/**- * One decoded buffer's residency record. Mirrors the texture pool's+ * One authored reference's residency record. Mirrors the texture pool's* three-state lifecycle: held (refCount > 0, pinned by Assets) →* evictable (refCount 0, warm cache bounded by the byte budget) →* evicted (backend buffer freed; a future load re-fetches).*/interface BufferEntry {handle: AudioBufferHandle;- /** Decoded bytes; 0 = untracked (streaming backends), never budgeted. */- bytes: number;+ source: SharedAudioBuffer;/** Assets-held references. Direct play/preload entries stay at 0. */refCount: number;}+interface SharedAudioBuffer {+ url: string;+ loading: Promise<AudioBufferHandle>;+ handle?: AudioBufferHandle;+ aliases: Set<string>;+ requests: Set<string>;+ charged: boolean;+}++interface PendingAudioBuffer {+ promise: Promise<void>;+ source: SharedAudioBuffer;+}+/** Buffer residency counters. See {@link AudioAPI.getBufferStats}. */export interface AudioBufferStats {+ /** Authored cache entries; aliases can share one decoded allocation. */bufferCount: number;- /** Decoded bytes resident (held + evictable entries). */+ /** Unique decoded bytes resident (held + evictable entries). */bufferBytes: number;/** The effective byte budget (0 = warm cache off). */bufferBudget: number;@@ -100,7 +114,8 @@ export class AudioAPI {private readonly backend_: PlatformAudioBackend;private readonly mixer_: AudioMixer | null;private readonly bufferCache_ = new Map<string, BufferEntry>();- private readonly loadingBuffers_ = new Map<string, Promise<void>>();+ private readonly loadingBuffers_ = new Map<string, PendingAudioBuffer>();+ private readonly bufferSources_ = new Map<string, SharedAudioBuffer>();/** refCount==0 urls in eviction order (oldest first); access re-appends. */private readonly evictOrder_ = new Set<string>();private residentBytes_ = 0;@@ -208,28 +223,35 @@ export class AudioAPI {/** End cached and pending loads for changed source bytes. Playing sources* keep their decoded data; later loads fetch fresh. Returns whether a load ended. */invalidateBuffer(url: string): boolean {- const pending = this.loadingBuffers_.delete(url);const entry = this.bufferCache_.get(url);- if (!pending && !entry) return false;- this.backend_.invalidateSource?.(this.resolveUrl_(url));- if (!entry) return pending;- this.freeBuffer_(url, entry);+ let source = entry?.source ?? this.loadingBuffers_.get(url)?.source;+ if (!source) {+ try { source = this.bufferSources_.get(this.resolveUrl_(url)); } catch { return false; }+ }+ if (!source) return false;+ this.backend_.invalidateSource?.(source.url);+ if (this.bufferSources_.get(source.url) === source) this.bufferSources_.delete(source.url);+ for (const alias of source.requests) {+ if (this.loadingBuffers_.get(alias)?.source === source) this.loadingBuffers_.delete(alias);+ }+ for (const alias of [...source.aliases]) {+ const cached = this.bufferCache_.get(alias);+ if (cached?.source === source) this.freeBuffer_(alias, cached);+ }+ this.releaseSource_(source);return true;}/*** Free every evictable warm-cache buffer now (memory pressure). Held* buffers and the budget are untouched; the cache refills as buffers are- * released afterwards. Returns the number of buffers freed.+ * released afterwards. Returns the number of unique decoded buffers freed.*/trimBufferCache(): number {let freed = 0;for (const url of [...this.evictOrder_]) {const entry = this.bufferCache_.get(url);- if (entry) {- this.freeBuffer_(url, entry);- freed++;- }+ if (entry && this.freeBuffer_(url, entry)) freed++;}return freed;}@@ -249,11 +271,15 @@ export class AudioAPI {* eviction pool — mirroring the C++ pool's add(), where a just-created* resource can't be the one evicted to make room for itself (a caller* about to pin or play it would find it already gone). */- private insertEntry_(url: string, handle: AudioBufferHandle): void {- const entry: BufferEntry = { handle, bytes: handle.bytes ?? 0, refCount: 0 };+ private insertEntry_(url: string, handle: AudioBufferHandle, source: SharedAudioBuffer): void {+ const entry: BufferEntry = { handle, source, refCount: 0 };this.bufferCache_.set(url, entry);- this.residentBytes_ += entry.bytes;- this.enforceBudget_();+ source.aliases.add(url);+ if (!source.charged) {+ source.charged = true;+ this.residentBytes_ += handle.bytes ?? 0;+ this.enforceBudget_();+ }this.evictOrder_.add(url);}@@ -268,11 +294,26 @@ export class AudioAPI {return entry.handle;}- private freeBuffer_(url: string, entry: BufferEntry): void {- this.backend_.unloadBuffer(entry.handle);+ private freeBuffer_(url: string, entry: BufferEntry): boolean {+ if (this.bufferCache_.get(url) !== entry) return false;this.bufferCache_.delete(url);this.evictOrder_.delete(url);- this.residentBytes_ -= entry.bytes;+ const source = entry.source;+ source.aliases.delete(url);+ if (source.aliases.size === 0 && source.charged) {+ source.charged = false;+ this.residentBytes_ -= entry.handle.bytes ?? 0;+ }+ return this.releaseSource_(source);+ }++ private releaseSource_(source: SharedAudioBuffer): boolean {+ if (source.aliases.size || source.requests.size) return false;+ if (this.bufferSources_.get(source.url) === source) this.bufferSources_.delete(source.url);+ const handle = source.handle;+ source.handle = undefined;+ if (handle) this.backend_.unloadBuffer(handle);+ return !!handle;}/** Evict oldest warm-cache entries until resident bytes fit the budget.@@ -310,42 +351,64 @@ export class AudioAPI {return `${this.baseUrl}/${url}`;}- /** Load `url`'s buffer into the residency cache unless already there. The- * double `has()` check absorbs a concurrent load racing to insert first. */- private async ensureBuffer_(url: string, load: () => Promise<AudioBufferHandle>): Promise<void> {+ /** Coalesce authored requests through their captured physical source. */+ private async ensureBuffer_(+ url: string, load: (source: string) => Promise<AudioBufferHandle>, sourceUrl?: string,+ ): Promise<void> {if (this.disposed_) return;if (this.bufferCache_.has(url)) return;// De-dupe concurrent loads of the same url — without this, two preloads// (esp. the loadBufferFromData path, which has no backend-side dedup)// both decode and orphan one AudioBuffer.const inFlight = this.loadingBuffers_.get(url);- if (inFlight) return inFlight;- let promise!: Promise<void>;- promise = (async () => {- const buffer = await load();- if (this.disposed_ || this.loadingBuffers_.get(url) !== promise) {- this.backend_.unloadBuffer(buffer);- return;+ if (inFlight) return inFlight.promise;+ const resolved = sourceUrl ?? this.resolveUrl_(url);+ let source = this.bufferSources_.get(resolved);+ let start: (() => void) | undefined;+ if (!source) {+ let accept!: (buffer: AudioBufferHandle) => void, reject!: (error: unknown) => void;+ source = {+ url: resolved, aliases: new Set(), requests: new Set(), charged: false,+ loading: new Promise<AudioBufferHandle>((resolve, fail) => { accept = resolve; reject = fail; }),+ };+ const owned = source;+ this.bufferSources_.set(resolved, owned);+ start = () => {+ try {+ void Promise.resolve(load(resolved)).then(buffer => { owned.handle = buffer; accept(buffer); }, reject);+ } catch (error) { reject(error); }+ };+ }+ const shared = source;+ shared.requests.add(url);+ let receipt!: PendingAudioBuffer;+ const promise = (async () => {+ try {+ const buffer = await shared.loading;+ if (this.disposed_ || this.loadingBuffers_.get(url) !== receipt) return;+ if (!this.bufferCache_.has(url)) this.insertEntry_(url, buffer, shared);+ } finally {+ if (this.loadingBuffers_.get(url) === receipt) this.loadingBuffers_.delete(url);+ shared.requests.delete(url);+ this.releaseSource_(shared);}- if (!this.bufferCache_.has(url)) this.insertEntry_(url, buffer);})();- this.loadingBuffers_.set(url, promise);- try {- await promise;- } finally {- if (this.loadingBuffers_.get(url) === promise) this.loadingBuffers_.delete(url);- }+ receipt = { promise, source: shared };+ this.loadingBuffers_.set(url, receipt);+ // Install both ownership records before a backend can reenter the API.+ start?.();+ await promise;}async preload(url: string): Promise<void> {- if (this.bufferCache_.has(url)) return;+ if (this.disposed_ || this.bufferCache_.has(url)) return;if (this.assetResolver_) {const data = this.assetResolver_(url);if (data) {return this.preloadFromData(url, data);}}- await this.ensureBuffer_(url, () => this.backend_.loadBuffer(this.resolveUrl_(url)));+ await this.ensureBuffer_(url, source => this.backend_.loadBuffer(source));}async preloadAll(urls: string[]): Promise<void> {@@ -359,7 +422,7 @@ export class AudioAPI {* for a `url`-delivery backend is the only thing it plays.*/async preloadFromData(url: string, data: ArrayBuffer): Promise<void> {- await this.ensureBuffer_(url, () => this.backend_.loadBufferFromData(this.resolveUrl_(url), data));+ await this.ensureBuffer_(url, source => this.backend_.loadBufferFromData(source, data));}/**@@ -373,7 +436,7 @@ export class AudioAPI {if (this.disposed_) return null;const epoch = this.playbackEpoch_;try {- await this.ensureBuffer_(url, () => this.backend_.loadBuffer(url));+ await this.ensureBuffer_(url, source => this.backend_.loadBuffer(source), url);} catch {return null;}@@ -799,10 +862,9 @@ export class AudioAPI {// Closing a Web Audio context alone leaves their handles marked playing,// and a different backend may require explicit stops before disposal.this.stopAll();- for (const entry of this.bufferCache_.values()) {- this.backend_?.unloadBuffer(entry.handle);- }- this.bufferCache_.clear();+ 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();diff --git a/sdk/tests/audio-residency.test.ts b/sdk/tests/audio-residency.test.tsindex 68d424f8d..c7d2cebd5 100644--- a/sdk/tests/audio-residency.test.ts+++ b/sdk/tests/audio-residency.test.ts@@ -74,6 +74,123 @@ describe('AudioAPI buffer residency', () => {audio.setBufferBudget(1000);});+ function sharedSource() {+ let loaded = false;+ const handle: AudioBufferHandle = { id: 77, duration: 1, bytes: 100 };+ backend.loadBuffer = vi.fn(async () => { loaded = true; return handle; });+ backend.unloadBuffer = vi.fn(() => { loaded = false; });+ const play = backend.play;+ backend.play = vi.fn((buffer, config) => {+ if (!loaded) throw new Error('Shared buffer already unloaded');+ return play(buffer, config);+ });+ audio.setRefResolver(() => 'physical/shared.wav');+ audio.setBufferBudget(0);+ return handle;+ }++ it('keeps a shared physical buffer alive until both authored references release it', async () => {+ sharedSource();+ await audio.preload('alias-a'); audio.retainBuffer('alias-a');+ await audio.preload('alias-b'); audio.retainBuffer('alias-b');+ audio.releaseBuffer('alias-a');+ expect(() => audio.playSFX('alias-b')).not.toThrow();+ expect(backend.unloadBuffer).not.toHaveBeenCalled();+ audio.releaseBuffer('alias-a'); // already released; cannot spend B's hold+ expect(backend.unloadBuffer).not.toHaveBeenCalled();+ audio.releaseBuffer('alias-b');+ expect(backend.unloadBuffer).toHaveBeenCalledOnce();+ });++ it('counts shared decoded bytes once while keeping each authored hold separate', async () => {+ sharedSource();+ await audio.preload('alias-a'); audio.retainBuffer('alias-a');+ await audio.preload('alias-b'); audio.retainBuffer('alias-b');+ expect(audio.getBufferStats().bufferBytes).toBe(100);+ audio.releaseBuffer('alias-a');+ expect(audio.getBufferStats().bufferBytes).toBe(100);+ audio.releaseBuffer('alias-b');+ expect(audio.getBufferStats().bufferBytes).toBe(0);+ });++ it('invalidates every cached alias of the changed physical source', async () => {+ sharedSource();+ await audio.preload('alias-a'); audio.retainBuffer('alias-a');+ await audio.preload('alias-b'); audio.retainBuffer('alias-b');+ expect(audio.invalidateBuffer('alias-a')).toBe(true);+ expect(audio.getBufferHandle('alias-a')).toBeUndefined();+ expect(audio.getBufferHandle('alias-b')).toBeUndefined();+ expect(backend.unloadBuffer).toHaveBeenCalledOnce();+ });++ it('trims shared warm entries with one physical unload and one freed-buffer count', async () => {+ sharedSource();+ audio.setBufferBudget(1000);+ await audio.preload('alias-a');+ await audio.preload('alias-b');+ expect(audio.getBufferStats()).toMatchObject({ bufferCount: 2, bufferBytes: 100, evictableCount: 2 });+ expect(audio.trimBufferCache()).toBe(1);+ expect(backend.unloadBuffer).toHaveBeenCalledOnce();+ expect(audio.getBufferStats()).toMatchObject({ bufferCount: 0, bufferBytes: 0, evictableCount: 0 });+ });++ it('coalesces concurrent aliases and retires their invalidated result once', async () => {+ audio.setRefResolver(() => 'shared.wav');+ const finish: Array<(buffer: AudioBufferHandle) => void> = [];+ backend.loadBufferFromData = vi.fn(() => new Promise<AudioBufferHandle>(resolve => { finish.push(resolve); }));+ const a = audio.preloadFromData('a', new ArrayBuffer(8));+ const b = audio.preloadFromData('b', new ArrayBuffer(8));+ expect(backend.loadBufferFromData).toHaveBeenCalledOnce();+ expect(audio.invalidateBuffer('a')).toBe(true);+ const current = audio.preloadFromData('b', new ArrayBuffer(16));+ expect(backend.loadBufferFromData).toHaveBeenCalledTimes(2);+ finish[1]({ id: 2, duration: 2, bytes: 200 });+ await current;+ finish[0]({ id: 1, duration: 1, bytes: 100 });+ await Promise.all([a, b]);+ expect(backend.unloaded).toEqual([1]);+ expect(audio.getBufferHandle('a')).toBeUndefined();+ expect(audio.getBufferHandle('b')?.id).toBe(2);+ expect(audio.getBufferStats().bufferBytes).toBe(200);+ audio.dispose();+ expect(backend.unloaded).toEqual([1, 2]);+ });++ it('allows a shared source to retry after all concurrent aliases fail', async () => {+ audio.setRefResolver(() => 'shared.wav');+ let fail!: (reason: Error) => void;+ backend.loadBuffer = vi.fn(() => new Promise<AudioBufferHandle>((_resolve, reject) => { fail = reject; }));+ const a = audio.preload('a'), b = audio.preload('b');+ const done = Promise.allSettled([a, b]);+ fail(new Error('decode failed'));+ expect((await done).every(result => result.status === 'rejected')).toBe(true);+ expect(backend.loadBuffer).toHaveBeenCalledOnce();+ backend.loadBuffer = vi.fn(async () => ({ id: 2, duration: 2, bytes: 200 }));+ await audio.preload('a');+ expect(backend.loadBuffer).toHaveBeenCalledOnce();+ expect(audio.getBufferHandle('a')?.id).toBe(2);+ expect(audio.trimBufferCache()).toBe(1);+ });++ it('invalidates the source captured by a pending load when the resolver changes', async () => {+ let source = 'old.wav';+ audio.setRefResolver(() => source);+ const finish: Array<(buffer: AudioBufferHandle) => void> = [];+ backend.loadBuffer = vi.fn(() => new Promise<AudioBufferHandle>(resolve => { finish.push(resolve); }));+ backend.invalidateSource = vi.fn();+ const old = audio.preload('key');+ source = 'new.wav';+ audio.invalidateBuffer('key');+ expect(backend.invalidateSource).toHaveBeenCalledWith('old.wav');+ const current = audio.preload('key');+ finish[1]({ id: 2, duration: 2, bytes: 200 });+ await current;+ finish[0]({ id: 1, duration: 1, bytes: 100 });+ await old;+ expect(backend.unloaded).toEqual([1]);+ expect(audio.getBufferHandle('key')?.id).toBe(2);+ });+it.each([0, 1000])('releasing an old asset lease cannot release the replacement clip, budget=%i', async budget => {audio.setBufferBudget(budget);const assets = Assets.create({diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 913bba4bd..bff59be55 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -30,6 +30,8 @@ export const NOTES_FLOOR = 'v0.65.0';export const NOTED = {'fix(example): honor authored workshop obstacle state':{ note: 'Build and reroute deliveries in a textured 2D courtyard.' },+ 'fix(audio): share decoded ownership across source aliases':+ { note: 'Audio aliases share decoded buffer ownership.' },'fix(audio): preserve controls on loading effect handles':{ note: 'Loading sound-effect handles preserve playback controls.' },'fix(audio): stop all owned voices and pending starts':