Skip to content

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.

fix(audio): retire source records with owned buffers

yhh5ed9c4e37044
diff --git a/CHANGELOG.md b/CHANGELOG.md
index beaba7cc7..fc0c102e4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Web audio source records follow live buffer ownership.** URL cache entries and invalidation identities retire after their current buffer and pending loads are released, instead of retaining every historical scene path. Distinct source records preserve overlapping invalidated loads, and unloading an older result leaves the replacement cached; failed loads release their records too.
+
- **Web UI getters can reach their generated pointer accessors.** The optional UINode pointer export avoids full component object marshaling for pre-resolved readers, with existing generated layout assertions and fresh pointer resolution after pool growth. Live focus queries use compact per-query visibility flags and pre-resolved parent reads to reduce transient work; older cores retain the getter fallback.
- **Ineligible text fields reject late editing callbacks immediately.** Hidden fields and controls outside a newly opened modal cannot commit delayed changes, composition endings or submissions. The rejected session releases its OS editing surface and preedit state, so eligibility returning before another frame reattaches the committed value instead of replaying stale input; fields inside the active dialog remain editable.
diff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.ts
index 698e21888..61f801ae7 100644
--- a/sdk/src/audio/WebAudioBackend.ts
+++ b/sdk/src/audio/WebAudioBackend.ts
@@ -153,6 +153,16 @@ function decodedBytes(buf: AudioBuffer): number {
return buf.length * buf.numberOfChannels * 4;
}
+interface BufferRecord {
+ buffer: AudioBuffer;
+ url: string;
+}
+
+interface SourceRecord {
+ pending: number;
+ bufferId?: number;
+}
+
export class WebAudioBackend implements PlatformAudioBackend {
readonly name = 'WebAudio';
readonly delivery = 'bytes' as const;
@@ -160,10 +170,10 @@ export class WebAudioBackend implements PlatformAudioBackend {
private context_: AudioContext | null = null;
private mixer_: AudioMixer | null = null;
private pool_: AudioPool | null = null;
- private buffers_ = new Map<number, AudioBuffer>();
- private urlToId_ = new Map<string, number>();
+ private buffers_ = new Map<number, BufferRecord>();
private loadingUrls_ = new Map<string, Promise<AudioBufferHandle>>();
- private sourceRevisions_ = new Map<string, number>();
+ /** Only current cached or pending sources; identity separates invalidated loads. */
+ private sources_ = new Map<string, SourceRecord>();
private nextBufferId_ = 0;
private nextHandleId_ = 0;
private resumeHandler_: (() => void) | null = null;
@@ -256,16 +266,13 @@ export class WebAudioBackend implements PlatformAudioBackend {
throw new Error('AudioContext not initialized');
}
- const existingId = this.urlToId_.get(url);
- if (existingId !== undefined && this.buffers_.has(existingId)) {
- const buf = this.buffers_.get(existingId)!;
- return { id: existingId, duration: buf.duration, bytes: decodedBytes(buf) };
- }
+ const cached = this.cachedBuffer_(url);
+ if (cached) return cached;
const inFlight = this.loadingUrls_.get(url);
if (inFlight) return inFlight;
- const promise = this.doLoadBuffer_(url, this.sourceRevisions_.get(url) ?? 0);
+ const promise = this.loadSource_(url, () => getPlatform().readFile(url));
this.loadingUrls_.set(url, promise);
try {
return await promise;
@@ -275,18 +282,45 @@ export class WebAudioBackend implements PlatformAudioBackend {
}
async loadBufferFromData(url: string, data: ArrayBuffer): Promise<AudioBufferHandle> {
- return this.decodeBuffer_(url, data, this.sourceRevisions_.get(url) ?? 0);
+ return this.loadSource_(url, async () => data);
}
- private async decodeBuffer_(url: string, data: ArrayBuffer, revision: number): Promise<AudioBufferHandle> {
+ private cachedBuffer_(url: string): AudioBufferHandle | null {
+ const id = this.sources_.get(url)?.bufferId;
+ if (id === undefined) return null;
+ const record = this.buffers_.get(id);
+ return record ? { id, duration: record.buffer.duration, bytes: decodedBytes(record.buffer) } : null;
+ }
+
+ private async loadSource_(url: string, read: () => Promise<ArrayBuffer>): Promise<AudioBufferHandle> {
if (!this.context_) {
throw new Error('AudioContext not initialized');
}
+ const cached = this.cachedBuffer_(url);
+ if (cached) return cached;
+ let source = this.sources_.get(url);
+ if (!source) {
+ source = { pending: 0 };
+ this.sources_.set(url, source);
+ }
+ source.pending++;
+ try {
+ return await this.decodeBuffer_(url, await read(), source);
+ } finally {
+ source.pending--;
+ if (this.sources_.get(url) === source && source.pending === 0 && source.bufferId === undefined) {
+ this.sources_.delete(url);
+ }
+ }
+ }
- const existingId = this.urlToId_.get(url);
- if (revision === (this.sourceRevisions_.get(url) ?? 0) && existingId !== undefined && this.buffers_.has(existingId)) {
- const buf = this.buffers_.get(existingId)!;
- return { id: existingId, duration: buf.duration, bytes: decodedBytes(buf) };
+ private async decodeBuffer_(url: string, data: ArrayBuffer, source: SourceRecord): Promise<AudioBufferHandle> {
+ if (!this.context_) {
+ throw new Error('AudioContext not initialized');
+ }
+ if (this.sources_.get(url) === source) {
+ const cached = this.cachedBuffer_(url);
+ if (cached) return cached;
}
let audioBuffer: AudioBuffer;
@@ -297,25 +331,26 @@ export class WebAudioBackend implements PlatformAudioBackend {
}
const id = ++this.nextBufferId_;
- this.buffers_.set(id, audioBuffer);
- if (revision === (this.sourceRevisions_.get(url) ?? 0)) this.urlToId_.set(url, id);
+ this.buffers_.set(id, { buffer: audioBuffer, url });
+ if (this.sources_.get(url) === source) source.bufferId = id;
return { id, duration: audioBuffer.duration, bytes: decodedBytes(audioBuffer) };
}
- private async doLoadBuffer_(url: string, revision: number): Promise<AudioBufferHandle> {
- const arrayBuffer = await getPlatform().readFile(url);
- return this.decodeBuffer_(url, arrayBuffer, revision);
- }
-
invalidateSource(url: string): void {
- this.sourceRevisions_.set(url, (this.sourceRevisions_.get(url) ?? 0) + 1);
+ this.sources_.delete(url);
this.loadingUrls_.delete(url);
- this.urlToId_.delete(url);
}
unloadBuffer(handle: AudioBufferHandle): void {
+ const record = this.buffers_.get(handle.id);
+ if (!record) return;
this.buffers_.delete(handle.id);
+ const source = this.sources_.get(record.url);
+ if (source?.bufferId === handle.id) {
+ delete source.bufferId;
+ if (source.pending === 0) this.sources_.delete(record.url);
+ }
}
play(buffer: AudioBufferHandle, config: PlayConfig): AudioHandle {
@@ -323,7 +358,7 @@ export class WebAudioBackend implements PlatformAudioBackend {
throw new Error('Audio system not initialized');
}
- const audioBuffer = this.buffers_.get(buffer.id);
+ const audioBuffer = this.buffers_.get(buffer.id)?.buffer;
if (!audioBuffer) {
throw new Error(`Buffer ${buffer.id} not found`);
}
@@ -389,7 +424,7 @@ export class WebAudioBackend implements PlatformAudioBackend {
this.pool_ = null;
this.mixer_ = null;
this.buffers_.clear();
- this.urlToId_.clear();
+ this.sources_.clear();
this.loadingUrls_.clear();
this.context_?.close();
this.context_ = null;
diff --git a/sdk/tests/web-audio-backend.test.ts b/sdk/tests/web-audio-backend.test.ts
index 685d50807..361a47507 100644
--- a/sdk/tests/web-audio-backend.test.ts
+++ b/sdk/tests/web-audio-backend.test.ts
@@ -211,6 +211,33 @@ describe('WebAudioBackend', () => {
});
describe('loadBuffer', () => {
+ it.each([false, true])('retires source metadata after buffer release (invalidate=%s)', async invalidate => {
+ await backend.initialize();
+ const ctx = (globalThis as any).__mockAudioContext;
+ ctx.decodeAudioData.mockResolvedValue({ duration: 1, length: 8, numberOfChannels: 1 });
+ for (let i = 0; i < 2000; i++) {
+ const url = `scene-${i}/sound.wav`;
+ const handle = await backend.loadBuffer(url);
+ backend.unloadBuffer(handle);
+ if (invalidate) backend.invalidateSource(url);
+ }
+ const retained = Object.values(backend).filter(value => value instanceof Map)
+ .reduce((count, map) => count + map.size, 0);
+ expect(retained).toBe(0);
+ });
+
+ it('does not retain metadata for failed source loads', async () => {
+ await backend.initialize();
+ const platform = (globalThis as any).__mockPlatform;
+ platform.readFile.mockRejectedValue(new Error('missing file'));
+ for (let i = 0; i < 25; i++) {
+ await expect(backend.loadBuffer(`missing-${i}.wav`)).rejects.toThrow('missing file');
+ }
+ const retained = Object.values(backend).filter(value => value instanceof Map)
+ .reduce((count, map) => count + map.size, 0);
+ expect(retained).toBe(0);
+ });
+
it.each(['old-first', 'new-first'] as const)('keeps the current URL load when an invalidated read finishes %s', async order => {
await backend.initialize();
const ctx = (globalThis as any).__mockAudioContext;
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 3137bd959..13682b248 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 = {
+ 'fix(audio): retire source records with owned buffers':
+ { note: 'Web audio source records follow live buffer ownership.' },
'perf(ui): use generated web pointers for live focus checks':
{ note: 'Web UI getters can reach their generated pointer accessors.' },
'fix(ui): retire text sessions when focus eligibility changes':