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(ci): a golden run that goes to the background and comes back

esengine19ba751ade73
diff --git a/desktop/scripts/inputScript.mjs b/desktop/scripts/inputScript.mjs
index ea2aee4fd..d48b0e5b1 100644
--- a/desktop/scripts/inputScript.mjs
+++ b/desktop/scripts/inputScript.mjs
@@ -22,6 +22,9 @@
* a frame range. A playthrough is a sequence, not a posture: "walk there, turn
* round, hit it" cannot be said by keys all pressed at frame zero.
*
+ * `hidden` is a frame range the page spends in the background: document.hidden
+ * plus a visibilitychange, which is the pair the engine's lifecycle listens to.
+ *
* `pad` is a gamepad the harness holds: the engine polls navigator.getGamepads,
* so standing one up there drives its real polling path rather than poking its
* state. Each entry sets axes/buttons over a frame range.
@@ -38,6 +41,9 @@ export function inputScript(spec) {
const taps = JSON.stringify(
(spec.taps ?? []).map((t) => ({ key: String(t.key), at: Number(t.at) || 0 })),
);
+ const hidden = JSON.stringify(
+ (spec.hidden ?? []).map((h) => ({ from: Number(h.from) || 0, to: Number(h.to ?? frames) })),
+ );
const pad = JSON.stringify(
(spec.pad ?? []).map((p) => ({
from: Number(p.from) || 0,
@@ -131,6 +137,14 @@ export function inputScript(spec) {
const taps = ${taps};
const holds = ${holds};
const touches = ${touches};
+ const hiddenSpec = ${hidden};
+ const setHidden = (h) => {
+ Object.defineProperty(document, 'hidden', { value: h, configurable: true });
+ Object.defineProperty(document, 'visibilityState', {
+ value: h ? 'hidden' : 'visible', configurable: true,
+ });
+ document.dispatchEvent(new Event('visibilitychange'));
+ };
const padSpec = ${pad};
let padState = null;
if (padSpec.length) {
@@ -150,6 +164,10 @@ export function inputScript(spec) {
if (h.from === i) { fireKey('keydown', h.key); down.add(h.key); }
if (h.to === i && down.has(h.key)) { fireKey('keyup', h.key); down.delete(h.key); }
}
+ for (const h of hiddenSpec) {
+ if (i === h.from) setHidden(true);
+ else if (i === h.to) setHidden(false);
+ }
if (padState) {
for (const p of padSpec) {
const on = i >= p.from && i < p.to;
@@ -194,7 +212,7 @@ export function inputScript(spec) {
for (const k of keys) fireKey('keyup', k);
await raf();
return keys.length + taps.length + holds.length + touches.length + padSpec.length
- + (pointer ? 1 : 0);
+ + hiddenSpec.length + (pointer ? 1 : 0);
})()
`;
}
diff --git a/desktop/src/gameHost.ts b/desktop/src/gameHost.ts
index bc07096cd..96079ad35 100644
--- a/desktop/src/gameHost.ts
+++ b/desktop/src/gameHost.ts
@@ -109,7 +109,10 @@ async function boot(): Promise<void> {
for (const name of names) {
const entity = app.world.findEntityByName(name);
if (entity === null || !app.world.has(entity, Transform)) continue;
- const p = app.world.get(entity, Transform).position;
+ // World, not local: a driver asks where something IS, and for anything
+ // parented (every UI node) the local offset answers a different question.
+ const t = app.world.get(entity, Transform);
+ const p = t.worldPosition ?? t.position;
at[name] = { x: p.x, y: p.y };
}
const scenes = app.hasResource(SceneManager) ? app.getResource(SceneManager) : null;
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index bf115e61f..4c82588f5 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -72,7 +72,6 @@ export const CAPABILITIES = [
*/
export const KNOWN_GAPS = {
'safe-area': 'safe-area insets are exercised by the UI mode viewport, not by a project — Celestial Heights P5',
- 'pause-resume': 'lifecycle suspend/resume is covered by native hosts, not by a golden project — Celestial Heights P3',
rollback: 'hot-update-demo swaps forward; nothing exercises a failed manifest rolling back',
// Present in the engine and shown by non-golden samples, but never carried
// through the chain by a project the release argues from.
@@ -171,6 +170,7 @@ export const GOLDEN = [
'tilemap', 'tile-collision', 'navigation', 'behavior-tree',
'scene-transition', 'y-sort', 'localization', 'ui-layout', 'text',
'persistence', 'ui-inventory', 'achievements', 'touch', 'controller',
+ 'pause-resume',
],
targets: ['web', 'desktop'],
// Nightly, not pr: a project earns the release gate by having run, and this
@@ -188,6 +188,10 @@ export const GOLDEN = [
// that holds a pad proves the binding is more than a line of code.
pad: [{ from: 2, to: 58, axes: { 0: 1 } }],
},
+ // Backgrounded, the world stops; brought back, it carries on. Read as where
+ // Lyra got to, because a frame comparison saturates the moment her sprite
+ // stops overlapping itself and cannot tell 30 frames from 60.
+ suspend: { entity: 'Lyra_Player', keys: ['KeyD'], frames: 80, hideFrom: 20, hideTo: 50, moves: 60 },
},
{
id: 'input-actions',
@@ -269,6 +273,24 @@ export function interactFor(g) {
};
}
+/**
+ * What a project asks of a run that goes to the background and comes back, or
+ * null when it makes no claim. `entity` is read three times — never hidden,
+ * hidden and left there, hidden and brought back — and how far it got has to
+ * order itself the same way.
+ */
+export function suspendFor(g) {
+ if (!g.suspend) return null;
+ return {
+ entity: g.suspend.entity,
+ keys: g.suspend.keys ?? [],
+ frames: g.suspend.frames ?? 80,
+ hideFrom: g.suspend.hideFrom ?? 20,
+ hideTo: g.suspend.hideTo ?? 50,
+ moves: g.suspend.moves ?? 60,
+ };
+}
+
/** Absolute path to a golden project's directory. */
export function projectDir(id) {
return path.join(EXAMPLES, id);
diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjs
index e866f38fe..cb1832647 100644
--- a/tools/verify-golden.mjs
+++ b/tools/verify-golden.mjs
@@ -19,7 +19,7 @@
import { spawnSync } from 'node:child_process';
import { mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs';
import path from 'node:path';
-import { atTier, projectDir, parityFor, interactFor, ROOT } from './goldenProjects.mjs';
+import { atTier, projectDir, parityFor, interactFor, suspendFor, ROOT } from './goldenProjects.mjs';
import { frameDistance, frameCellMax, readPNG } from './frameCompare.mjs';
const argv = process.argv.slice(2);
@@ -244,6 +244,48 @@ for (const { id, target } of pairs) {
if (!answered) console.log(` the package did not visibly answer it; compare ${packagePng} and ${drivenPng}`);
}
void allAnswered;
+
+ // Backgrounded, the world stops; brought back, it carries on. Three runs of
+ // the same drive, read as how far the same entity got.
+ const suspend = suspendFor(golden);
+ if (suspend) {
+ const where = (hidden) => {
+ const r = spawnSync('npx', [
+ 'electron', path.join('scripts', LAUNCHER(target)),
+ '--dir', out, '--w', String(editor.w), '--h', String(editor.h),
+ '--probe', suspend.entity,
+ '--input', JSON.stringify({ keys: suspend.keys, frames: suspend.frames, hidden }),
+ ], { encoding: 'utf8', cwd: DESKTOP });
+ const line = (r.stdout || '').split('\n').find((l) => l.includes('probe:'));
+ if (!line) return null;
+ try {
+ return JSON.parse(line.slice(line.indexOf('{'))).at?.[suspend.entity]?.x ?? null;
+ } catch { return null; }
+ };
+
+ const never = where([]);
+ const stayed = where([{ from: suspend.hideFrom, to: suspend.frames - 1 }]);
+ const back = where([{ from: suspend.hideFrom, to: suspend.hideTo }]);
+
+ if (never === null || stayed === null || back === null) {
+ results.push({ id, target, stage: 'suspend', ok: false, why: `could not read ${suspend.entity}` });
+ console.log(`✗ ${id} ${target} — suspend: could not read ${suspend.entity} in all three runs`);
+ } else {
+ // Ordered, not merely different: a run left in the background must sit
+ // between nothing and a run that never stopped, or "resume" only means
+ // the frame kept being drawn.
+ const paused = Math.abs(never - stayed) >= suspend.moves;
+ const resumed = Math.abs(back - stayed) >= suspend.moves && Math.abs(never - back) >= suspend.moves;
+ const between = (back - stayed) * (never - back) > 0;
+ const ok = paused && resumed && between;
+ results.push({
+ id, target, stage: 'suspend', ok,
+ why: ok ? '' : `never ${never.toFixed(0)}, stayed hidden ${stayed.toFixed(0)}, came back ${back.toFixed(0)}`,
+ });
+ console.log(`${ok ? '✓' : '✗'} ${id} ${target} — suspend: ${suspend.entity} at `
+ + `${stayed.toFixed(0)} hidden, ${back.toFixed(0)} back, ${never.toFixed(0)} never stopped`);
+ }
+ }
}
const bad = results.filter((r) => !r.ok);