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 verify-remote-capture.mjs — a development build dials the editor, and the
* editor captures and replays one of its frames.
*
* The editor's own server (desktop/shared/debugChannelServer.mjs) listens; a golden
* project is exported with the channel and opened the way a player opens it; the
* frame comes back over the socket. Asked of the package, not of the editor's
* realms, because a capture that only works in-process is the one this exists to
* go beyond. Also asked: a dial with the wrong token is refused, and a shipping
* export will not carry a channel at all.
*
* node tools/verify-remote-capture.mjs [--project input-actions] [--platform web]
*/
import { spawnSync } from 'node:child_process';
import { createRequire } from 'node:module';
import { mkdirSync, rmSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { projectDir, ROOT } from './goldenProjects.mjs';
import { spawnElectron } from './lib/electronRun.mjs';
import { createDebugChannelServer } from '../desktop/shared/debugChannelServer.mjs';
const argv = process.argv.slice(2);
const arg = (name, fallback) => {
const i = argv.indexOf(`--${name}`);
return i >= 0 ? argv[i + 1] : fallback;
};
const PROJECT = arg('project', 'input-actions');
const PLATFORM = arg('platform', 'web');
const LAUNCHER = { web: 'launch-export.mjs', wechat: 'launch-minigame.mjs', douyin: 'launch-minigame.mjs' }[PLATFORM];
if (!LAUNCHER) {
console.error(`verify-remote-capture: no launcher for ${PLATFORM}`);
process.exit(2);
}
const WORK = path.join(ROOT, 'build', 'remote-capture');
const { WebSocketServer, WebSocket } = createRequire(path.join(ROOT, 'desktop', 'package.json'))('ws');
const problems = [];
const check = (ok, what) => {
console.log(`${ok ? '✓' : '✗'} ${what}`);
if (!ok) problems.push(what);
};
const exportPackage = (out, extra) => spawnSync(process.execPath, [
path.join(ROOT, 'pipeline', 'bin', 'estella.mjs'), 'export', projectDir(PROJECT),
'--platform', PLATFORM, '--out', out, ...extra,
], { encoding: 'utf8', cwd: ROOT });
const lines = [];
const server = await createDebugChannelServer({
WebSocketServer, host: '127.0.0.1', onLog: (_id, level, line) => lines.push({ level, line }),
});
let child = null;
try {
const refused = await new Promise((resolve) => {
const ws = new WebSocket(`ws://127.0.0.1:${server.port}/?token=not-${server.token}`);
ws.on('unexpected-response', (_req, res) => resolve(res.statusCode));
ws.on('open', () => { ws.close(); resolve('open'); });
ws.on('error', () => {});
});
check(refused === 401, `a dial with the wrong token is refused at the upgrade (got ${refused})`);
mkdirSync(WORK, { recursive: true });
const shipping = exportPackage(path.join(WORK, 'shipping'), ['--minify', '--debug-channel', server.urlFor('127.0.0.1')]);
check(shipping.status !== 0 && /never carries a debug channel/.test(`${shipping.stdout}${shipping.stderr}`),
'a shipping export refuses the channel');
const out = path.join(WORK, `${PROJECT}-${PLATFORM}`);
rmSync(out, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
const exported = exportPackage(out, ['--debug-channel', server.urlFor('127.0.0.1')]);
if (exported.status !== 0) {
console.error(`${exported.stdout}${exported.stderr}`.trim().split('\n').slice(-8).join('\n'));
throw new Error(`export of ${PROJECT} for ${PLATFORM} failed`);
}
const connected = new Promise((resolve) => {
const poll = setInterval(() => {
const t = server.targets()[0];
if (t) { clearInterval(poll); resolve(t); }
}, 100);
});
child = spawnElectron([path.join(ROOT, 'tools', 'launchers', LAUNCHER), '--dir', out,
'--settle', '3600', '--timeout', '60000'], { cwd: ROOT, stdio: ['ignore', 'pipe', 'pipe'] });
let log = '';
child.stdout.on('data', (d) => { log += d; });
child.stderr.on('data', (d) => { log += d; });
const exited = new Promise((resolve) => child.on('close', resolve));
const target = await Promise.race([
connected,
exited.then(() => null),
new Promise((resolve) => setTimeout(() => resolve(null), 90_000)),
]);
check(!!target, `the package dialled the editor${target ? ` (${target.platform}, protocol ${target.protocol})` : ''}`);
if (!target) {
console.error(log.trim().split('\n').slice(-12).join('\n'));
throw new Error('no device connected');
}
const report = await server.query(target.id, 'frameCapture');
const draws = report?.draws ?? [];
check(draws.length > 0 && report.passCount >= 1,
`a frame came back over the socket: ${draws.length} draw(s) in ${report?.passCount ?? 0} pass(es)`);
const named = Object.keys(report?.names ?? {}).length;
check(named > 0, `the device named its entities (${named})`);
const scene = draws.filter((d) => d.pass === 0);
const last = (scene.length ? scene : draws).at(-1);
const image = last ? await server.query(target.id, 'frameReplay', { drawIndex: last.index }) : null;
const size = image ? image.width * image.height * 4 : 0;
check(!!image && size > 0 && image.pixels.byteLength === size,
`the replay of draw ${last?.index} came back as ${image?.width}x${image?.height} RGBA (${image?.pixels.byteLength ?? 0} bytes)`);
check(!!image?.matchesCapture, 'the replay matches the frame it was captured from');
let lit = 0;
for (let i = 0; image && i < image.pixels.length; i += 4) {
if (image.pixels[i + 3] > 0 && (image.pixels[i] | image.pixels[i + 1] | image.pixels[i + 2]) > 8) lit++;
}
check(lit > 0, `the replayed pass has drawn pixels (${lit})`);
// A replay is one pass on a transparent background; what the player sees is
// every pass composited, opaque everywhere.
const screen = await server.query(target.id, 'screen', { maxSide: 400 });
let clear = 0;
const colours = new Set();
for (let i = 0; screen && i < screen.pixels.length; i += 4) {
if (screen.pixels[i + 3] < 255) clear++;
colours.add((screen.pixels[i] << 16) | (screen.pixels[i + 1] << 8) | screen.pixels[i + 2]);
}
check(!!screen && screen.width > 0 && screen.pixels.byteLength === screen.width * screen.height * 4 && clear === 0,
`the screen came back whole and opaque: ${screen?.width}x${screen?.height}, ${clear} see-through pixel(s)`);
check(colours.size > 1, `the screen shows more than one colour (${colours.size}: ${[...colours].slice(0, 3).map((c) => c.toString(16)).join(",")})`);
const now = server.targets().find((t) => t.id === target.id);
check(now?.project === 'Input Actions' && typeof now?.revision === 'string',
`the build said which project and content it is (${now?.project}, ${now?.revision})`);
// Lines travel in batches, behind whatever answer is on the socket.
for (const until = Date.now() + 5000; Date.now() < until && !lines.some((l) => /EstellaContext initialized/.test(l.line));) {
await new Promise((r) => setTimeout(r, 100));
}
check(lines.some((l) => /EstellaContext initialized/.test(l.line)),
`what the device printed before it connected reached the editor (${lines.length} line(s))`);
// The first ask turns timings on; they exist once the device has run a frame since,
// which a software-rendered runner can take a second or more to do.
await server.query(target.id, 'stats');
let stats = null;
for (const until = Date.now() + 10_000; Date.now() < until;) {
await new Promise((r) => setTimeout(r, 250));
stats = await server.query(target.id, 'stats');
if (Object.keys(stats?.phases ?? {}).length > 0) break;
}
check(stats?.entities > 0 && Object.keys(stats?.phases ?? {}).length > 0 && stats?.wasmBytes > 0,
`the device reported its frame: ${stats?.entities} entities, ${Object.keys(stats?.phases ?? {}).length} phase(s), ${stats?.wasmBytes} wasm bytes`);
// What the channel costs the game it watches, over a window of frames, by its own clock.
await server.query(target.id, 'stats');
await new Promise((r) => setTimeout(r, 2000));
const cost = await server.query(target.id, 'stats');
const perFrame = cost?.frames > 0 ? cost.agentMs / cost.frames : NaN;
// A runner that draws a frame or two a second, on a clock that steps by 1 ms,
// reads one step over one frame as 1 ms a frame: that is the clock, not a cost.
const belowClock = typeof cost?.clockMs === 'number' && cost.agentMs <= cost.clockMs;
check(typeof cost?.agentMs === 'number' && cost.frames > 0 && (perFrame <= 0.5 || belowClock),
`the debug channel cost the device ${cost?.agentMs?.toFixed(3)} ms over ${cost?.frames} frame(s) — ${perFrame.toFixed(4)} ms a frame (budget 0.5; clock step ${cost?.clockMs})`);
const tree = (await server.query(target.id, 'snapshot', { selectedId: null, withTree: true }))?.tree;
const ship = tree?.entities.find((e) => e.name === 'Ship');
const one = ship ? (await server.query(target.id, 'snapshot', { selectedId: ship.id, withTree: false }))?.selected : null;
const transform = one?.components.find((c) => c.type === 'Transform');
check(!!ship && typeof transform?.data?.position?.x === 'number',
`the device's world came back: ${tree?.entities.length ?? 0} entities, Ship's Transform ${JSON.stringify(transform?.data?.position)}`);
const paused = await server.query(target.id, 'control', { paused: true, fps: 30 });
const stepped = await server.query(target.id, 'control', { step: 2 });
const resumed = await server.query(target.id, 'control', { paused: false, fps: 0 });
check(paused.paused && paused.fps === 30 && stepped.paused && !resumed.paused && resumed.fps === 0,
`the device paused, stepped while paused, capped and resumed (${JSON.stringify([paused, stepped, resumed])})`);
} catch (e) {
problems.push(e.message);
console.error(`✗ ${e.message}`);
} finally {
child?.kill();
await server.close();
}
if (problems.length) {
console.error(`\nverify-remote-capture: ${problems.length} problem(s) — ${PROJECT} on ${PLATFORM}`);
process.exit(1);
}
console.log(`\nverify-remote-capture: ${PROJECT} on ${PLATFORM} — captured and replayed over the debug channel.`);