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): open the projects we actually released, with the editor of today

esenginee68f9e281c2e
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 2177bbb29..b35df1395 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -536,6 +536,14 @@ jobs:
ELECTRON_DISABLE_SANDBOX: '1'
run: xvfb-run -a node tools/verify-golden.mjs --tier pr
+ # Projects as they were RELEASED, opened by the editor of today. The golden
+ # corpus is re-saved by whoever last touched it, so it can only say that this
+ # version opens its own files; a person's project is not re-saved by anybody.
+ - name: Open released projects (PR tier)
+ env:
+ ELECTRON_DISABLE_SANDBOX: '1'
+ run: xvfb-run -a node tools/verify-legacy.mjs --tier pr
+
# The SAME pixel assertions on the WebGPU backend — Dawn renders through the
# bundled SwiftShader Vulkan (--use-webgpu-adapter=swiftshader), so a GPU-less
# runner verifies the second backend for real: WGSL twins, the reflected
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index 824b3af1a..ff3224c09 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -164,6 +164,27 @@ export const GOLDEN = [
},
];
+/**
+ * Projects as they were RELEASED — what a golden project cannot ask, since every
+ * example is re-saved by whoever last touched it. Git history rather than
+ * fixtures: an invented "old project" is only old in imitated ways. The risk is
+ * component data; the envelope has not changed since v0.20.0.
+ */
+export const LEGACY = [
+ { tag: 'v0.20.0', id: 'platformer', tier: 'pr' },
+ { tag: 'v0.30.0', id: 'platformer', tier: 'nightly' },
+ { tag: 'v0.30.0', id: 'ui-controls', tier: 'nightly' },
+ { tag: 'v0.40.0', id: 'tilemap-demo', tier: 'nightly' },
+ { tag: 'v0.46.0', id: 'space-shooter', tier: 'release' },
+];
+
+/** Released projects a tier must still be able to open. */
+export function legacyAtTier(tier) {
+ const want = TIERS.indexOf(tier);
+ if (want < 0) throw new Error(`unknown tier "${tier}" (have: ${TIERS.join(', ')})`);
+ return LEGACY.filter((l) => TIERS.indexOf(l.tier) <= want);
+}
+
const rank = (tier) => TIERS.indexOf(tier);
/** Golden projects that run at `tier` — cheaper tiers included (they are cumulative). */
diff --git a/tools/verify-legacy.mjs b/tools/verify-legacy.mjs
new file mode 100644
index 000000000..ff0429a4c
--- /dev/null
+++ b/tools/verify-legacy.mjs
@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file verify-legacy.mjs — today's editor still opens what an older one wrote.
+ *
+ * The golden corpus is always current: every example is re-saved by whichever
+ * editor last touched it, so it can only ever answer "does this version open its
+ * own files". A person's project is not re-saved by anybody. This takes projects
+ * as they were RELEASED — straight out of git, not imitated — opens each in the
+ * editor of today, and holds the result against the file that went out.
+ *
+ * "It opened" is the weak claim. The strong one is that nothing was quietly
+ * dropped: the editor's model is documented as lossless over unknown component
+ * types, so every entity and every component in the released file must still be
+ * there afterwards. A component the editor no longer understands must survive as
+ * data, not vanish because nothing renders it.
+ *
+ * node tools/verify-legacy.mjs --tier pr
+ * node tools/verify-legacy.mjs --tag v0.20.0 --id platformer
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { legacyAtTier, ROOT } from './goldenProjects.mjs';
+
+const argv = process.argv.slice(2);
+const flag = (n, d) => {
+ const i = argv.indexOf(`--${n}`);
+ return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d;
+};
+const TIER = flag('tier', 'pr');
+const DESKTOP = path.join(ROOT, 'desktop');
+
+const cases = flag('tag', '') && flag('id', '')
+ ? [{ tag: flag('tag', ''), id: flag('id', ''), tier: TIER }]
+ : legacyAtTier(TIER);
+
+/** Check out one example directory as it was at `tag`. */
+function extract(tag, id, into) {
+ mkdirSync(into, { recursive: true });
+ const archive = spawnSync('git', ['archive', tag, `examples/${id}`], {
+ cwd: ROOT, encoding: 'buffer', maxBuffer: 1 << 28,
+ });
+ if (archive.status !== 0) return `no examples/${id} at ${tag}`;
+ const untar = spawnSync('tar', ['-x', '-C', into, '--strip-components=2'], { input: archive.stdout });
+ if (untar.status !== 0) return `could not unpack ${id} at ${tag}`;
+ return existsSync(path.join(into, 'project.esproject')) ? null : `${tag} has no project.esproject for ${id}`;
+}
+
+/** Every scene the released project carried, as `{ path: parsed }`. */
+function releasedScenes(dir) {
+ const out = {};
+ const walk = (d) => {
+ for (const e of readdirSync(d, { withFileTypes: true })) {
+ const p = path.join(d, e.name);
+ if (e.isDirectory()) walk(p);
+ else if (e.name.endsWith('.esscene')) out[path.relative(dir, p)] = JSON.parse(readFileSync(p, 'utf8'));
+ }
+ };
+ const assets = path.join(dir, 'assets');
+ if (existsSync(assets)) walk(assets);
+ return out;
+}
+
+/** Entity id → sorted component types, the shape a lossless open must preserve. */
+function shapeOf(scene) {
+ const out = {};
+ for (const e of scene.entities ?? []) {
+ out[e.id] = (e.components ?? []).map((c) => c.type).sort();
+ }
+ return out;
+}
+
+let failed = 0;
+for (const { tag, id } of cases) {
+ const work = mkdtempSync(path.join(tmpdir(), `estella-legacy-${id}-`));
+ try {
+ const bad = extract(tag, id, work);
+ if (bad) {
+ console.log(`✗ ${id} @ ${tag} — ${bad}`);
+ failed++;
+ continue;
+ }
+ const scenes = releasedScenes(work);
+ const entry = JSON.parse(readFileSync(path.join(work, 'project.esproject'), 'utf8')).defaultScene;
+ const released = entry && scenes[path.relative('', entry)] ? scenes[path.relative('', entry)] : Object.values(scenes)[0];
+ if (!released) {
+ console.log(`✗ ${id} @ ${tag} — the released project carried no scene`);
+ failed++;
+ continue;
+ }
+
+ // Open it in the editor of today and read back what the model holds.
+ const probe = `(() => {
+ const s = window.__estellaEditor.surface;
+ const doc = s.serializeScene();
+ const shape = {};
+ for (const e of (doc && doc.entities) || []) {
+ shape[e.id] = (e.components || []).map((c) => c.type).sort();
+ }
+ return JSON.stringify(shape);
+ })()`;
+ const run = spawnSync('npx', ['electron', '.'], {
+ encoding: 'utf8',
+ cwd: DESKTOP,
+ env: {
+ ...process.env,
+ ESTELLA_SHOT: path.join(work, 'open.png'),
+ ESTELLA_SHOT_PROJECT: work,
+ ESTELLA_SHOT_EVAL: probe,
+ },
+ });
+ const line = (run.stdout || '').split('\n').find((l) => l.startsWith('[eval] '));
+ if (!line) {
+ console.log(`✗ ${id} @ ${tag} — the editor never reported a scene`);
+ for (const l of (run.stdout || run.stderr || '').split('\n').slice(-6)) if (l.trim()) console.log(` ${l}`);
+ failed++;
+ continue;
+ }
+ const loaded = JSON.parse(line.slice(7));
+ const want = shapeOf(released);
+
+ const missingEntities = Object.keys(want).filter((k) => !(k in loaded));
+ const droppedComponents = [];
+ for (const [eid, types] of Object.entries(want)) {
+ if (!loaded[eid]) continue;
+ const have = new Set(loaded[eid]);
+ for (const t of types) if (!have.has(t)) droppedComponents.push(`${eid}:${t}`);
+ }
+
+ if (missingEntities.length || droppedComponents.length) {
+ console.log(`✗ ${id} @ ${tag} — opening it lost content`);
+ if (missingEntities.length) console.log(` ${missingEntities.length} entity(ies) gone: ${missingEntities.slice(0, 6).join(', ')}`);
+ if (droppedComponents.length) console.log(` ${droppedComponents.length} component(s) gone: ${droppedComponents.slice(0, 6).join(', ')}`);
+ failed++;
+ } else {
+ console.log(`✓ ${id} @ ${tag} — ${Object.keys(want).length} entities, every component still there`);
+ }
+ } finally {
+ rmSync(work, { recursive: true, force: true });
+ }
+}
+
+console.log(`\nlegacy ${TIER}: ${cases.length - failed}/${cases.length} released project(s) still open`);
+if (failed) process.exit(1);