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 { beforeAll, describe, expect, it } from 'vitest';
import { World } from '../src/ecs/world';
import { Children, Name, Transform } from '../src/ecs/component';
import type { ChildrenData, NameData } from '../src/ecs/component';
import { isEntityActive } from '../src/ecs/entityUtils';
import type { PrefabData } from '../src/prefab';
import type { Assets } from '../src/asset/Assets';
import type { Entity } from '../src/types';
import { UIPages } from '../src/ui/pages/ui-pages';
import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
import type { CppRegistry, ESEngineModule } from '../src/wasm';
const page = (name: string, kids: string[]): PrefabData => ({
version: '2', name, rootEntityId: 'root',
entities: [
{ prefabEntityId: 'root', name, parent: null, children: kids.map((k) => 'e-' + k), visible: true, components: [{ type: 'Transform', data: {} }] },
...kids.map((k) => ({ prefabEntityId: 'e-' + k, name: k, parent: 'root', children: [], visible: true, components: [{ type: 'Transform', data: {} }] })),
],
});
describe.skipIf(!HAS_WASM)('UIPages', () => {
let engine: ESEngineModule;
beforeAll(async () => { engine = await loadWasmModule(); });
const setup = (prefabs: Record<string, PrefabData>) => {
const world = new World();
world.connectCpp(new engine.Registry() as unknown as CppRegistry, engine);
const loads: string[] = [];
const assets = {
loadPrefab: async (ref: string) => { loads.push(ref); const data = prefabs[ref]; if (!data) throw new Error('no such prefab ' + ref); return { data }; },
acquireTyped: async () => { throw new Error('this test has no nested prefabs'); },
// What loading a scene asks of the asset system: nothing to fetch here, nothing missing.
preloadSceneAssets: async () => ({ scope: { releaseAll() {}, absorb() {} }, missing: [], textureHandles: new Map(), materialHandles: new Map() }),
resolveSceneAssetPaths() {},
trackSceneAssetReferences() {},
} as unknown as Assets;
return { world, pages: new UIPages(world, assets), loads };
};
const namesUnder = (world: World, root: Entity): string[] => {
const out: string[] = [];
const walk = (e: Entity): void => {
if (world.has(e, Name)) out.push((world.get(e, Name) as NameData).value);
if (world.has(e, Children)) for (const c of (world.get(e, Children) as ChildrenData).entities) walk(c);
};
walk(root);
return out;
};
const mountIn = (world: World, name: string): Entity => {
const e = world.spawn();
world.insert(e, Name, { value: name });
world.insert(e, Transform, {} as never);
return e;
};
it('builds a page the first time it is opened, once however many ask, and finds its nodes by name', async () => {
const { world, pages, loads } = setup({ home: page('home', ['title', 'ok']) });
const parent = mountIn(world, 'canvas');
pages.register('home', { prefab: 'home', parent });
expect(pages.isBuilt('home')).toBe(false);
let built = 0; pages.onBuilt(() => { built++; });
const [a, b] = await Promise.all([pages.open('home'), pages.open('home')]);
expect(a).toBe(b);
expect(built).toBe(1);
expect(loads).toEqual(['home']);
expect(pages.isBuilt('home')).toBe(true); expect(pages.isOpen('home')).toBe(true);
expect(a.has('ok')).toBe(true); expect(a.has('nope')).toBe(false);
expect(world.has(a.find('ok')!, Name)).toBe(true);
expect([...a.names()].sort()).toEqual(['e-title'.slice(2), 'ok', 'home'].sort());
expect((world.get(parent, Children) as ChildrenData).entities).toContain(a.root);
});
it('builds a mounted page under the mount, in order, and leaves no root of its own behind', async () => {
const { world, pages } = setup({ shop: page('shop', ['a', 'b', 'c']) });
const canvas = mountIn(world, 'canvas'), first = mountIn(world, 'first'), mount = mountIn(world, 'shop-mount'), last = mountIn(world, 'last');
for (const e of [first, mount, last]) world.setParent(e, canvas);
const before = world.getAllEntities().length;
pages.register('shop', { prefab: 'shop', mount });
const handle = await pages.open('shop');
expect(handle.root).toBe(mount);
expect(namesUnder(world, mount)).toEqual(['shop-mount', 'a', 'b', 'c']);
expect(world.getAllEntities().length).toBe(before + 3); // three children, and no stray root
expect((world.get(canvas, Children) as ChildrenData).entities).toEqual([first, mount, last]); // it kept its place
});
it('applies the overrides it was registered with', async () => {
const { world, pages } = setup({ p: page('p', ['x']) });
const mount = mountIn(world, 'm');
pages.register('p', { prefab: 'p', mount, overrides: [{ type: 'name', prefabEntityId: 'e-x', value: 'renamed' }] });
const handle = await pages.open('p');
expect(handle.has('renamed')).toBe(true); expect(handle.has('x')).toBe(false);
});
it('closing a kept page switches it off and opening it again is instant: nothing is built twice', async () => {
const { world, pages, loads } = setup({ p: page('p', ['x']) });
const mount = mountIn(world, 'm');
pages.register('p', { prefab: 'p', mount });
let built = 0; pages.onBuilt(() => { built++; });
const first = await pages.open('p');
const x = first.find('x')!;
pages.close('p');
expect(pages.isOpen('p')).toBe(false); expect(pages.isBuilt('p')).toBe(true);
expect(isEntityActive(world, mount)).toBe(false);
const again = await pages.open('p');
expect(again).toBe(first); expect(again.find('x')).toBe(x);
expect(isEntityActive(world, mount)).toBe(true);
expect(built).toBe(1); expect(loads).toEqual(['p']);
});
it('closing a destroyed page takes its contents out of the world and the next open builds them again', async () => {
const { world, pages, loads } = setup({ p: page('p', ['x', 'y']) });
const mount = mountIn(world, 'm');
pages.register('p', { prefab: 'p', mount, onClose: 'destroy' });
const first = await pages.open('p');
const x = first.find('x')!;
pages.close('p');
expect(world.valid(x)).toBe(false);
expect(pages.isBuilt('p')).toBe(false); expect(pages.page('p')).toBeNull();
expect(world.valid(mount)).toBe(true); // the scene's mount stays
expect(world.has(mount, Children) ? (world.get(mount, Children) as ChildrenData).entities.length : 0).toBe(0);
const again = await pages.open('p');
expect(again.has('x')).toBe(true); expect(again.find('x')).not.toBe(x);
expect(isEntityActive(world, mount)).toBe(true);
expect(loads).toEqual(['p']); // the prefab is fetched once
});
it('a page given a parent has a root of its own, and destroying it removes that root', async () => {
const { world, pages } = setup({ p: page('p', ['x']) });
const parent = mountIn(world, 'canvas');
pages.register('p', { prefab: 'p', parent, onClose: 'destroy' });
const handle = await pages.open('p');
expect(handle.root).not.toBe(parent);
expect((world.get(parent, Children) as ChildrenData).entities).toEqual([handle.root]);
pages.close('p');
expect(world.valid(handle.root)).toBe(false);
expect(world.has(parent, Children) ? (world.get(parent, Children) as ChildrenData).entities.length : 0).toBe(0);
});
it('looks for a name inside its own page: two pages can use the same one', async () => {
const { world, pages } = setup({ a: page('a', ['ok']), b: page('b', ['ok']) });
pages.register('a', { prefab: 'a', mount: mountIn(world, 'ma') });
pages.register('b', { prefab: 'b', mount: mountIn(world, 'mb') });
const [a, b] = [await pages.open('a'), await pages.open('b')];
expect(a.find('ok')).not.toBe(b.find('ok'));
expect(namesUnder(world, a.root)).toContain('ok'); expect(namesUnder(world, b.root)).toContain('ok');
});
it('tells the listener about each build with the page already in place, and the listener can be removed', async () => {
const { world, pages } = setup({ a: page('a', ['ok']), b: page('b', ['ok']) });
pages.register('a', { prefab: 'a', mount: mountIn(world, 'ma') });
pages.register('b', { prefab: 'b', mount: mountIn(world, 'mb') });
const seen: string[] = [];
const off = pages.onBuilt((h) => { seen.push(h.id + ':' + h.has('ok')); });
await pages.open('a'); off(); await pages.open('b');
expect(seen).toEqual(['a:true']);
});
it('refuses what cannot work: an unknown page, a page twice, a page with nowhere to go', () => {
const { world, pages } = setup({});
expect(() => pages.isOpen('nope')).toThrow(/no page "nope"/);
pages.register('p', { prefab: 'p', mount: mountIn(world, 'm') });
expect(() => pages.register('p', { prefab: 'p', mount: mountIn(world, 'm2') })).toThrow(/already registered/);
expect(() => pages.register('q', { prefab: 'q' })).toThrow(/mount or a parent/);
});
it('a prefab that fails to load rejects the open and is asked for again next time', async () => {
const prefabs: Record<string, PrefabData> = {};
const { world, pages, loads } = setup(prefabs);
pages.register('p', { prefab: 'p', mount: mountIn(world, 'm') });
await expect(pages.open('p')).rejects.toThrow(/no such prefab/);
expect(pages.isBuilt('p')).toBe(false); expect(pages.isOpen('p')).toBe(false);
prefabs.p = page('p', ['x']);
const handle = await pages.open('p');
expect(handle.has('x')).toBe(true);
expect(loads).toEqual(['p', 'p']);
});
});