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.

refactor: move audio backend creation into platform adapter layer

esenginefd0660c9ba04
diff --git a/sdk/src/audio/AudioBackendFactory.ts b/sdk/src/audio/AudioBackendFactory.ts
deleted file mode 100644
index e9268457d..000000000
--- a/sdk/src/audio/AudioBackendFactory.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import { WebAudioBackend } from './WebAudioBackend';
-import { WeChatAudioBackend } from './WeChatAudioBackend';
-import type { PlatformAudioBackend } from './PlatformAudioBackend';
-import { isWeChat } from '../platform/base';
-
-export function createAudioBackend(): PlatformAudioBackend {
- if (isWeChat()) {
- return new WeChatAudioBackend();
- }
- return new WebAudioBackend();
-}
diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.ts
index 9ab19e5ba..e491d8f40 100644
--- a/sdk/src/audio/AudioPlugin.ts
+++ b/sdk/src/audio/AudioPlugin.ts
@@ -5,8 +5,7 @@ import { Res, Time, type TimeData } from '../resource';
import { Audio } from './Audio';
import { AudioSource, AudioListener, type AudioSourceData, type AudioListenerData } from './AudioComponents';
import { WorldTransform, type WorldTransformData } from '../component';
-import { createAudioBackend } from './AudioBackendFactory';
-import { WebAudioBackend } from './WebAudioBackend';
+import { getPlatform } from '../platform/base';
import { calculateAttenuation, calculatePanning, type SpatialAudioConfig, AttenuationModel } from './SpatialAudio';
import type { AudioHandle } from './PlatformAudioBackend';
@@ -26,19 +25,12 @@ export class AudioPlugin implements Plugin {
}
build(app: App): void {
- const backend = createAudioBackend();
+ const backend = getPlatform().createAudioBackend();
const config = this.config_;
- if (backend instanceof WebAudioBackend) {
- backend.initialize({ initialPoolSize: config.initialPoolSize });
- } else {
- backend.initialize();
- }
+ backend.initialize({ initialPoolSize: config.initialPoolSize });
- let mixer = null;
- if (backend instanceof WebAudioBackend) {
- mixer = backend.mixer;
- }
+ const mixer = backend.mixer;
Audio.init(backend, mixer);
if (mixer) {
diff --git a/sdk/src/audio/PlatformAudioBackend.ts b/sdk/src/audio/PlatformAudioBackend.ts
index b919f115a..e52141953 100644
--- a/sdk/src/audio/PlatformAudioBackend.ts
+++ b/sdk/src/audio/PlatformAudioBackend.ts
@@ -1,3 +1,6 @@
+import type { AudioMixer } from './AudioMixer';
+import type { AudioMixerConfig } from './AudioMixer';
+
export interface AudioHandle {
readonly id: number;
stop(): void;
@@ -28,9 +31,15 @@ export interface PlayConfig {
startOffset?: number;
}
+export interface AudioBackendInitOptions {
+ initialPoolSize?: number;
+ mixerConfig?: AudioMixerConfig;
+}
+
export interface PlatformAudioBackend {
readonly name: string;
- initialize(): Promise<void>;
+ readonly mixer: AudioMixer | null;
+ initialize(options?: AudioBackendInitOptions): Promise<void>;
ensureResumed(): Promise<void>;
loadBuffer(url: string): Promise<AudioBufferHandle>;
unloadBuffer(handle: AudioBufferHandle): void;
diff --git a/sdk/src/audio/WeChatAudioBackend.ts b/sdk/src/audio/WeChatAudioBackend.ts
index c65f6531f..cdeecea1f 100644
--- a/sdk/src/audio/WeChatAudioBackend.ts
+++ b/sdk/src/audio/WeChatAudioBackend.ts
@@ -1,4 +1,5 @@
-import type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend } from './PlatformAudioBackend';
+import type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend, AudioBackendInitOptions } from './PlatformAudioBackend';
+import type { AudioMixer } from './AudioMixer';
interface WxInnerAudioContext {
src: string;
@@ -84,7 +85,11 @@ export class WeChatAudioBackend implements PlatformAudioBackend {
private urlCache_ = new Map<number, string>();
private nextId_ = 0;
- async initialize(): Promise<void> {
+ get mixer(): AudioMixer | null {
+ return null;
+ }
+
+ async initialize(_options?: AudioBackendInitOptions): Promise<void> {
// wx.createInnerAudioContext does not require global initialization
}
diff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.ts
index 6e268fcb1..3817f9fb5 100644
--- a/sdk/src/audio/WebAudioBackend.ts
+++ b/sdk/src/audio/WebAudioBackend.ts
@@ -1,5 +1,5 @@
-import type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend } from './PlatformAudioBackend';
-import { AudioMixer, type AudioMixerConfig } from './AudioMixer';
+import type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend, AudioBackendInitOptions } from './PlatformAudioBackend';
+import { AudioMixer } from './AudioMixer';
import { AudioPool, type PooledAudioNode } from './AudioPool';
class WebAudioHandle implements AudioHandle {
@@ -129,11 +129,6 @@ class WebAudioHandle implements AudioHandle {
}
}
-export interface WebAudioBackendOptions {
- initialPoolSize?: number;
- mixerConfig?: AudioMixerConfig;
-}
-
export class WebAudioBackend implements PlatformAudioBackend {
readonly name = 'WebAudio';
@@ -141,6 +136,8 @@ export class WebAudioBackend implements PlatformAudioBackend {
private mixer_: AudioMixer | null = null;
private pool_: AudioPool | null = null;
private buffers_ = new Map<number, AudioBuffer>();
+ private urlToId_ = new Map<string, number>();
+ private loadingUrls_ = new Map<string, Promise<AudioBufferHandle>>();
private nextBufferId_ = 0;
private nextHandleId_ = 0;
private resumeHandler_: (() => void) | null = null;
@@ -149,7 +146,7 @@ export class WebAudioBackend implements PlatformAudioBackend {
return this.mixer_;
}
- async initialize(options: WebAudioBackendOptions = {}): Promise<void> {
+ async initialize(options: AudioBackendInitOptions = {}): Promise<void> {
this.context_ = new AudioContext();
this.mixer_ = new AudioMixer(this.context_, options.mixerConfig);
this.pool_ = new AudioPool(this.context_, options.initialPoolSize);
@@ -179,12 +176,41 @@ export class WebAudioBackend implements PlatformAudioBackend {
if (!this.context_) {
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 };
+ }
+
+ const inFlight = this.loadingUrls_.get(url);
+ if (inFlight) return inFlight;
+
+ const promise = this.doLoadBuffer_(url);
+ this.loadingUrls_.set(url, promise);
+ try {
+ return await promise;
+ } finally {
+ this.loadingUrls_.delete(url);
+ }
+ }
+
+ private async doLoadBuffer_(url: string): Promise<AudioBufferHandle> {
const response = await fetch(url);
+ if (!response.ok) {
+ throw new Error(`Failed to load audio: ${url} (${response.status})`);
+ }
const arrayBuffer = await response.arrayBuffer();
- const audioBuffer = await this.context_.decodeAudioData(arrayBuffer);
+ let audioBuffer: AudioBuffer;
+ try {
+ audioBuffer = await this.context_!.decodeAudioData(arrayBuffer);
+ } catch (err) {
+ throw new Error(`Failed to decode audio ${url}: ${(err as Error).message}`);
+ }
const id = ++this.nextBufferId_;
this.buffers_.set(id, audioBuffer);
+ this.urlToId_.set(url, id);
return { id, duration: audioBuffer.duration };
}
@@ -203,7 +229,7 @@ export class WebAudioBackend implements PlatformAudioBackend {
throw new Error(`Buffer ${buffer.id} not found`);
}
- const poolNode = this.pool_.acquire(config.priority ?? 0);
+ const poolNode = this.pool_.acquire();
const source = this.context_.createBufferSource();
source.buffer = audioBuffer;
source.loop = config.loop ?? false;
diff --git a/sdk/src/audio/index.ts b/sdk/src/audio/index.ts
index eb9e4d0be..9e4fccb59 100644
--- a/sdk/src/audio/index.ts
+++ b/sdk/src/audio/index.ts
@@ -4,8 +4,7 @@ export { AudioMixer, type AudioMixerConfig } from './AudioMixer';
export { AudioPool, type PooledAudioNode } from './AudioPool';
export { AudioPlugin, audioPlugin, type AudioPluginConfig } from './AudioPlugin';
export { AudioSource, AudioListener, type AudioSourceData, type AudioListenerData } from './AudioComponents';
-export { createAudioBackend } from './AudioBackendFactory';
export { AttenuationModel, calculateAttenuation, calculatePanning, type SpatialAudioConfig } from './SpatialAudio';
-export { WebAudioBackend, type WebAudioBackendOptions } from './WebAudioBackend';
+export { WebAudioBackend } from './WebAudioBackend';
export { WeChatAudioBackend } from './WeChatAudioBackend';
-export type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend } from './PlatformAudioBackend';
+export type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend, AudioBackendInitOptions } from './PlatformAudioBackend';
diff --git a/sdk/src/platform/base.ts b/sdk/src/platform/base.ts
index 1e5407847..e356d9f89 100644
--- a/sdk/src/platform/base.ts
+++ b/sdk/src/platform/base.ts
@@ -106,6 +106,10 @@ export function platformNow(): number {
return getPlatform().now();
}
+export function platformCreateAudioBackend(): import('../audio/PlatformAudioBackend').PlatformAudioBackend {
+ return getPlatform().createAudioBackend();
+}
+
export function platformDevicePixelRatio(): number {
if (currentPlatform?.name === 'wechat') {
const g = globalThis as any;
diff --git a/sdk/src/platform/index.ts b/sdk/src/platform/index.ts
index 9b2942302..e483094ee 100644
--- a/sdk/src/platform/index.ts
+++ b/sdk/src/platform/index.ts
@@ -30,6 +30,7 @@ export {
platformCreateCanvas,
platformCreateImage,
platformNow,
+ platformCreateAudioBackend,
platformDevicePixelRatio,
} from './base';
diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.ts
index 33be67a5a..e341b231d 100644
--- a/sdk/src/platform/types.ts
+++ b/sdk/src/platform/types.ts
@@ -90,6 +90,8 @@ export interface PlatformAdapter {
createImage(): HTMLImageElement;
bindInputEvents(callbacks: InputEventCallbacks, target?: unknown): void;
+
+ createAudioBackend(): import('../audio/PlatformAudioBackend').PlatformAudioBackend;
}
// =============================================================================
diff --git a/sdk/src/platform/web.ts b/sdk/src/platform/web.ts
index 94e9d701b..0d89903a3 100644
--- a/sdk/src/platform/web.ts
+++ b/sdk/src/platform/web.ts
@@ -11,6 +11,8 @@ import type {
InputEventCallbacks,
ImageLoadResult,
} from './types';
+import { WebAudioBackend } from '../audio/WebAudioBackend';
+import type { PlatformAudioBackend } from '../audio/PlatformAudioBackend';
const WHEEL_LINE_HEIGHT = 16;
@@ -205,6 +207,10 @@ class WebPlatformAdapter implements PlatformAdapter {
this.inputCleanup_ = null;
}
}
+
+ createAudioBackend(): PlatformAudioBackend {
+ return new WebAudioBackend();
+ }
}
// =============================================================================
diff --git a/sdk/src/platform/wechat/index.ts b/sdk/src/platform/wechat/index.ts
index 9300d271b..9935bbcc0 100644
--- a/sdk/src/platform/wechat/index.ts
+++ b/sdk/src/platform/wechat/index.ts
@@ -13,6 +13,8 @@ import type {
InputEventCallbacks,
ImageLoadResult,
} from '../types';
+import { WeChatAudioBackend } from '../../audio/WeChatAudioBackend';
+import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';
import { wxFetch, polyfillFetch } from './fetch';
import { wxInstantiateWasm, polyfillWebAssembly } from './wasm';
import { wxReadFileSync, wxReadTextFileSync, wxFileExistsSync } from './fs';
@@ -130,6 +132,10 @@ class WeChatPlatformAdapter implements PlatformAdapter {
this.inputCleanup_ = null;
}
}
+
+ createAudioBackend(): PlatformAudioBackend {
+ return new WeChatAudioBackend();
+ }
}
// =============================================================================
diff --git a/sdk/tests/audio-backend-factory.test.ts b/sdk/tests/audio-backend-factory.test.ts
index 893943c5e..2d587ddba 100644
--- a/sdk/tests/audio-backend-factory.test.ts
+++ b/sdk/tests/audio-backend-factory.test.ts
@@ -1,21 +1,47 @@
import { describe, it, expect, beforeEach } from 'vitest';
-import { createAudioBackend } from '../src/audio/AudioBackendFactory';
import { setPlatform } from '../src/platform/base';
import { WebAudioBackend } from '../src/audio/WebAudioBackend';
import { WeChatAudioBackend } from '../src/audio/WeChatAudioBackend';
+import type { PlatformAdapter } from '../src/platform/types';
-describe('AudioBackendFactory', () => {
- describe('createAudioBackend', () => {
- it('should return WebAudioBackend for web platform', () => {
- setPlatform({ name: 'web' } as any);
- const backend = createAudioBackend();
- expect(backend).toBeInstanceOf(WebAudioBackend);
- });
+function createMockPlatform(name: 'web' | 'wechat'): PlatformAdapter {
+ return {
+ name,
+ fetch: async () => ({} as any),
+ readFile: async () => new ArrayBuffer(0),
+ readTextFile: async () => '',
+ fileExists: async () => false,
+ loadImagePixels: async () => ({ width: 0, height: 0, pixels: new Uint8Array() }),
+ instantiateWasm: async () => ({} as any),
+ createCanvas: () => ({} as any),
+ now: () => 0,
+ createImage: () => ({} as any),
+ bindInputEvents: () => {},
+ createAudioBackend: () => {
+ if (name === 'wechat') return new WeChatAudioBackend();
+ return new WebAudioBackend();
+ },
+ };
+}
- it('should return WeChatAudioBackend for wechat platform', () => {
- setPlatform({ name: 'wechat' } as any);
- const backend = createAudioBackend();
- expect(backend).toBeInstanceOf(WeChatAudioBackend);
- });
+describe('PlatformAdapter.createAudioBackend', () => {
+ it('should return WebAudioBackend for web platform', () => {
+ const platform = createMockPlatform('web');
+ setPlatform(platform);
+ const backend = platform.createAudioBackend();
+ expect(backend).toBeInstanceOf(WebAudioBackend);
+ });
+
+ it('should return WeChatAudioBackend for wechat platform', () => {
+ const platform = createMockPlatform('wechat');
+ setPlatform(platform);
+ const backend = platform.createAudioBackend();
+ expect(backend).toBeInstanceOf(WeChatAudioBackend);
+ });
+
+ it('should return backend with mixer=null for WeChat', () => {
+ const platform = createMockPlatform('wechat');
+ const backend = platform.createAudioBackend();
+ expect(backend.mixer).toBeNull();
});
});