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
/**
* @file What a build target cannot render, and the export saying so.
*
* The native app compiles a subset of the engine, so a project can author
* content that will not appear on the device. Two things are asserted: that the
* scan sees the authored vocabulary (scenes, prefabs, nested entities), and that
* the declared native gaps still match `native/CMakeLists.txt` — the build file
* is the truth about which sources are compiled, and flipping a flag there is
* what deletes an entry from the table.
*/
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, copyFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
collectSubsystems, subsystemGapWarnings, targetGaps, SUBSYSTEM_CMAKE_FLAG, type Subsystem,
} from '../src/project/targetSupport';
import { exportGame } from '../src/export/exportGame';
import { writeFakeSdkDist } from './fixtures/fakeSdkDist';
import { OFFICIAL_PACKAGES } from './officialPackagesDir';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const REPO = path.resolve(HERE, '..', '..');
const HOSTS = path.join(HERE, '..', '..', 'pipeline', 'src', 'runtime');
describe('collectSubsystems', () => {
it('sees components wherever they sit in the document', () => {
const scene = {
version: '1.0',
entities: [
{ id: 0, components: [{ type: 'Transform' }, { type: 'Sprite' }] },
{ id: 1, components: [{ type: 'TilemapLayer', data: { tileset: '@uuid:x' } }] },
{ id: 2, children: [{ id: 3, components: [{ type: 'Text', data: { text: 'hi' } }] }] },
],
};
expect([...collectSubsystems(scene)].sort()).toEqual(['text', 'tilemap']);
});
it('sees a prefab body and its physics vocabulary', () => {
const prefab = { version: '1.0', root: { components: [{ type: 'RigidBody2D' }, { type: 'BoxCollider2D' }] } };
expect([...collectSubsystems(prefab)]).toEqual(['physics']);
});
it('says nothing about a project that only uses what every target has', () => {
const scene = { entities: [{ components: [{ type: 'Sprite' }, { type: 'Light' }, { type: 'TrailRenderer' }] }] };
expect(collectSubsystems(scene).size).toBe(0);
});
it('ignores non-component `type` fields', () => {
expect(collectSubsystems({ importer: { type: 'texture' }, asset: { type: 'scene' } }).size).toBe(0);
});
});
describe('subsystemGapWarnings', () => {
const usage = new Map<Subsystem, string[]>([['spine', ['scenes/b.esscene', 'scenes/a.esscene']]]);
it('names the subsystem, the reason and the files', () => {
// Driven through a declared gap rather than a real one: every subsystem is
// supported on every target today, and the reporting still has to work for the
// day one is not (a flag turned off, a new platform-bound feature).
const declared = [{ subsystem: 'spine' as Subsystem, why: 'a made-up gap, for this test' }];
const [warning, ...rest] = subsystemGapWarnings('android', usage, declared);
expect(rest).toEqual([]);
expect(warning).toContain('Spine animation will not render');
expect(warning).toContain('a made-up gap, for this test');
expect(warning).toContain('scenes/a.esscene, scenes/b.esscene');
});
it('is silent about a gap the content does not use', () => {
const declared = [{ subsystem: 'spine' as Subsystem, why: 'a made-up gap' }];
expect(subsystemGapWarnings('android', new Map(), declared)).toEqual([]);
});
it('says nothing at all now that every target compiles every subsystem', () => {
expect(subsystemGapWarnings('android', usage)).toEqual([]);
expect(subsystemGapWarnings('web', usage)).toEqual([]);
});
it('reports the same gaps for both native targets — they compile one CMakeLists', () => {
expect(targetGaps('ios')).toEqual(targetGaps('android'));
});
});
describe('the native gaps match the native build', () => {
const cmake = readFileSync(path.join(REPO, 'native', 'CMakeLists.txt'), 'utf8');
const enabled = new Set([...cmake.matchAll(/set\(\s*(ES_ENABLE_\w+)\s+ON\s*\)/g)].map((m) => m[1]));
const gaps = new Set(targetGaps('android').map((g) => g.subsystem));
it.each(Object.entries(SUBSYSTEM_CMAKE_FLAG) as [Subsystem, string][])(
'%s: a source set the native build omits is declared unsupported', (subsystem, flag) => {
if (!enabled.has(flag)) expect(gaps).toContain(subsystem);
},
);
it.each(Object.keys(SUBSYSTEM_CMAKE_FLAG) as Subsystem[])(
'%s: a source set the native build compiles is not declared unsupported', (subsystem) => {
if (enabled.has(SUBSYSTEM_CMAKE_FLAG[subsystem]!)) expect(gaps).not.toContain(subsystem);
},
);
});
describe('exportGame warns about content the target cannot render', () => {
let root: string;
const TEX = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
const SCN = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
beforeAll(() => {
root = mkdtempSync(path.join(tmpdir(), 'estella-target-support-'));
mkdirSync(path.join(root, 'assets'), { recursive: true });
copyFileSync(path.join(REPO, 'examples', 'hello-world', 'assets', 'textures', 'logo.png'), path.join(root, 'assets', 'hero.png'));
writeFileSync(path.join(root, 'assets', 'hero.png.meta'), meta(TEX, 'texture'));
mkdirSync(path.join(root, 'scenes'), { recursive: true });
writeFileSync(path.join(root, 'scenes', 'main.esscene'), JSON.stringify({
version: '1.0', name: 'Main',
entities: [
{ id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] },
{ id: 1, components: [{ type: 'Text', data: { text: 'score' } }] },
{ id: 2, components: [{ type: 'ParticleEmitter', data: {} }] },
{ id: 3, components: [{ type: 'TilemapLayer', data: {} }] },
{ id: 4, components: [{ type: 'RigidBody2D', data: {} }] },
{ id: 5, components: [{ type: 'SpineAnimation', data: {} }] },
],
}));
writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
writeFakeSdkDist(path.join(root, '_sdk'));
mkdirSync(path.join(root, '_wasm'), { recursive: true });
writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'export default () => {};');
});
afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));
const run = (platform: 'android' | 'web', outDir: string) => exportGame({
root, entryScene: 'scenes/main.esscene', hostsDir: HOSTS, packagesDir: OFFICIAL_PACKAGES,
sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'),
outDir, platform, title: 'Game',
});
it('warns about nothing: the native build renders everything this scene uses', async () => {
// The scene deliberately authors every optional subsystem — text, particles,
// tilemaps, physics and spine — and the native app compiles all of them now, so
// any warning here would be false. The reporting mechanism itself is covered
// above, against a declared gap.
const res = await run('android', path.join(root, 'dist-android'));
expect(res.errors).toEqual([]);
expect(res.ok).toBe(true);
const gaps = res.warnings.filter((w) => w.startsWith('android:'));
expect(gaps).toEqual([]);
}, 60_000);
it('stays quiet for a target that renders all of it', async () => {
const res = await run('web', path.join(root, 'dist-web'));
expect(res.warnings.filter((w) => w.includes('will not render'))).toEqual([]);
}, 60_000);
});