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(scene): one swap, one lock, for both switch transitions

esenginef960a47ff789
diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.ts
index fbcfb06d2..47b03cea9 100644
--- a/sdk/src/scene/sceneManager.ts
+++ b/sdk/src/scene/sceneManager.ts
@@ -236,40 +236,39 @@ export class SceneManagerState {
return;
}
- const transition = options?.transition ?? 'none';
-
- if (transition === 'fade') {
- const duration = options?.duration ?? RuntimeConfig.sceneTransitionDuration;
- const color = options?.color ?? { ...RuntimeConfig.sceneTransitionColor };
- const oldScene = this.activeScene_;
+ // One lock for both paths: "one switch at a time" is a single invariant,
+ // and a faded switch must hold the same one a plain switch does.
+ this.switching_ = true;
+ try {
+ if ((options?.transition ?? 'none') !== 'fade') {
+ await this.swapTo_(name, options);
+ return;
+ }
await this.transitionController_.start(
{
- duration,
- color,
+ duration: options?.duration ?? RuntimeConfig.sceneTransitionDuration,
+ color: options?.color ?? { ...RuntimeConfig.sceneTransitionColor },
onStart: options?.onStart,
onComplete: options?.onComplete,
},
- async () => {
- if (oldScene && oldScene !== name) {
- await this.unload(oldScene, options);
- }
- await this.load(name);
- },
+ () => this.swapTo_(name, options),
);
- return;
- }
-
- this.switching_ = true;
- try {
- if (this.activeScene_ && this.activeScene_ !== name) {
- await this.unload(this.activeScene_, options);
- }
- await this.load(name);
} finally {
this.switching_ = false;
}
}
+ /** The swap itself: retire whatever is active, bring `name` up. */
+ private async swapTo_(name: string, options?: TransitionOptions): Promise<void> {
+ // Read at swap time, not at switchTo time: a fade puts half a second
+ // between the two, and the scene to retire is the one active NOW.
+ const outgoing = this.activeScene_;
+ if (outgoing && outgoing !== name) {
+ await this.unload(outgoing, options);
+ }
+ await this.load(name);
+ }
+
updateTransition(dt: number): void {
this.transitionController_.update(dt);
}
diff --git a/sdk/tests/scene-switch-parity.test.ts b/sdk/tests/scene-switch-parity.test.ts
new file mode 100644
index 000000000..1776b9c0b
--- /dev/null
+++ b/sdk/tests/scene-switch-parity.test.ts
@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A faded switch and a plain one differ by the overlay, nothing else.
+ *
+ * They were two copies of the same swap holding two different locks — the faded
+ * path only `isTransitioning`, the plain one only `switching_` — so "one switch
+ * at a time" was two invariants that happened to agree. Every claim below is
+ * made of both modes from one table; a third transition means a third row.
+ */
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+
+vi.mock('../src/scene/scene', () => ({
+ loadSceneWithAssets: vi.fn().mockResolvedValue(new Map()),
+}));
+vi.mock('../src/render/customDraw', () => ({
+ registerDrawCallback: vi.fn(), unregisterDrawCallback: vi.fn(),
+}));
+vi.mock('../src/postprocess', () => ({
+ PostProcess: { bind: vi.fn(), unbind: vi.fn() }, PostProcessStack: vi.fn(),
+}));
+vi.mock('../src/render/material', () => ({
+ Material: { release: vi.fn(), createShader: vi.fn() }, defineResource: vi.fn(),
+}));
+vi.mock('../src/asset', () => ({
+ Assets: { releaseTexture: vi.fn(), releaseTyped: vi.fn(), releaseAll: vi.fn() },
+ discoverSceneAssets: vi.fn().mockReturnValue({ byType: new Map() }),
+ preloadSceneAssets: vi.fn().mockResolvedValue({ missing: [] }),
+}));
+vi.mock('../src/asset/discoverAssets', () => ({
+ discoverSceneAssets: vi.fn(() => ({ byType: new Map() })),
+ getAssetPathsByType: vi.fn(() => new Set()),
+}));
+
+import { SceneManagerState } from '../src/scene/sceneManager';
+import type { TransitionOptions } from '../src/scene/sceneManager';
+
+const SCENE_DATA = { version: '1.0', name: 'T', entities: [] };
+
+function createMockApp() {
+ const live = new Set<number>();
+ let next = 1;
+ const world = {
+ spawn: () => { const e = next++; live.add(e); return e; },
+ despawn: (e: number) => { live.delete(e); },
+ valid: (e: number) => live.has(e),
+ has: () => false,
+ get: () => ({ scene: '', persistent: false }),
+ insert: () => {}, set: () => {}, remove: () => {},
+ };
+ return {
+ world,
+ live,
+ hasResource: () => false,
+ getResource: () => undefined,
+ addSystemToSchedule: () => {},
+ removeSystem: () => {},
+ };
+}
+
+/** Both public transitions, and the pumping a fade needs to get through. */
+const MODES: Array<{ name: string; options: TransitionOptions }> = [
+ { name: 'plain', options: { transition: 'none' } },
+ { name: 'fade', options: { transition: 'fade', duration: 0.2 } },
+];
+
+describe.each(MODES)('switchTo ($name)', (mode) => {
+ let app: ReturnType<typeof createMockApp>;
+ let manager: SceneManagerState;
+
+ beforeEach(() => {
+ app = createMockApp();
+ manager = new SceneManagerState(app as never);
+ for (const name of ['alpha', 'beta']) {
+ manager.register({ name, data: SCENE_DATA, setup: (ctx) => { ctx.spawn(); } });
+ }
+ });
+
+ /** Drive the switch to completion — a fade only advances on updateTransition. */
+ async function switchAndSettle(to: string): Promise<void> {
+ const done = manager.switchTo(to, mode.options);
+ for (let i = 0; i < 60 && manager.isTransitioning(); i++) {
+ manager.updateTransition(0.05);
+ await Promise.resolve();
+ }
+ await done;
+ // The fade resolves on fade-IN completion, one more pump past the swap.
+ for (let i = 0; i < 20 && manager.isTransitioning(); i++) {
+ manager.updateTransition(0.05);
+ await Promise.resolve();
+ }
+ }
+
+ it('brings the target up as the active scene', async () => {
+ await switchAndSettle('alpha');
+ expect(manager.isActive('alpha'), 'the target never became active').toBe(true);
+ expect(manager.isLoaded('alpha')).toBe(true);
+ });
+
+ it('retires the scene that was active', async () => {
+ await switchAndSettle('alpha');
+ await switchAndSettle('beta');
+ expect(manager.isLoaded('beta')).toBe(true);
+ expect(manager.isLoaded('alpha'), 'the outgoing scene was left loaded').toBe(false);
+ expect(app.live.size, 'the outgoing scene left entities behind').toBe(1);
+ });
+
+ it('ignores a second switch while one is in progress', async () => {
+ const first = manager.switchTo('alpha', mode.options);
+ await manager.switchTo('beta', mode.options); // must be refused
+ for (let i = 0; i < 60 && manager.isTransitioning(); i++) {
+ manager.updateTransition(0.05);
+ await Promise.resolve();
+ }
+ await first;
+ expect(manager.isLoaded('beta'), 'a concurrent switch was allowed through').toBe(false);
+ });
+
+ it('switching to the scene already active leaves it alone', async () => {
+ await switchAndSettle('alpha');
+ const before = app.live.size;
+ await switchAndSettle('alpha');
+ expect(manager.isActive('alpha')).toBe(true);
+ expect(app.live.size, 'the active scene was torn down and rebuilt').toBe(before);
+ });
+});