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.

49.4 KB
Raw Blame
// 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');
        });
    });
});