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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file MiniGameAudioBackend.ts
* @brief Audio for the mini-game platform family — one player per sound over
* the host's `createInnerAudioContext()`.
*
* Written against the normalized {@link MiniGameInnerAudioContext}, not
* `wx`, so every vendor of the family gets it without an implementation
* of its own. There is no mixer: mini-game hosts expose finished
* players, not a DSP graph, so routing labels are honored by the engine
* and the graph itself is absent (`mixer` is null by contract).
*/
import type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend, AudioBackendInitOptions, AudioLoadOptions } from './PlatformAudioBackend';
import type { AudioMixer } from './AudioMixer';
import type { MiniGameGlobal, MiniGameInnerAudioContext } from '../platform/minigame/api';
import { scalar } from '../math/scalar';
import { log } from '../util/logger';
interface MiniGameAudioDeviceState {
suspended: boolean;
pending: Map<number, MiniGameInnerAudioContext>;
}
class MiniGameAudioHandle implements AudioHandle {
readonly id: number;
onEnd?: () => void;
private ctx_: MiniGameInnerAudioContext;
private contexts_: Map<number, MiniGameInnerAudioContext>;
private done_ = false;
constructor(id: number, ctx: MiniGameInnerAudioContext, contexts: Map<number, MiniGameInnerAudioContext>,
private readonly device_: MiniGameAudioDeviceState) {
this.id = id;
this.ctx_ = ctx;
this.contexts_ = contexts;
}
private isLive_(): boolean {
return !this.done_ && this.contexts_.get(this.id) === this.ctx_;
}
// Guarded so stop() after a natural end (or a double stop()) can't destroy the
// audio context twice — the second destroy() throws on-device.
private dispose_(alsoStop: boolean): void {
if (!this.isLive_()) return;
this.done_ = true;
this.contexts_.delete(this.id);
this.device_.pending.delete(this.id);
try {
if (alsoStop) this.ctx_.stop();
} finally {
this.ctx_.destroy();
}
}
stop(): void {
this.dispose_(true);
}
/** Where a loop comes back to when it is not the start; the host's own loop only knows the start. */
private loopFrom_ = 0;
private looping_ = false;
/** @internal A loop that comes back to @p seconds: the context is not left to loop, and is sent back when it ends. */
loopFrom(seconds: number): void {
this.loopFrom_ = seconds;
this.looping_ = true;
this.ctx_.loop = false;
}
/** @internal The context ended on its own — dispose without a redundant stop(). */
onNaturalEnd(): void {
if (!this.isLive_() || this.ctx_.loop) return;
if (this.looping_) {
// A context that has ended starts from its startTime when it is played again.
this.ctx_.startTime = this.loopFrom_;
this.resume();
return;
}
this.dispose_(false);
this.onEnd?.();
}
pause(): void {
if (!this.isLive_()) return;
this.device_.pending.delete(this.id);
this.ctx_.pause();
}
resume(): void {
if (!this.isLive_()) return;
if (this.device_.suspended) this.device_.pending.set(this.id, this.ctx_);
else this.ctx_.play();
}
setVolume(volume: number): void {
if (!this.isLive_()) return;
// The host's volume is only valid in [0,1] — out-of-range writes are
// rejected on-device rather than clamped.
this.ctx_.volume = scalar.clamp01(volume);
}
private panWarned_ = false;
setPan(_pan: number): void {
if (!this.isLive_()) return;
if (!this.panWarned_) {
log.warn('audio', 'mini-game audio contexts do not support stereo panning');
this.panWarned_ = true;
}
}
setLoop(loop: boolean): void {
if (!this.isLive_()) return;
if (this.loopFrom_ > 0) this.looping_ = loop;
else this.ctx_.loop = loop;
}
setPlaybackRate(rate: number): void {
if (!this.isLive_()) return;
this.ctx_.playbackRate = rate;
}
get isPlaying(): boolean {
// Device suspension preserves playback intent, like a suspended WebAudio context.
return this.isLive_() && (!this.ctx_.paused || this.device_.pending.get(this.id) === this.ctx_);
}
get currentTime(): number {
return this.isLive_() ? this.ctx_.currentTime : 0;
}
get duration(): number {
return this.ctx_.duration;
}
}
export class MiniGameAudioBackend implements PlatformAudioBackend {
readonly name: string;
// The host owns the fetch: a player is handed a `src` and streams it.
readonly delivery = 'url' as const;
private readonly g_: MiniGameGlobal;
private contexts_ = new Map<number, MiniGameInnerAudioContext>();
private readonly device_: MiniGameAudioDeviceState = { suspended: false, pending: new Map() };
private urlCache_ = new Map<number, string>();
/** The silence encoding put before a clip the exporter re-encoded, by buffer: a player is started past it. */
private leads_ = new Map<number, number>();
private nextId_ = 0;
constructor(global: MiniGameGlobal, label = 'MiniGame') {
this.g_ = global;
this.name = label;
}
get mixer(): AudioMixer | null {
return null;
}
get isReady(): boolean {
return true;
}
async initialize(_options?: AudioBackendInitOptions): Promise<void> {
// createInnerAudioContext does not require global initialization
}
async ensureResumed(): Promise<void> {
// Mini-game hosts do not gate playback on a user gesture
}
async loadBuffer(src: string, options?: AudioLoadOptions): Promise<AudioBufferHandle> {
const id = ++this.nextId_;
this.urlCache_.set(id, src);
// The player decodes the file itself and its length is not known here, so the lead the exporter measured is taken as it is.
if (options?.trim && options.trim.lead > 0) this.leads_.set(id, options.trim.lead);
return { id, duration: options?.trim?.seconds ?? 0 };
}
/** No decoder here — the player streams from `src`, and the bytes are dropped.
* Callers avoid the wasted fetch by reading {@link delivery} first. */
async loadBufferFromData(src: string, _data: ArrayBuffer, options?: AudioLoadOptions): Promise<AudioBufferHandle> {
return this.loadBuffer(src, options);
}
unloadBuffer(handle: AudioBufferHandle): void {
this.leads_.delete(handle.id);
this.urlCache_.delete(handle.id);
}
play(buffer: AudioBufferHandle, config: PlayConfig): AudioHandle {
const url = this.urlCache_.get(buffer.id);
if (!url) {
throw new Error(`Buffer ${buffer.id} not found`);
}
const ctx = this.g_.createInnerAudioContext();
ctx.loop = config.loop ?? false;
ctx.volume = scalar.clamp01(config.volume ?? 1.0);
ctx.playbackRate = config.playbackRate ?? 1.0;
const lead = this.leads_.get(buffer.id) ?? 0;
ctx.startTime = lead + (config.startOffset ?? 0);
ctx.obeyMuteSwitch = false;
const handleId = ++this.nextId_;
this.contexts_.set(handleId, ctx);
const handle = new MiniGameAudioHandle(handleId, ctx, this.contexts_, this.device_);
// Sent back past the lead each time round as well, where the host's own loop would play it again.
if (config.loop && ((config.loopStart && config.loopStart > 0) || lead > 0)) handle.loopFrom(lead + (config.loopStart ?? 0));
ctx.onEnded(() => handle.onNaturalEnd());
ctx.onError((res) => {
log.error('audio', `Playback error for "${url}"`, res.errMsg);
});
ctx.src = url;
handle.resume();
return handle;
}
suspend(): void {
if (this.device_.suspended) return;
this.device_.suspended = true;
for (const [id, ctx] of this.contexts_) {
if (ctx.paused) continue;
this.device_.pending.set(id, ctx);
ctx.pause();
}
}
resume(): void {
if (!this.device_.suspended) return;
this.device_.suspended = false;
for (const [id, ctx] of this.device_.pending) {
this.device_.pending.delete(id);
if (this.contexts_.get(id) === ctx && ctx.paused) {
ctx.play();
}
if (this.device_.suspended) break;
}
}
dispose(): void {
this.device_.suspended = false;
this.device_.pending.clear();
for (const ctx of this.contexts_.values()) {
ctx.destroy();
}
this.contexts_.clear();
this.urlCache_.clear();
}
}