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
feat(gates): the start screen is judged over a link a phone actually has
esengine0a4c2ffc1070
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjsindex a473d580b..fa3c2a54d 100644--- a/tools/goldenProjects.mjs+++ b/tools/goldenProjects.mjs@@ -893,6 +893,9 @@ export const GOLDEN = [// limit. Naming it here lets the host REFUSE it too: on a bad network the// game cannot start, and all it can still do is say which package failed.subpackage: { name: 'engine' },+ // A first screen is a question about a NETWORK — on this machine the whole+ // boot beats the splash's own fade. Judged over a declared link instead.+ firstScreen: { link: 'slow-4g', maxMs: 300 },},{id: 'sprite-animation',@@ -1005,6 +1008,11 @@ export function audioFor(g) {return g.audio ?? null;}+/** The start-screen claim, or null. See input-actions. */+export function firstScreenFor(g) {+ return g.firstScreen ?? null;+}+/** The 分包 a mini-game package rides, or null. See input-actions. */export function subpackageFor(g) {return g.subpackage ?? null;diff --git a/tools/launchers/launch-export.mjs b/tools/launchers/launch-export.mjsindex f9ced587e..13ff9b734 100644--- a/tools/launchers/launch-export.mjs+++ b/tools/launchers/launch-export.mjs@@ -58,6 +58,7 @@ import path from 'node:path';import { fileURLToPath } from 'node:url';import { onRendererConsole } from '../lib/rendererConsole.mjs';import { inputScript } from './inputScript.mjs';+import { networkProfile } from './networkProfiles.mjs';// Headless / GPU-less (CI) WebGL2 falls back to SwiftShader; harmless with a GPU.// Without it Chromium refuses the context outright and the package boots to@@ -99,8 +100,37 @@ const SETTLE = Number(flag('settle', '30'));const INPUT = flag('input', '');const TIMEOUT = Number(flag('timeout', '30000'));const LOG = flag('log', '');+/** Emulate a link before loading, so the start screen is asked a real question. */+const THROTTLE = flag('throttle', '');+/** Report when the first screen appeared and how its progress moved. */+const BOOT = has('boot');const logRe = LOG ? new RegExp(LOG, 'i') : null;+/**+ * Installed ahead of the page's own scripts, in the page's world: the start+ * screen announces its boot on `window`, and a listener attached after the load+ * has already missed the stages that made the wait worth showing.+ */+const BOOT_RECORDER = `(() => {+ const marks = [];+ let firstFrame = null;+ addEventListener('esengine:bootprogress', (e) => marks.push({+ ms: Math.round(performance.now()),+ stage: e.detail && e.detail.stage,+ progress: e.detail && e.detail.progress,+ }));+ addEventListener('esengine:firstframe', () => { firstFrame = Math.round(performance.now()); });+ window.__estellaBoot = () => {+ const paint = performance.getEntriesByType('paint')+ .find((p) => p.name === 'first-contentful-paint');+ return {+ firstScreenMs: paint ? Math.round(paint.startTime) : null,+ firstFrameMs: firstFrame,+ marks,+ };+ };+})();`;+const MIME = {'.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript','.json': 'application/json', '.wasm': 'application/wasm', '.png': 'image/png',@@ -213,8 +243,52 @@ const SCENE = flag('scene', '');});win.webContents.on('render-process-gone', (_e, d) => errors.push(`render process gone: ${d.reason}`));+ // Before the load, and through Chrome's own emulation rather than a hand-rolled+ // server: the numbers are the vendor's, and a recorder installed here runs in+ // the page's own world ahead of every script the page carries.+ if (THROTTLE || BOOT) {+ // A window that has never navigated answers no CDP command — `Page.enable`+ // simply never resolves. One blank document is enough to make it a page.+ await win.loadURL('about:blank');+ win.webContents.debugger.attach('1.3');+ await win.webContents.debugger.sendCommand('Page.enable');+ if (THROTTLE) {+ const link = networkProfile(THROTTLE);+ await win.webContents.debugger.sendCommand('Network.enable');+ await win.webContents.debugger.sendCommand('Network.emulateNetworkConditions', {+ offline: false,+ latency: link.latency,+ downloadThroughput: link.downloadThroughput,+ uploadThroughput: link.uploadThroughput,+ });+ console.log(` link: ${THROTTLE} — ${link.note}`);+ }+ if (BOOT) {+ await win.webContents.debugger.sendCommand('Page.addScriptToEvaluateOnNewDocument', {+ source: BOOT_RECORDER,+ });+ }+ }+await win.loadURL(base);+ // A boot measurement waits for the boot, not for a canvas with a size: the+ // splash covers a canvas that exists from the first byte of HTML, so the frame+ // gate below is satisfied long before the game has anything to draw.+ if (BOOT) {+ await win.webContents.executeJavaScript(`+ new Promise((resolve) => {+ const deadline = Date.now() + ${TIMEOUT};+ const tick = () => {+ if (window.__estellaBoot?.().firstFrameMs != null) return resolve(true);+ if (Date.now() > deadline) return resolve(false);+ setTimeout(tick, 100);+ };+ tick();+ })+ `).catch((e) => { errors.push(String(e)); return false; });+ }+// Wait for a real frame rather than a wall-clock guess: the engine paints when// its wasm and assets are in, which is exactly the part a package can get wrong.const paint = await win.webContents.executeJavaScript(`@@ -255,6 +329,17 @@ const SCENE = flag('scene', '');console.log(` probe: ${JSON.stringify(seen)}`);}+ if (BOOT) {+ const seen = await win.webContents.executeJavaScript('window.__estellaBoot?.() ?? null')+ .catch((e) => ({ error: String(e) }));+ // Monotonic is the claim, not "reached 100%": a bar that goes back is worse+ // than one that stops, and only the sequence can say which happened.+ const steps = (seen?.marks ?? []).map((m) => m.progress);+ const backwards = steps.findIndex((p, i) => i > 0 && p < steps[i - 1]);+ console.log(` boot: ${JSON.stringify({ ...seen, monotonic: backwards < 0 })}`);+ if (backwards >= 0) errors.push(`the boot bar went backwards at step ${backwards}`);+ }+if (STREAMING) {const seen = await win.webContents.executeJavaScript('window.__estellaCooked?.streaming() ?? null',diff --git a/tools/launchers/networkProfiles.mjs b/tools/launchers/networkProfiles.mjsnew file mode 100644index 000000000..80399ae88--- /dev/null+++ b/tools/launchers/networkProfiles.mjs@@ -0,0 +1,35 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file networkProfiles.mjs — the links a start screen is judged on.+ *+ * A first screen is a question about a NETWORK, and a machine with a fast one+ * cannot ask it — the whole boot lands inside the splash's own fade. So a run+ * declares a link, and the numbers are somebody else's published recommendation.+ */++/**+ * Link conditions, in the units Chrome's `Network.emulateNetworkConditions`+ * takes (bytes/second, milliseconds). `note` is quoted verbatim with its source,+ * so the reader checks the arithmetic below against the recommendation.+ */+export const NETWORK_PROFILES = {+ 'slow-4g': {+ latency: 150,+ downloadThroughput: (1.6 * 1024 * 1024) / 8,+ uploadThroughput: (750 * 1024) / 8,+ note: 'Lighthouse: "This is the standard recommendation for mobile throttling"'+ + ' — "Latency: 150ms", "Throughput: 1.6Mbps down / 750 Kbps up.". The preset is'+ + ' "currently called \'Slow 4G\' but used to be labeled as \'Fast 3G\'".'+ + ' https://github.com/GoogleChrome/lighthouse/blob/main/docs/throttling.md',+ },+};++/** The profile named, or a throw listing the ones there are. */+export function networkProfile(name) {+ const profile = NETWORK_PROFILES[name];+ if (!profile) {+ throw new Error(`unknown network profile "${name}" — have: ${Object.keys(NETWORK_PROFILES).join(', ')}`);+ }+ return profile;+}diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjsindex 84b6e7fd4..c546bc059 100644--- a/tools/verify-golden.mjs+++ b/tools/verify-golden.mjs@@ -25,7 +25,7 @@ import { spawn, spawnSync } from 'node:child_process';import { fileURLToPath } from 'node:url';import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs';import path from 'node:path';-import { atTier, sharesOf, projectDir, parityFor, interactFor, audioFor, suspendFor, safeAreaFor, atlasFor, subpackageFor, webPixels, launchTimeoutFor, ROOT } from './goldenProjects.mjs';+import { atTier, sharesOf, projectDir, parityFor, interactFor, audioFor, suspendFor, safeAreaFor, atlasFor, subpackageFor, firstScreenFor, webPixels, launchTimeoutFor, ROOT } from './goldenProjects.mjs';import { frameDistance, frameCellMax, readPNG } from './frameCompare.mjs';import { retryOnDeadGpu, deadGpuVerdict, launchNeverHappenedVerdict, failureLines } from './lib/deadGpu.mjs';import { runElectron, ensureElectronBinary } from './lib/electronRun.mjs';@@ -55,6 +55,10 @@ const COMPARABLE = OWNED;const DESKTOP = path.join(ROOT, 'desktop');+/** A throttled boot is the whole package over a phone's link — minutes, not the+ * 30s an unthrottled launch gets. */+const FIRST_SCREEN_TIMEOUT_MS = 180_000;+/*** Where the engine binary a target packages comes from, and which build variant* it is. Checked PER TARGET: the variants are separate builds, and a stale one@@ -438,6 +442,30 @@ for (const { id, target } of pairs) {console.log(`${ok ? '✓' : '✗'} ${id} ${target} — audio: ${audio.bar} at ${height ?? 'nothing'} (silent floor ${audio.floor})`);}+ // When the start screen appears, over a link a phone actually has. A machine+ // with a fast one cannot ask this: the whole boot lands inside the fade.+ const firstScreen = target === 'web' ? firstScreenFor(golden) : null;+ if (firstScreen) {+ const run = launchPackage(id, target, [+ '--dir', out, '--boot', '--throttle', firstScreen.link,+ '--timeout', String(FIRST_SCREEN_TIMEOUT_MS), '--settle', '10',+ ]);+ const found = /boot: (\{.*\})/.exec(run.stdout || '');+ let boot = null;+ try { boot = found ? JSON.parse(found[1]) : null; } catch { boot = null; }+ const at = boot?.firstScreenMs ?? null;+ const ok = typeof at === 'number' && at <= firstScreen.maxMs && boot?.monotonic === true;+ results.push({+ id, target, stage: 'first-screen', ok,+ why: ok ? '' : at === null+ ? 'the page reported no first paint at all — nothing was on screen to time'+ : `the start screen appeared at ${at}ms over ${firstScreen.link}`+ + ` (limit ${firstScreen.maxMs}ms)${boot?.monotonic === false ? ', and its progress went backwards' : ''}`,+ });+ console.log(`${ok ? '✓' : '✗'} ${id} ${target} — start screen at ${at ?? 'never'}ms over ${firstScreen.link}`+ + `, first frame at ${boot?.firstFrameMs ?? 'never'}ms`);+ }+// The 分包 the host REFUSES. The ordinary launch above already proved the happy// half (this package's engine rides a 分包, so it booted through one); what has// never run is the half a player on a bad network gets.