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
import { describe, it, expect, 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/render/draw', () => ({
Draw: {
setLayer: vi.fn(),
setDepth: vi.fn(),
rect: vi.fn(),
},
}));
vi.mock('../src/ecs/resource', () => ({
defineResource: vi.fn((_init: unknown, name?: string) => ({
_id: Symbol(name ?? 'Resource'),
_name: name ?? 'Resource',
_default: _init,
})),
}));
// Renderables carry the field that gates them, because sleep/wake writes THAT
// field — TilemapLayer's is `visible`, not `enabled`. Everything is built inside
// the factory: vi.mock is hoisted above this file's own top-level statements.
vi.mock('../src/ecs/component', () => {
const def = (name: string, renderableField = 'enabled') => ({
_id: Symbol(name), _name: name, _builtin: true, renderableField,
});
const renderables = [
def('Sprite'), def('SpineAnimation'), def('BitmapText'),
def('ShapeRenderer'), def('ParticleEmitter'), def('TilemapLayer', 'visible'),
];
return {
SceneOwner: Symbol('SceneOwner'),
Parent: Symbol('Parent'),
Disabled: { _id: Symbol('Disabled'), _name: 'Disabled', _builtin: false, _default: {} },
...Object.fromEntries(renderables.map((d) => [d._name, d])),
renderableComponents: () => renderables,
defineBuiltin: (name: string, defaults: unknown) => Symbol(name),
defineTag: (name: string) => ({ _id: Symbol(name), _name: name, _builtin: false, _default: {} }),
};
});
vi.mock('../src/asset/AssetPlugin', () => ({
Assets: Symbol('Assets'),
}));
vi.mock('../src/defaults', () => ({
RuntimeConfig: {
sceneTransitionDuration: 0.5,
sceneTransitionColor: { r: 0, g: 0, b: 0, a: 1 },
},
}));
import { SceneManagerState, SceneLoadCancelled, wrapSceneSystem, type SceneContext } from '../src/scene/sceneManager';
import { SceneOwner, Sprite, SpineAnimation, BitmapText, TilemapLayer } from '../src/ecs/component';
import { loadSceneWithAssets } from '../src/scene/scene';
import { registerDrawCallback, unregisterDrawCallback } from '../src/render/customDraw';
import { PostProcess } from '../src/postprocess';
import { Material } from '../src/render/material';
function createMockApp() {
const entities = new Map<number, Map<symbol, any>>();
const despawnListeners = new Set<(entity: number) => void>();
let nextEntity = 1;
const resources = new Map<any, any>();
// PostProcess is now a per-App resource; register the mock so sceneManager's
// app.getResource(PostProcess).bind/unbind hits the spies.
resources.set(PostProcess, PostProcess);
const world = {
spawn: vi.fn(() => {
const e = nextEntity++;
entities.set(e, new Map());
return e;
}),
despawn: vi.fn((e: number) => {
for (const listener of [...despawnListeners]) listener(e);
return entities.delete(e);
}),
onDespawn: vi.fn((listener: (entity: number) => void) => {
despawnListeners.add(listener);
return () => { despawnListeners.delete(listener); };
}),
valid: vi.fn((e: number) => entities.has(e)),
has: vi.fn((e: number, comp: symbol) => entities.get(e)?.has(comp) ?? false),
get: vi.fn((e: number, comp: symbol) => entities.get(e)?.get(comp)),
tryGet: vi.fn((e: number, comp: symbol) => entities.get(e)?.get(comp) ?? null),
insert: vi.fn((e: number, comp: symbol, data: any) => {
if (!entities.has(e)) entities.set(e, new Map());
entities.get(e)!.set(comp, data);
}),
set: vi.fn((e: number, comp: symbol, data: any) => {
if (!entities.has(e)) entities.set(e, new Map());
entities.get(e)!.set(comp, data);
}),
remove: vi.fn((e: number, comp: symbol) => {
entities.get(e)?.delete(comp);
}),
};
return {
world,
hasResource: vi.fn((key: any) => resources.has(key)),
getResource: vi.fn((key: any) => resources.get(key)),
addSystemToSchedule: vi.fn(),
_entities: entities,
_resources: resources,
_despawnListeners: despawnListeners,
};
}
function makeSceneData() {
return {
version: '1.0',
name: 'TestScene',
entities: [],
};
}
describe('SceneManager', () => {
let app: ReturnType<typeof createMockApp>;
let manager: SceneManagerState;
beforeEach(() => {
vi.clearAllMocks();
app = createMockApp();
manager = new SceneManagerState(app as any);
});
it('forgets entities destroyed through the World and reattaches tracking after reset', async () => {
for (let round = 0; round < 2; round++) {
manager.register({ name: 'tracked' });
const context = await manager.load('tracked');
for (let i = 0; i < 100; i++) {
const entity = context.spawn();
context.adopt(entity);
app.world.despawn(entity);
expect(context.entities.size).toBe(0);
}
expect(app._despawnListeners.size).toBe(1);
await manager.unload('tracked');
manager.reset();
expect(app._despawnListeners.size).toBe(0);
}
});
it.each([[false, false], [true, false], [false, true], [true, true]])(
'transfers ownership and render state, source asleep=%j target asleep=%j', async (sourceAsleep, targetAsleep) => {
manager.register({ name: 'source' }); manager.register({ name: 'target' });
const source = await manager.load('source'), entity = source.spawn();
app.world.insert(entity, Sprite as any, { enabled: true });
const target = await manager.load('target');
if (sourceAsleep) manager.sleep('source');
if (targetAsleep) manager.sleep('target');
target.adopt(entity);
target.adopt(entity);
expect(source.entities.has(entity)).toBe(false);
expect(target.entities.has(entity)).toBe(true);
expect(app.world.get(entity, Sprite as any).enabled).toBe(!targetAsleep);
await manager.unload('source');
expect(app.world.valid(entity)).toBe(true);
if (targetAsleep) manager.wake('target');
expect(app.world.get(entity, Sprite as any).enabled).toBe(true);
await manager.unload('target');
expect(app.world.valid(entity)).toBe(false);
});
it.each(['unload', 'reload', 'reset'])(
'rejects mutations from a stale context after %s', async mode => {
manager.register({ name: 'source' }); manager.register({ name: 'target' });
const stale = await manager.load('source'), target = await manager.load('target');
const entity = target.spawn();
if (mode === 'reset') manager.reset();
else {
await manager.unload('source');
if (mode === 'reload') await manager.load('source');
}
const spawnCalls = app.world.spawn.mock.calls.length;
expect(() => stale.adopt(entity)).toThrow(SceneLoadCancelled);
expect(() => stale.spawn()).toThrow(SceneLoadCancelled);
expect(app.world.spawn.mock.calls.length).toBe(spawnCalls);
expect(() => stale.despawn(entity)).toThrow(SceneLoadCancelled);
expect(() => stale.setPersistent(entity, true)).toThrow(SceneLoadCancelled);
expect(() => stale.registerDrawCallback('late', () => {})).toThrow(SceneLoadCancelled);
expect(() => stale.bindPostProcess(entity, {} as any)).toThrow(SceneLoadCancelled);
expect(() => stale.unbindPostProcess(entity)).toThrow(SceneLoadCancelled);
expect(() => stale.trackAssets(new Map())).toThrow(SceneLoadCancelled);
const scope = { releaseAll: vi.fn() };
expect(() => stale.trackAssetScope(scope as any)).toThrow(SceneLoadCancelled);
expect(scope.releaseAll).toHaveBeenCalledTimes(1);
if (mode !== 'reset') {
expect(target.entities.has(entity)).toBe(true);
expect(app.world.valid(entity)).toBe(true);
await manager.unload('target');
expect(app.world.valid(entity)).toBe(false);
}
});
// =========================================================================
// Registration & initial scene
// =========================================================================
describe('registration & initial scene', () => {
it('register stores config by name', () => {
manager.register({ name: 'main' });
expect(manager.getScene('main')).toBeNull();
// Does not throw when loading a registered scene
expect(() => manager.register({ name: 'main' })).not.toThrow();
});
it('setInitial / getInitial', () => {
expect(manager.getInitial()).toBeNull();
manager.setInitial('main');
expect(manager.getInitial()).toBe('main');
});
it('load unregistered scene throws "not registered"', async () => {
await expect(manager.load('unknown')).rejects.toThrow('not registered');
});
it('loadAdditive unregistered scene throws "not registered"', async () => {
await expect(manager.loadAdditive('unknown')).rejects.toThrow('not registered');
});
});
// =========================================================================
// Scene loading
// =========================================================================
describe('scene loading', () => {
it('load() with inline data sets status=running and activeScene', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
expect(ctx.name).toBe('level1');
expect(manager.getActive()).toBe('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
});
it('load() with already-loaded scene returns existing context', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx1 = await manager.load('level1');
const ctx2 = await manager.load('level1');
expect(ctx2).toBe(ctx1);
});
it('load() adds entities via SceneOwner when loadSceneWithAssets returns entities', async () => {
const entityMap = new Map<number, number>();
entityMap.set(100, 1);
entityMap.set(200, 2);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
// Pre-create the entities in the mock world so valid() returns true
app._entities.set(1, new Map());
app._entities.set(2, new Map());
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
expect(ctx.entities.size).toBe(2);
expect(app.world.insert).toHaveBeenCalledWith(
1, SceneOwner, { scene: 'level1', persistent: false }
);
});
it('loadAdditive() adds to additive scenes', async () => {
manager.register({ name: 'ui', data: makeSceneData() });
manager.register({ name: 'main', data: makeSceneData() });
await manager.load('main');
await manager.loadAdditive('ui');
expect(manager.isLoaded('ui')).toBe(true);
expect(manager.getLoaded()).toContain('ui');
});
it('loadAdditive() for already-loaded scene reuses instance', async () => {
manager.register({ name: 'ui', data: makeSceneData() });
const ctx1 = await manager.loadAdditive('ui');
const ctx2 = await manager.loadAdditive('ui');
expect(ctx2).toBe(ctx1);
});
it('duplicate load() while loading returns same promise', async () => {
let resolveLoad!: (val: Map<number, number>) => void;
vi.mocked(loadSceneWithAssets).mockReturnValueOnce(
new Promise(r => { resolveLoad = r; })
);
manager.register({ name: 'level1', data: makeSceneData() });
const p1 = manager.load('level1');
const p2 = manager.load('level1');
resolveLoad(new Map());
const [ctx1, ctx2] = await Promise.all([p1, p2]);
expect(ctx1).toBe(ctx2);
});
it('load() calls setup callback', async () => {
const setup = vi.fn();
manager.register({ name: 'level1', data: makeSceneData(), setup });
await manager.load('level1');
expect(setup).toHaveBeenCalledTimes(1);
});
});
// =========================================================================
// Scene unloading
// =========================================================================
describe('scene unloading', () => {
it('unload() despawns entities', async () => {
const entityMap = new Map([[100, 1]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
app._entities.set(1, new Map());
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
await manager.unload('level1');
expect(app.world.despawn).toHaveBeenCalledWith(1);
});
it('unload() keeps persistent entities by default', async () => {
const entityMap = new Map([[100, 1], [200, 2]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
app._entities.set(1, new Map());
app._entities.set(2, new Map());
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
// Mark entity 1 as persistent
const ownerData1 = app._entities.get(1)!.get(SceneOwner);
ownerData1.persistent = true;
app._entities.get(1)!.set(SceneOwner, ownerData1);
await manager.unload('level1');
// Entity 1 should NOT be despawned (persistent)
expect(app.world.despawn).not.toHaveBeenCalledWith(1);
// Entity 2 should be despawned (not persistent)
expect(app.world.despawn).toHaveBeenCalledWith(2);
// The surviving persistent entity is promoted to global (scene ''),
// so scene-gated consumers (e.g. the camera render filter) keep it
// active instead of orphaning it to the now-unloaded scene.
const owner1 = app._entities.get(1)!.get(SceneOwner);
expect(owner1.persistent).toBe(true);
expect(owner1.scene).toBe('');
});
it('unload() with keepPersistent=false despawns all entities', async () => {
const entityMap = new Map([[100, 1]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
app._entities.set(1, new Map());
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
// Mark as persistent
const ownerData = app._entities.get(1)!.get(SceneOwner);
ownerData.persistent = true;
app._entities.get(1)!.set(SceneOwner, ownerData);
await manager.unload('level1', { keepPersistent: false });
expect(app.world.despawn).toHaveBeenCalledWith(1);
});
it('unload() cleans up draw callbacks', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
ctx.registerDrawCallback('myDraw', () => {});
await manager.unload('level1');
expect(unregisterDrawCallback).toHaveBeenCalledWith('myDraw');
});
it('unload() unbinds postprocess stacks', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const mockStack = { setAllPassesEnabled: vi.fn(), isDestroyed: false } as any;
ctx.bindPostProcess(1 as any, mockStack);
await manager.unload('level1');
expect(PostProcess.unbind).toHaveBeenCalledWith(1);
});
it('unload() releases what the scene acquired, by receipt', async () => {
let released = 0;
vi.mocked(loadSceneWithAssets).mockImplementationOnce(
async (_world, _data, options) => {
// What the real preload hands back: a receipt per successful
// acquire, materials included. Releasing by handle instead
// would free whatever that path resolves to at unload.
options?.collectAssets?.scope?.add({
key: 'material:hero.esmat', generation: 1, value: null,
release: () => { released++; },
} as never);
return new Map();
}
);
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
await manager.unload('level1');
expect(released).toBe(1);
expect(Material.release).not.toHaveBeenCalled();
});
it('unload() clears activeScene if unloaded scene was active', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
expect(manager.getActive()).toBe('level1');
await manager.unload('level1');
expect(manager.getActive()).toBeNull();
});
it('unload() calls cleanup callback', async () => {
const cleanup = vi.fn();
manager.register({ name: 'level1', data: makeSceneData(), cleanup });
await manager.load('level1');
await manager.unload('level1');
expect(cleanup).toHaveBeenCalledTimes(1);
});
it('unload() non-existent scene is a no-op', async () => {
await expect(manager.unload('nonexistent')).resolves.toBeUndefined();
});
});
// =========================================================================
// Scene switching
// =========================================================================
describe('scene switching', () => {
it('switchTo() unloads old scene and loads new scene', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
expect(manager.getActive()).toBe('level1');
await manager.switchTo('level2');
expect(manager.getActive()).toBe('level2');
expect(manager.isLoaded('level1')).toBe(false);
});
it('switchTo() during transition is ignored', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
manager.register({ name: 'level3', data: makeSceneData() });
await manager.load('level1');
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
// Start a switch that won't resolve immediately
let resolveLoad!: (val: Map<number, number>) => void;
vi.mocked(loadSceneWithAssets).mockReturnValueOnce(
new Promise(r => { resolveLoad = r; })
);
const p1 = manager.switchTo('level2');
// This should be ignored
await manager.switchTo('level3');
expect(warnSpy).toHaveBeenCalled();
resolveLoad(new Map());
await p1;
expect(manager.getActive()).toBe('level2');
warnSpy.mockRestore();
});
it('switchTo() with transition=none does direct switch', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
await manager.switchTo('level2', { transition: 'none' });
expect(manager.getActive()).toBe('level2');
expect(registerDrawCallback).not.toHaveBeenCalledWith(
'__scene_transition_overlay__',
expect.any(Function)
);
});
it('switching_ is reset even if load fails', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
// Attempt to switch to an unregistered scene (will throw)
await expect(manager.switchTo('nonexistent')).rejects.toThrow('not registered');
// switching_ should be reset, so another switch should work
manager.register({ name: 'level2', data: makeSceneData() });
await manager.switchTo('level2');
expect(manager.getActive()).toBe('level2');
});
it('switchTo() to same scene as active does not unload', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
await manager.switchTo('level1');
expect(manager.getActive()).toBe('level1');
expect(manager.isLoaded('level1')).toBe(true);
});
});
// =========================================================================
// Pause / Resume
// =========================================================================
describe('pause / resume', () => {
it('pause() sets status=paused and adds to pausedScenes', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.pause('level1');
expect(manager.getSceneStatus('level1')).toBe('paused');
expect(manager.isPaused('level1')).toBe(true);
});
it('pause() on non-running scene is no-op', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.pause('level1');
expect(manager.isPaused('level1')).toBe(true);
// Pause again should be no-op (already paused, not 'running')
manager.pause('level1');
expect(manager.isPaused('level1')).toBe(true);
});
it('pause() on non-loaded scene is no-op', () => {
manager.pause('nonexistent');
expect(manager.isPaused('nonexistent')).toBe(false);
});
it('resume() sets status=running and removes from pausedScenes', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.pause('level1');
manager.resume('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
expect(manager.isPaused('level1')).toBe(false);
});
it('resume() on non-paused scene is no-op', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
// Already running, resume should be no-op
manager.resume('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
});
it('pause() disables postprocess passes via stack', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const mockStack = { setAllPassesEnabled: vi.fn(), isDestroyed: false } as any;
ctx.bindPostProcess(1 as any, mockStack);
manager.pause('level1');
expect(mockStack.setAllPassesEnabled).toHaveBeenCalledWith(false);
});
it('resume() re-enables postprocess passes via stack', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const mockStack = { setAllPassesEnabled: vi.fn(), isDestroyed: false } as any;
ctx.bindPostProcess(1 as any, mockStack);
manager.pause('level1');
mockStack.setAllPassesEnabled.mockClear();
manager.resume('level1');
expect(mockStack.setAllPassesEnabled).toHaveBeenCalledWith(true);
});
});
// =========================================================================
// Sleep / Wake
// =========================================================================
describe('sleep / wake', () => {
function setupEntityWithComponents(entityId: number) {
const entityComponents = new Map<symbol, any>();
entityComponents.set(Sprite, { color: { r: 1, g: 1, b: 1, a: 0.8 }, enabled: true });
entityComponents.set(SpineAnimation, { color: { r: 1, g: 1, b: 1, a: 0.6 }, enabled: true });
entityComponents.set(BitmapText, { color: { r: 1, g: 1, b: 1, a: 0.9 }, enabled: true });
app._entities.set(entityId, entityComponents);
}
it('sleep() sets status=sleeping and disables renderable components', async () => {
const entityMap = new Map([[100, 1]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
setupEntityWithComponents(1);
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.sleep('level1');
expect(manager.getSceneStatus('level1')).toBe('sleeping');
expect(manager.isSleeping('level1')).toBe(true);
const sprite = app._entities.get(1)!.get(Sprite);
expect(sprite.enabled).toBe(false);
});
it('sleep() only on running scenes', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.pause('level1');
manager.sleep('level1');
// Should still be paused, not sleeping
expect(manager.getSceneStatus('level1')).toBe('paused');
expect(manager.isSleeping('level1')).toBe(false);
});
it('sleep() on non-loaded scene is no-op', () => {
manager.sleep('nonexistent');
expect(manager.isSleeping('nonexistent')).toBe(false);
});
it('wake() restores enabled state from saved values', async () => {
const entityMap = new Map([[100, 1]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
setupEntityWithComponents(1);
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.sleep('level1');
manager.wake('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
expect(manager.isSleeping('level1')).toBe(false);
const sprite = app._entities.get(1)!.get(Sprite);
expect(sprite.enabled).toBe(true);
const spine = app._entities.get(1)!.get(SpineAnimation);
expect(spine.enabled).toBe(true);
const bt = app._entities.get(1)!.get(BitmapText);
expect(bt.enabled).toBe(true);
});
// A renderable whose gating flag is not called `enabled`. Sleep wrote a
// fixed `enabled` key, so a tilemap layer kept drawing in a slept scene —
// and a stray `enabled: false` was left on data that has no such field.
it('sleeps and wakes a renderable through its own flag name', async () => {
const entityMap = new Map([[100, 1]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
const layer = { visible: true, opacity: 1 };
app._entities.set(1, new Map([[TilemapLayer, layer]]));
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.sleep('level1');
expect(layer.visible).toBe(false);
expect('enabled' in layer).toBe(false);
manager.wake('level1');
expect(layer.visible).toBe(true);
});
it('wake() only on sleeping scenes', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
// Running scene, wake should be no-op
manager.wake('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
});
it('wake() disables postprocess passes on sleep and re-enables on wake', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const mockStack = { setAllPassesEnabled: vi.fn(), isDestroyed: false } as any;
ctx.bindPostProcess(1 as any, mockStack);
manager.sleep('level1');
expect(mockStack.setAllPassesEnabled).toHaveBeenCalledWith(false);
mockStack.setAllPassesEnabled.mockClear();
manager.wake('level1');
expect(mockStack.setAllPassesEnabled).toHaveBeenCalledWith(true);
});
it('load() on a sleeping scene wakes it (restores enabled, clears sleeping)', async () => {
const entityMap = new Map([[100, 1]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
setupEntityWithComponents(1);
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.sleep('level1');
expect(manager.isSleeping('level1')).toBe(true);
// Re-loading a slept scene must run the full wake restore, not a bare
// status flip that would strand its entities Disabled forever.
await manager.load('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
expect(manager.isSleeping('level1')).toBe(false);
expect(app._entities.get(1)!.get(Sprite).enabled).toBe(true);
});
it('load() on a paused scene resumes it (clears paused)', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.pause('level1');
expect(manager.isPaused('level1')).toBe(true);
await manager.load('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
expect(manager.isPaused('level1')).toBe(false);
});
});
describe('load/unload race (load token)', () => {
it('a load cancelled by a concurrent unload rejects and orphans nothing', async () => {
let resolveAssets!: () => void;
vi.mocked(loadSceneWithAssets).mockImplementationOnce(async () => {
await new Promise<void>((res) => { resolveAssets = res; });
app._entities.set(1, new Map()); // the real loader spawns this into the world
return new Map([[100, 1]]);
});
manager.register({ name: 'level1', data: makeSceneData() });
const loadP = manager.load('level1');
await new Promise((r) => setTimeout(r, 0)); // park at the pending asset load
await manager.unload('level1'); // race: unload while assets are in flight
resolveAssets(); // now the assets finish
await expect(loadP).rejects.toThrow(SceneLoadCancelled);
expect(manager.getActive()).not.toBe('level1');
expect(manager.getSceneStatus('level1')).toBeNull();
// The entity spawned after the unload is despawned, not left orphaned.
expect(app.world.despawn).toHaveBeenCalledWith(1);
expect(app._entities.has(1)).toBe(false);
});
});
// =========================================================================
// Query methods
// =========================================================================
describe('query methods', () => {
it('getActive() returns active scene name', async () => {
expect(manager.getActive()).toBeNull();
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
expect(manager.getActive()).toBe('level1');
});
it('getActiveScenes() returns all running scenes', async () => {
manager.register({ name: 'main', data: makeSceneData() });
manager.register({ name: 'ui', data: makeSceneData() });
await manager.load('main');
await manager.loadAdditive('ui');
const active = manager.getActiveScenes();
expect(active).toContain('main');
expect(active).toContain('ui');
expect(active).toHaveLength(2);
});
it('getActiveScenes() excludes paused scenes', async () => {
manager.register({ name: 'main', data: makeSceneData() });
manager.register({ name: 'ui', data: makeSceneData() });
await manager.load('main');
await manager.loadAdditive('ui');
manager.pause('ui');
const active = manager.getActiveScenes();
expect(active).toContain('main');
expect(active).not.toContain('ui');
});
it('getLoaded() returns all loaded scene names', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
await manager.loadAdditive('level2');
const loaded = manager.getLoaded();
expect(loaded).toContain('level1');
expect(loaded).toContain('level2');
});
it('getLoadOrder() returns load order', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
await manager.loadAdditive('level2');
expect(manager.getLoadOrder()).toEqual(['level1', 'level2']);
});
it('bringToTop() moves scene to end of loadOrder', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
manager.register({ name: 'level3', data: makeSceneData() });
await manager.load('level1');
await manager.loadAdditive('level2');
await manager.loadAdditive('level3');
manager.bringToTop('level1');
expect(manager.getLoadOrder()).toEqual(['level2', 'level3', 'level1']);
});
it('bringToTop() on non-loaded scene is no-op', () => {
manager.bringToTop('nonexistent');
expect(manager.getLoadOrder()).toEqual([]);
});
it('getScene() returns context or null', async () => {
expect(manager.getScene('nonexistent')).toBeNull();
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
expect(manager.getScene('level1')).not.toBeNull();
});
it('getSceneStatus() returns status or null', async () => {
expect(manager.getSceneStatus('nonexistent')).toBeNull();
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
expect(manager.getSceneStatus('level1')).toBe('running');
});
it('isActive() returns correct value', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
expect(manager.isActive('level1')).toBe(false);
await manager.load('level1');
expect(manager.isActive('level1')).toBe(true);
});
it('isLoaded() returns correct value', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
expect(manager.isLoaded('level1')).toBe(false);
await manager.load('level1');
expect(manager.isLoaded('level1')).toBe(true);
});
});
// =========================================================================
// wrapSceneSystem
// =========================================================================
describe('wrapSceneSystem', () => {
it('wrapped system only runs when scene status is running', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
const innerFn = vi.fn();
const system = {
_id: Symbol('test'),
_name: 'testSystem',
_params: [],
_fn: innerFn,
};
// We need to set up getResource to return the manager
const { SceneManager } = await import('../src/scene/sceneManager');
app.getResource.mockImplementation((key: any) => {
if (key === SceneManager || key?._name === 'SceneManager') return manager;
return undefined;
});
const wrapped = wrapSceneSystem(app as any, 'level1', system as any);
(wrapped._fn as Function)();
expect(innerFn).toHaveBeenCalledTimes(1);
});
it('wrapped system is skipped when scene is paused', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.pause('level1');
const innerFn = vi.fn();
const system = {
_id: Symbol('test'),
_name: 'testSystem',
_params: [],
_fn: innerFn,
};
const { SceneManager } = await import('../src/scene/sceneManager');
app.getResource.mockImplementation((key: any) => {
if (key === SceneManager || key?._name === 'SceneManager') return manager;
return undefined;
});
const wrapped = wrapSceneSystem(app as any, 'level1', system as any);
(wrapped._fn as Function)();
expect(innerFn).not.toHaveBeenCalled();
});
it('wrapped system name includes scene name', () => {
const system = {
_id: Symbol('test'),
_name: 'movement',
_params: [],
_fn: vi.fn(),
};
const wrapped = wrapSceneSystem(app as any, 'level1', system as any);
expect(wrapped._name).toBe('movement@level1');
});
});
// =========================================================================
// Transition (fade)
// =========================================================================
describe('transition (fade)', () => {
it('isTransitioning() returns false initially', () => {
expect(manager.isTransitioning()).toBe(false);
});
it('switchTo with fade starts transition', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
const onStart = vi.fn();
manager.switchTo('level2', { transition: 'fade', duration: 1.0, onStart });
// Allow microtask to run
await Promise.resolve();
expect(manager.isTransitioning()).toBe(true);
expect(onStart).toHaveBeenCalled();
expect(registerDrawCallback).toHaveBeenCalledWith(
'__scene_transition_overlay__',
expect.any(Function)
);
});
it('updateTransition with dt progresses elapsed', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
manager.switchTo('level2', { transition: 'fade', duration: 1.0 });
await Promise.resolve();
expect(manager.isTransitioning()).toBe(true);
// Progress but not past half duration
manager.updateTransition(0.2);
expect(manager.isTransitioning()).toBe(true);
});
it('fade-out completes at half duration and switches to fade-in', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
manager.switchTo('level2', { transition: 'fade', duration: 1.0 });
await Promise.resolve();
// Advance past half (0.5)
manager.updateTransition(0.6);
// Allow async scene switch to complete
await new Promise(r => setTimeout(r, 10));
// Should still be transitioning (in fade-in phase now)
// If the fade-in hasn't completed, it should still be transitioning
// The elapsed was reset to 0 for fade-in, then 0 < 0.5 so still transitioning
expect(manager.isTransitioning()).toBe(true);
});
it('fade-in completes and resolves transition', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
const onComplete = vi.fn();
const promise = manager.switchTo('level2', {
transition: 'fade',
duration: 1.0,
onComplete,
});
await Promise.resolve();
// Complete fade-out (half = 0.5) → enters loading phase.
manager.updateTransition(0.6);
await new Promise(r => setTimeout(r, 10));
// Flush the loading-phase outcome; sees success → flips to fade-in.
manager.updateTransition(0.0);
// Complete fade-in (half = 0.5).
manager.updateTransition(0.6);
expect(manager.isTransitioning()).toBe(false);
expect(onComplete).toHaveBeenCalled();
expect(unregisterDrawCallback).toHaveBeenCalledWith('__scene_transition_overlay__');
await promise;
});
it('switchTo with fade is ignored during active transition', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
manager.register({ name: 'level3', data: makeSceneData() });
await manager.load('level1');
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
manager.switchTo('level2', { transition: 'fade', duration: 1.0 });
await Promise.resolve();
// Second switch should be ignored
await manager.switchTo('level3');
expect(warnSpy).toHaveBeenCalled();
warnSpy.mockRestore();
});
});
// =========================================================================
// SceneContext methods
// =========================================================================
describe('SceneContext', () => {
it('spawn() creates entity with SceneOwner', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
// Annotated: this is the shape `load` promises, so a member that
// moves fails here and not at whatever calls it next.
const ctx: SceneContext = await manager.load('level1');
const entity = ctx.spawn();
expect(app.world.spawn).toHaveBeenCalled();
expect(ctx.entities.has(entity)).toBe(true);
expect(app.world.insert).toHaveBeenCalledWith(
entity, SceneOwner, { scene: 'level1', persistent: false }
);
});
it('despawn() removes entity from context', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const entity = ctx.spawn();
ctx.despawn(entity);
expect(app.world.despawn).toHaveBeenCalledWith(entity);
expect(ctx.entities.has(entity)).toBe(false);
});
it('setPersistent() updates SceneOwner data', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const entity = ctx.spawn();
ctx.setPersistent(entity, true);
const lastInsertCall = app.world.insert.mock.calls[
app.world.insert.mock.calls.length - 1
];
expect(lastInsertCall[2].persistent).toBe(true);
});
it('unbindPostProcess() removes binding from instance tracking', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const mockStack = { setAllPassesEnabled: vi.fn(), isDestroyed: false } as any;
ctx.bindPostProcess(1 as any, mockStack);
ctx.unbindPostProcess(1 as any);
expect(PostProcess.unbind).toHaveBeenCalledWith(1);
});
});
// =========================================================================
// reset()
// =========================================================================
describe('reset()', () => {
it('clears all loaded scenes and configs', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
await manager.loadAdditive('level2');
manager.reset();
expect(manager.getActive()).toBeNull();
expect(manager.getLoaded()).toEqual([]);
expect(manager.getLoadOrder()).toEqual([]);
expect(manager.getScene('level1')).toBeNull();
expect(manager.getScene('level2')).toBeNull();
});
it('clears initial scene', async () => {
manager.setInitial('level1');
manager.reset();
expect(manager.getInitial()).toBeNull();
});
it('clears paused and sleeping sets', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
await manager.loadAdditive('level2');
manager.pause('level1');
manager.sleep('level2');
manager.reset();
expect(manager.isPaused('level1')).toBe(false);
expect(manager.isSleeping('level2')).toBe(false);
});
it('unregisters draw callbacks from loaded scenes', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
ctx.registerDrawCallback('myDraw', () => {});
manager.reset();
expect(unregisterDrawCallback).toHaveBeenCalledWith('myDraw');
});
it('unbinds post process from loaded scenes', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
const mockStack = { setAllPassesEnabled: vi.fn() };
ctx.bindPostProcess(42 as any, mockStack as any);
manager.reset();
expect(PostProcess.unbind).toHaveBeenCalledWith(42);
});
it('does not despawn entities', async () => {
const entityMap = new Map([[100, 1]]);
vi.mocked(loadSceneWithAssets).mockResolvedValueOnce(entityMap);
app._entities.set(1, new Map());
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.reset();
expect(app.world.despawn).not.toHaveBeenCalled();
});
it('clears transition state', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
manager.register({ name: 'level2', data: makeSceneData() });
await manager.load('level1');
manager.switchTo('level2', { transition: 'fade', duration: 1.0 });
await Promise.resolve();
expect(manager.isTransitioning()).toBe(true);
manager.reset();
expect(manager.isTransitioning()).toBe(false);
expect(unregisterDrawCallback).toHaveBeenCalledWith('__scene_transition_overlay__');
});
it('allows re-registration and loading after reset', async () => {
manager.register({ name: 'level1', data: makeSceneData() });
await manager.load('level1');
manager.reset();
manager.register({ name: 'level1', data: makeSceneData() });
const ctx = await manager.load('level1');
expect(ctx.name).toBe('level1');
expect(manager.getActive()).toBe('level1');
});
});
});