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 check-arena-server.mjs — a multiplayer game runs without the editor.
*
* `check-headless-export` proves a project PACKAGES from the command line. This
* proves the other half of shipping a multiplayer one: that the authority runs
* as an ordinary Node process, over a real socket, driving the project's own
* gameplay code — and that the parts the editor's preview structurally cannot
* reach still work.
*
* The preview wires its players over MessagePorts inside one process. Those
* never drop, so nothing there ever exercised a connection LEAVING; and the
* host is always a player, so nothing exercised an authority with no pawn of
* its own. Both are ordinary facts of a dedicated server, and both are checked
* here against `examples/multiplayer-arena`:
*
* 1. the server boots headless (no renderer, no editor) and accepts sockets
* 2. no phantom host pawn — a keyboard-less authority owns nothing
* 3. a client's input moves ITS pawn, and the arena wall clamps it
* 4. that movement reaches a THIRD party as replicated state
* 5. a client that leaves takes its pawn with it
*
* node tools/check-arena-server.mjs
* node tools/check-arena-server.mjs --project templates/online-3d --bound 1450 --speed 340
*
* The project is any one with a `server/` and a pawn that walks right on `KeyD`; `--bound` is the world's edge along x and `--speed` the pawn's
* speed, both from the project's own movement rule. `--no-wall` is for a world too wide to cross in a check: the pawn walks for a moment instead,
* and what is asserted is that it advanced and that a third party saw it where it was (the wall itself is the movement rule's own test).
*/
import { spawn, spawnSync } from 'node:child_process';
import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { pathToFileURL, fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const flag = (name, fallback) => {
const i = process.argv.indexOf(`--${name}`);
return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
};
const PROJECT = path.resolve(ROOT, flag('project', path.join('examples', 'multiplayer-arena')));
const SDK = path.join(ROOT, 'sdk', 'dist', 'index.node.js');
const WASM = path.join(ROOT, 'build', 'wasm', 'web');
/** The world's edge along x and the pawn's speed, from the project's own movement rule (the arena's by default). */
const BOUND_X = Number(flag('bound', '420'));
const SPEED = Number(flag('speed', '260'));
const NO_WALL = process.argv.includes('--no-wall');
const STEP = 1 / 60;
// The server runs a REAL engine, so a checkout without one cannot answer this.
// Skipped where building it is a choice, an error where CI has the artifact:
// otherwise "no binary" and "the server is broken" report identically.
if (!existsSync(path.join(WASM, 'esengine.wasm'))) {
const build = 'node build-tools/cli.js build -t web';
if (process.env.ESTELLA_REQUIRE_WASM) {
console.error('check-arena-server: ESTELLA_REQUIRE_WASM is set and there is no engine wasm'
+ ` at build/wasm/web.\n ${build}`);
process.exit(1);
}
console.log('check-arena-server: no engine wasm at build/wasm/web — skipped'
+ ` (build it with \`${build}\`; the engine-coupled CI job sets ESTELLA_REQUIRE_WASM).`);
process.exit(0);
}
const work = mkdtempSync(path.join(tmpdir(), 'estella-arena-'));
const NAME = path.basename(PROJECT);
let server = null;
function fail(message, detail) {
console.error(`check-arena-server: ${message}`);
if (detail) console.error(detail);
cleanup();
process.exit(1);
}
function cleanup() {
if (server && server.exitCode === null) server.kill();
rmSync(work, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
}
const delay = (ms) => new Promise((r) => setTimeout(r, ms));
/** tsc and esbuild both want a path, not a file:// URL, with forward slashes. */
const posix = (p) => p.split(path.sep).join('/');
// ---------------------------------------------------------------------------
// Build both ends from the project's own sources.
// ---------------------------------------------------------------------------
/**
* Type-check the server entry first: esbuild only strips types, so drift from
* the SDK would surface as a runtime throw. The project's own tsconfig covers
* `src/` alone — a game project has no `ws` or `@types/node` — so the check
* runs from here, against the SDK install that does.
*/
const TSC = path.join(ROOT, 'sdk', 'node_modules', 'typescript', 'bin', 'tsc');
const SDK_TYPES = path.join(ROOT, 'sdk', 'node_modules', '@types');
const tsconfig = path.join(work, 'tsconfig.json');
writeFileSync(tsconfig, JSON.stringify({
compilerOptions: {
target: 'ES2022', module: 'ESNext', moduleResolution: 'bundler',
strict: true, skipLibCheck: true, noEmit: true, esModuleInterop: true, allowImportingTsExtensions: true,
types: ['node'], typeRoots: [posix(SDK_TYPES)],
baseUrl: '.',
paths: {
esengine: [posix(path.join(ROOT, 'sdk', 'dist', 'index.d.ts'))],
'esengine/node': [posix(path.join(ROOT, 'sdk', 'dist', 'index.node.d.ts'))],
'esengine/replication': [posix(path.join(ROOT, 'sdk', 'dist', 'net', 'replication', 'index.d.ts'))],
'esengine/terrain': [posix(path.join(ROOT, 'sdk', 'dist', 'terrain', 'index.d.ts'))],
ws: [posix(path.join(SDK_TYPES, 'ws', 'index.d.ts'))],
},
},
include: [posix(path.join(PROJECT, 'server', '**', '*.ts')), posix(path.join(PROJECT, 'src', '**', '*.ts'))],
}, null, 2));
const typed = spawnSync(process.execPath, [TSC, '-p', tsconfig], { encoding: 'utf8', cwd: ROOT });
if (typed.status !== 0) {
fail('the server entry does not type-check against the SDK.', typed.stdout || typed.stderr);
}
// The SDK and wasm are this checkout's own, a pair: a template's server has no engine tree beside it to fall back to.
const built = spawnSync(process.execPath, [
path.join(PROJECT, 'server', 'run.mjs'), '--build-only', '--sdk', path.dirname(SDK), '--wasm', WASM,
], {
encoding: 'utf8', cwd: ROOT,
// `ws` is the server's own dependency; in this checkout it is installed with the SDK, which a template has no tree beside it to find.
env: { ...process.env, NODE_PATH: [path.join(ROOT, 'sdk', 'node_modules'), path.join(ROOT, 'node_modules')].join(path.delimiter) },
});
if (built.status !== 0) fail('the server bundle failed to build.', built.stderr || built.stdout);
/**
* The client half, built from the project's REAL entry point: it registers the
* same components (the handshake compares schemas and would reject a faked
* probe) and runs the same input/prediction system a browser would. The second
* client registers nothing, which is what makes it a fair witness.
*/
const probeSource = `
// 'esengine' rather than a path: the alias below points it at the same headless
// SDK the server bundle uses, so probe and project share one module instance.
export { loadEsengineModule, createHeadlessApp, flushPendingRegistrations, GameSocket, Input, Transform } from 'esengine';
export { Net, Replicated } from 'esengine/replication';
import ${JSON.stringify(posix(path.join(PROJECT, 'src', 'main.ts')))};
`;
writeFileSync(path.join(work, 'probe.entry.ts'), probeSource);
const probeOut = path.join(work, 'probe.mjs');
const { build } = await import('esbuild');
await build({
entryPoints: [path.join(work, 'probe.entry.ts')],
outfile: probeOut,
bundle: true,
format: 'esm',
platform: 'node',
target: 'node20',
logLevel: 'silent',
// The project's `import ... from 'esengine'` resolves to the same headless SDK
// the server bundle uses — one build on both ends, which is what the
// handshake's ABI/schema check insists on.
alias: {
esengine: SDK, 'esengine/node': SDK,
'esengine/replication': path.join(path.dirname(SDK), 'net', 'replication', 'index.js'),
'esengine/terrain': path.join(path.dirname(SDK), 'terrain', 'index.js'),
},
});
const probe = await import(pathToFileURL(probeOut).href);
// ---------------------------------------------------------------------------
// Boot the server and learn the port it got.
// ---------------------------------------------------------------------------
server = spawn(process.execPath, [
path.join(PROJECT, '.esengine', 'cache', 'server.mjs'),
'--port', '0', '--wasm', WASM,
], { cwd: ROOT });
let serverLog = '';
server.stdout.on('data', (d) => { serverLog += d.toString(); });
server.stderr.on('data', (d) => { serverLog += d.toString(); });
server.on('exit', (code) => {
if (code !== 0 && code !== null) fail(`the server exited ${code}.`, serverLog);
});
const url = await (async () => {
for (let i = 0; i < 100; i++) {
const match = serverLog.match(/listening on (ws:\/\/\S+)/);
if (match) return match[1];
await delay(100);
}
return null;
})();
if (!url) fail('the server never reported a listening address.', serverLog);
// ---------------------------------------------------------------------------
// Two clients.
// ---------------------------------------------------------------------------
/** A client App on a real socket, ticking on the fixed step like a game does. */
async function connectClient({ withGameplay }) {
const app = probe.createHeadlessApp(await probe.loadEsengineModule(WASM));
// Only the first client installs the project's systems; the spectator runs
// the replication plugin alone, so what it sees it was SENT.
if (withGameplay) probe.flushPendingRegistrations(app);
const socket = new probe.GameSocket({ url });
socket.connect();
const client = await app.getResource(probe.Net).connect(socket, { interpolationDelayTicks: 0 });
return { app, client, socket };
}
/** Every replicated entity this client can see, with its position. */
function ghosts(app) {
return app.world.getEntitiesWithComponents([probe.Replicated]).map((e) => ({
entity: e,
x: app.world.tryGet(e, probe.Transform)?.position.x ?? NaN,
}));
}
/**
* Tick both apps for `seconds` of simulated time, at the rate the authority runs
* at. The server is a real 60Hz process: a client that outpaces it overruns the
* input window and has its commands refused, which reads as "replication is
* behind" while the client's own prediction sits at the wall.
*/
async function run(apps, seconds) {
for (let i = 0; i < Math.round(seconds / STEP); i++) {
for (const app of apps) await app.tick(STEP);
await delay(STEP * 1000);
}
}
/** Run until `done()`, or fail once `seconds` of simulated time have passed. */
async function runUntil(apps, seconds, done) {
for (let i = 0; i < Math.round(seconds / STEP); i++) {
if (done()) return true;
for (const app of apps) await app.tick(STEP);
await delay(STEP * 1000);
}
return done();
}
let player, spectator;
try {
player = await connectClient({ withGameplay: true });
spectator = await connectClient({ withGameplay: false });
} catch (err) {
fail(`a client could not complete the handshake: ${err?.message ?? err}`, serverLog);
}
// Let the roster settle: the authority provisions a pawn per connection on its
// next fixed tick, and the spawns come back over the socket.
await run([player.app, spectator.app], 0.5);
// 2 — the authority has no keyboard, so it owns no pawn. Two connections, two
// pawns; a third would be the host phantom this deployment must not have.
const seen = ghosts(spectator.app);
if (seen.length !== 2) {
fail(`the spectator sees ${seen.length} replicated pawn(s), expected 2 (one per connection).`
+ ' A third would mean the dedicated server spawned a host pawn it cannot steer.', serverLog);
}
// 3 — hold a direction. This is the project's own input system reading the
// project's own key bindings; nothing here reaches past it to move anything.
const input = player.app.getResource(probe.Input);
input.keysDown.add('KeyD');
const own = () => ghosts(player.app).find((g) => player.client.ownsEntity(g.entity));
const startX = own()?.x;
if (startX === undefined) fail('the connected client owns no pawn.', serverLog);
await run([player.app, spectator.app], 0.4);
const movedX = own().x;
if (!(movedX > startX + Math.min(20, SPEED * 0.4 * 0.4))) {
fail(`holding right moved the owned pawn from ${startX} to ${movedX} — expected it to advance.`, serverLog);
}
if (NO_WALL) {
// 3b/4 — keep walking for a moment, then stop: the pawn advanced by about what its speed says, and a third party sees it there.
await run([player.app, spectator.app], 0.8);
input.keysDown.delete('KeyD');
await run([player.app, spectator.app], 0.4);
const gone = own().x - startX;
if (!(gone > SPEED * 0.8 * 0.5 && gone < SPEED * 1.6 * 1.5)) {
fail(`the owned pawn walked ${gone} units in about a second and a half, expected about ${SPEED * 1.2}.`, serverLog);
}
const rest = own().x;
const witnessed = () => ghosts(spectator.app).some((g) => Math.abs(g.x - rest) < 1);
if (!await runUntil([player.app, spectator.app], 1.0, witnessed)) {
fail(`the spectator never saw the pawn where it stopped (x=${rest}; saw ${ghosts(spectator.app).map((g) => g.x).join(', ')}).`, serverLog);
}
} else {
// Long enough to cross the arena and pin against the wall. The clamp is part of
// the shared movement rule, so server and prediction must agree on it exactly.
await run([player.app, spectator.app], (BOUND_X * 2) / SPEED + 1);
input.keysDown.delete('KeyD');
const wallX = own().x;
if (Math.abs(wallX - BOUND_X) > 0.5) {
fail(`the owned pawn settled at x=${wallX}, expected the arena wall at ${BOUND_X}.`, serverLog);
}
// 4 — a third party saw it happen. The spectator runs no gameplay code at all,
// so this position can only have arrived as replicated state.
// Waiting for the state to ARRIVE rather than for a fixed duration: how many
// ticks a socket round trip takes is a property of the machine, and a deadline
// dressed up as a duration fails on a slow one while asserting nothing more.
const sawWall = () => ghosts(spectator.app).some((g) => Math.abs(g.x - BOUND_X) < 40);
if (!await runUntil([player.app, spectator.app], 1.0, sawWall)) {
const witnessed = ghosts(spectator.app).map((g) => g.x);
fail(`the spectator never saw the moving pawn reach the wall (saw x=${witnessed.join(', ')}).`, serverLog);
}
}
// 5 — leaving takes the pawn with it. This is the assertion the editor's
// preview cannot make: its MessagePorts never close.
player.client.disconnect();
player.socket.close();
await run([spectator.app], 0.6);
const after = ghosts(spectator.app);
if (after.length !== 1) {
fail(`after a client left the spectator still sees ${after.length} pawn(s), expected 1.`
+ ' The authority is not retiring pawns for departed connections.', serverLog);
}
spectator.client.disconnect();
spectator.socket.close();
cleanup();
console.log(`check-arena-server: ${NAME} served headless over a real socket — no host phantom, input moved and clamped,`
+ ' replicated to a third party, and a leaver was retired.');