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): preserve latest Web device suspension intent

yhh196653bbd289
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a292908d..f46441d02 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,8 @@ published separately; it ships inside the editor.
- **Collapsed 2D hierarchies skip geometry and recover reliably.** Transform composition propagates authored zero-area state through planar rotations and transformless groups, preventing floating-point residue from reviving degenerate boxes. Sprite, UI, native bitmap text, picking and empty scissor/stencil subtrees share the guard. Valid tiny spans and children that regain area through a 3D tilt remain available; hidden bitmap runs skip font layout and submission.
+- **Web audio preserves the latest device pause intent.** Late browser resume/suspend operations cannot undo a newer takeover request; initial autoplay-unlock gestures and ensureResumed respect explicit suspension. Reconciliation stops at the current request and ignores disposed contexts, preserving the user mixer and avoiding retry loops for blocked playback.
+
- **Advertising requests preserve a single active break.** Rewarded and interstitial requests reject immediately while another ad is showing, before creating a competing unit. The active break retains its showing flag, clock pause and audio suspension until it closes; errors release the guard so a later request can proceed. Rejected requests are not queued for playback.
- **UI geometry, picking and scissors retain parent-induced shear.** Solid, image, nine-slice, tiled and filled visuals use the complete parent basis for vertices and camera bounds. UI, editor and world-sprite picking test the same local boxes, and scissor bounds project their actual corners. Mirrored radial fills retain their wedges and UVs; axis-aligned positive UI keeps its existing geometry path.
@@ -28,6 +30,8 @@ published separately; it ships inside the editor.
### Added
+- **Poki training reports authored gameplay and ad outcomes.** The mobile-controls example adds a named Poki Web profile with explicit start, pause, three-hit completion, replay and opt-in reward controls. Device actions and returning to the page never infer gameplay start; rewards require completion, background and scene cleanup preserve state, and missing SDKs leave training usable. Headless CI checks real input, event order, audio transitions, landscape rotation and the original standalone controls using SDK mocks.
+
- **Web exports can select the Poki channel.** Project and named export settings inject its official SDK, initialize it with a bounded fallback, report loading after the scene is ready and connect rewarded/commercial breaks to the existing Ads service. The editor exposes the channel choice; standalone keeps its original resource policy. Game logic still reports gameplay transitions explicitly, and official Inspector/device acceptance remains pending.
- **Playable scenarios run in headless Chromium and save bound evidence.** A CLI replays declared canvas clicks and host callbacks, records trusted pointers and user activation, checks hidden input and animation, and fails on unexpected requests, page errors, event mismatches, lost history or changed inputs. Reports and screenshots retain delivery/scenario/tool hashes and pending acceptance; eight network mocks run on the example in CI using that commit's Web runtime. No local editor or browser window is opened.
diff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.ts
index a54b1c544..796819499 100644
--- a/sdk/src/audio/WebAudioBackend.ts
+++ b/sdk/src/audio/WebAudioBackend.ts
@@ -4,6 +4,7 @@ import type { AudioHandle, AudioBufferHandle, PlayConfig, PlatformAudioBackend,
import { AudioMixer } from './AudioMixer';
import { AudioPool, type PooledAudioNode } from './AudioPool';
import { getPlatform } from '../platform/base';
+import { log } from '../util/logger';
class WebAudioHandle implements AudioHandle {
readonly id: number;
@@ -157,6 +158,9 @@ export class WebAudioBackend implements PlatformAudioBackend {
private nextBufferId_ = 0;
private nextHandleId_ = 0;
private resumeHandler_: (() => void) | null = null;
+ private explicitlySuspended_ = false;
+ private deviceIntentRevision_ = 0;
+ private contextGeneration_ = 0;
private analyser_: AnalyserNode | null = null;
get mixer(): AudioMixer | null {
@@ -168,6 +172,9 @@ export class WebAudioBackend implements PlatformAudioBackend {
}
async initialize(options: AudioBackendInitOptions = {}): Promise<void> {
+ this.contextGeneration_++;
+ this.deviceIntentRevision_++;
+ this.explicitlySuspended_ = false;
this.context_ = new AudioContext();
this.mixer_ = new AudioMixer(this.context_, options.mixerConfig);
this.pool_ = new AudioPool(this.context_, options.initialPoolSize);
@@ -181,7 +188,8 @@ export class WebAudioBackend implements PlatformAudioBackend {
if (this.context_.state === 'suspended') {
const resume = () => {
- this.context_!.resume();
+ if (this.explicitlySuspended_) return;
+ this.resume();
document.removeEventListener('touchstart', resume);
document.removeEventListener('mousedown', resume);
document.removeEventListener('keydown', resume);
@@ -195,11 +203,45 @@ export class WebAudioBackend implements PlatformAudioBackend {
}
async ensureResumed(): Promise<void> {
- if (this.context_ && this.context_.state === 'suspended') {
- await this.context_.resume();
+ if (!this.explicitlySuspended_ && this.context_?.state === 'suspended') {
+ await this.requestDeviceIntent_(false);
}
}
+ private requestDeviceIntent_(suspended: boolean): Promise<void> {
+ if (this.explicitlySuspended_ !== suspended) {
+ this.explicitlySuspended_ = suspended;
+ this.deviceIntentRevision_++;
+ }
+ const revision = this.deviceIntentRevision_;
+ const context = this.context_;
+ if (!context || context.state === 'closed') return Promise.resolve();
+ return this.applyDeviceIntent_(context, suspended, revision, this.contextGeneration_);
+ }
+
+ private async applyDeviceIntent_(context: AudioContext, suspended: boolean, revision: number, generation: number): Promise<void> {
+ // Invoke synchronously to preserve the original user-gesture stack.
+ await (suspended ? context.suspend() : context.resume());
+ if (context !== this.context_ || generation !== this.contextGeneration_ || context.state === 'closed') return;
+ // Browser transitions can settle out of order. Reapply the latest intent
+ // only when a newer request superseded this operation; blocked autoplay
+ // or an OS interruption must not produce an unbounded retry loop.
+ if (revision !== this.deviceIntentRevision_
+ && context.state !== (this.explicitlySuspended_ ? 'suspended' : 'running')) {
+ await this.applyDeviceIntent_(context, this.explicitlySuspended_, this.deviceIntentRevision_, generation);
+ }
+ }
+
+ private fireDeviceIntent_(suspended: boolean): void {
+ const context = this.context_;
+ const generation = this.contextGeneration_;
+ void this.requestDeviceIntent_(suspended).catch(error => {
+ if (context === this.context_ && generation === this.contextGeneration_) {
+ log.warn('audio', 'Audio device transition failed', error);
+ }
+ });
+ }
+
async loadBuffer(url: string): Promise<AudioBufferHandle> {
if (!this.context_) {
throw new Error('AudioContext not initialized');
@@ -312,14 +354,17 @@ export class WebAudioBackend implements PlatformAudioBackend {
}
suspend(): void {
- this.context_?.suspend();
+ this.fireDeviceIntent_(true);
}
resume(): void {
- this.context_?.resume();
+ this.fireDeviceIntent_(false);
}
dispose(): void {
+ this.contextGeneration_++;
+ this.deviceIntentRevision_++;
+ this.explicitlySuspended_ = false;
if (this.resumeHandler_) {
document.removeEventListener('touchstart', this.resumeHandler_);
document.removeEventListener('mousedown', this.resumeHandler_);
diff --git a/sdk/tests/web-audio-backend.test.ts b/sdk/tests/web-audio-backend.test.ts
index 1f72e3b76..0d3088f4b 100644
--- a/sdk/tests/web-audio-backend.test.ts
+++ b/sdk/tests/web-audio-backend.test.ts
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { WebAudioBackend } from '../src/audio/WebAudioBackend';
import { setPlatform } from '../src/platform/base';
import type { PlatformAdapter } from '../src/platform/types';
@@ -107,6 +107,8 @@ describe('WebAudioBackend', () => {
backend = new WebAudioBackend();
});
+ afterEach(() => backend.dispose());
+
it('should have name "WebAudio"', () => {
expect(backend.name).toBe('WebAudio');
});
@@ -526,6 +528,76 @@ describe('WebAudioBackend', () => {
});
});
+ describe('explicit suspension versus autoplay unlock', () => {
+ for (const event of ['keydown', 'mousedown', 'touchstart']) {
+ it(`keeps the device suspended through ${event} until explicit resume`, async () => {
+ const mockCtx = (globalThis as any).__mockAudioContext;
+ mockCtx.state = 'suspended';
+ await backend.initialize(); backend.suspend();
+ document.dispatchEvent(new Event(event));
+ expect(mockCtx.resume).not.toHaveBeenCalled();
+ backend.resume(); expect(mockCtx.resume).toHaveBeenCalledTimes(1);
+ mockCtx.resume.mockClear();
+ document.dispatchEvent(new Event(event));
+ expect(mockCtx.resume).toHaveBeenCalledTimes(1);
+ mockCtx.resume.mockClear();
+ document.dispatchEvent(new Event(event));
+ expect(mockCtx.resume).not.toHaveBeenCalled();
+ });
+ }
+ it('a late resume cannot reopen the device after a newer suspend request', async () => {
+ const mockCtx = (globalThis as any).__mockAudioContext;
+ mockCtx.state = 'suspended';
+ let finish!: () => void;
+ mockCtx.resume.mockImplementation(() => new Promise<void>(resolve => { finish = () => { mockCtx.state = 'running'; resolve(); }; }));
+ mockCtx.suspend.mockImplementation(async () => { mockCtx.state = 'suspended'; });
+ await backend.initialize(); backend.resume(); backend.suspend();
+ finish(); await new Promise(resolve => setTimeout(resolve, 0));
+ expect(mockCtx.state).toBe('suspended'); expect(mockCtx.suspend).toHaveBeenCalledTimes(2);
+ });
+ it('a late suspend cannot silence the device after a newer resume request', async () => {
+ const mockCtx = (globalThis as any).__mockAudioContext;
+ let finish!: () => void;
+ mockCtx.suspend.mockImplementation(() => new Promise<void>(resolve => { finish = () => { mockCtx.state = 'suspended'; resolve(); }; }));
+ mockCtx.resume.mockImplementation(async () => { mockCtx.state = 'running'; });
+ await backend.initialize(); backend.suspend(); backend.resume();
+ finish(); await new Promise(resolve => setTimeout(resolve, 0));
+ expect(mockCtx.state).toBe('running'); expect(mockCtx.resume).toHaveBeenCalledTimes(2);
+ });
+ it('a disposed context settling late cannot issue another device transition', async () => {
+ const mockCtx = (globalThis as any).__mockAudioContext;
+ mockCtx.state = 'suspended';
+ let finish!: () => void;
+ mockCtx.resume.mockImplementation(() => new Promise<void>(resolve => { finish = () => { mockCtx.state = 'running'; resolve(); }; }));
+ await backend.initialize(); backend.resume(); backend.suspend(); backend.dispose();
+ const count = mockCtx.suspend.mock.calls.length;
+ finish(); await new Promise(resolve => setTimeout(resolve, 0));
+ expect(mockCtx.suspend).toHaveBeenCalledTimes(count);
+ });
+ it('preserves ensureResumed rejection when the browser rejects playback', async () => {
+ const mockCtx = (globalThis as any).__mockAudioContext;
+ mockCtx.state = 'suspended'; mockCtx.resume.mockRejectedValue(new Error('playback denied'));
+ await backend.initialize();
+ await expect(backend.ensureResumed()).rejects.toThrow('playback denied');
+ expect(mockCtx.resume).toHaveBeenCalledTimes(1);
+ });
+ it('does not loop when a current resume settles without unlocking the device', async () => {
+ const mockCtx = (globalThis as any).__mockAudioContext;
+ mockCtx.state = 'suspended';
+ await backend.initialize(); backend.resume();
+ await new Promise(resolve => setTimeout(resolve, 0));
+ expect(mockCtx.resume).toHaveBeenCalledTimes(1);
+ });
+ it('ensureResumed cannot bypass a fullscreen takeover suspension', async () => {
+ const mockCtx = (globalThis as any).__mockAudioContext;
+ mockCtx.state = 'suspended';
+ await backend.initialize(); backend.suspend();
+ await backend.ensureResumed(); expect(mockCtx.resume).not.toHaveBeenCalled();
+ backend.resume(); mockCtx.resume.mockClear();
+ await backend.ensureResumed(); expect(mockCtx.resume).toHaveBeenCalledTimes(1);
+ });
+ });
+
describe('dispose', () => {
it('should close AudioContext and clear state', async () => {
await backend.initialize();