Skip to content

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.

feat(gates): the start screen is judged over a link a phone actually has

esengine0a4c2ffc1070
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.