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.

fix(build): date each wasm variant by its own build, not by the manifest

esenginee6f72e46eaa6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8209dccb1..7598e8e57 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,17 @@ published separately; it ships inside the editor.
### Fixed
+- **The engine-freshness gate answers per build variant.** `wasm.manifest.json`
+ carried one `builtAt`, stamped whenever the manifest was last written, and
+ listed the variants merely present on disk — so building `-t web` vouched for a
+ wechat binary of any age. A mini-game golden pair then failed its ABI handshake
+ and read as a component regression (`Draggable: missing addDraggable`) with the
+ freshness gate green. Each variant is now dated from its own newest artifact
+ (manifest schema 2, written into the build dirs as well as the synced ones),
+ `staleEngineBuild` takes the variant in question and names its build command,
+ and `verify-golden` checks the engine behind every target a tier will package
+ before it packages the first one.
+
- **A drag turns the view the way it grabs it.** Dragging the editor eye moved the
yaw one way and the pitch the other: a diagonal drag pulled the scene left while
pulling it down, because only the vertical half followed the pointer. Both halves
diff --git a/build-tools/tasks/sync.js b/build-tools/tasks/sync.js
index e241e7591..a31477257 100644
--- a/build-tools/tasks/sync.js
+++ b/build-tools/tasks/sync.js
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import path from 'path';
import { mkdir, cp, readdir, rm, stat, readFile, writeFile } from 'fs/promises';
-import { existsSync } from 'fs';
+import { existsSync, readdirSync, statSync } from 'fs';
import { execSync } from 'child_process';
import config from '../build.config.js';
import * as logger from '../utils/logger.js';
@@ -62,16 +62,31 @@ export async function syncToDesktop(options = {}) {
return { synced };
}
-// Write wasm.manifest.json into each wasm dest dir: the ABI hash the binary was
-// built against, the build variant(s) present, and git/time provenance. The
-// abiHash is read from the freshly-built SDK metadata — the wasm and that
-// constant are generated together by the EHT pipeline, so it faithfully mirrors
-// the binary's getAbiLayoutHash(). Defensive: a failure here only warns.
+/** The newest artifact in a directory, in epoch ms — 0 for an empty/absent one.
+ * Flat by design: a wasm output dir has no subdirectories. */
+function newestArtifact(dir) {
+ if (!existsSync(dir)) return 0;
+ let newest = 0;
+ for (const name of readdirSync(dir)) {
+ if (name === 'wasm.manifest.json') continue; // an output of this function
+ try {
+ const at = statSync(path.join(dir, name)).mtimeMs;
+ if (at > newest) newest = at;
+ } catch { /* raced with a rebuild — the other files still answer */ }
+ }
+ return newest;
+}
+
+// Write wasm.manifest.json into each wasm dir: ABI hash, per-variant build time,
+// git provenance. A variant is dated from ITS OWN newest artifact — they are
+// separate builds, so one `-t web` restamp would vouch for any age of wechat.
async function writeWasmManifest(rootDir) {
try {
- const variants = [...new Set(Object.keys(config.sync.wasm).map((src) => path.basename(src)))].filter(
- (v) => existsSync(path.join(rootDir, 'build/wasm', v)),
- );
+ const variants = {};
+ for (const src of new Set(Object.keys(config.sync.wasm))) {
+ const at = newestArtifact(path.join(rootDir, src));
+ if (at > 0) variants[path.basename(src)] = { builtAt: new Date(at).toISOString() };
+ }
const genPath = path.join(config.paths.sdk, 'src/ecs/component.generated.ts');
const gen = await readFile(genPath, 'utf8');
@@ -86,24 +101,28 @@ async function writeWasmManifest(rootDir) {
}
const manifest = {
- schema: 1,
+ schema: 2,
abiHash,
editorTarget: 'web',
variants,
gitSha,
- builtAt: new Date().toISOString(),
+ stampedAt: new Date().toISOString(),
};
- const dests = [...new Set(Object.values(config.sync.wasm))];
- for (const dest of dests) {
- const destDir = path.join(rootDir, dest);
- if (!existsSync(destDir)) continue;
+ // Both the build dirs and the synced ones: whoever asks how old a binary
+ // is asks the directory they are about to package FROM, and only half of
+ // those are the editor's.
+ const dirs = [...new Set([...Object.keys(config.sync.wasm), ...Object.values(config.sync.wasm)])];
+ for (const dir of dirs) {
+ const abs = path.join(rootDir, dir);
+ if (!existsSync(abs)) continue;
await writeFile(
- path.join(destDir, 'wasm.manifest.json'),
+ path.join(abs, 'wasm.manifest.json'),
JSON.stringify(manifest, null, 2) + '\n',
);
}
- logger.debug(`Stamped wasm.manifest.json (abi=${abiHash} git=${gitSha} variants=${variants.join(',') || 'none'})`);
+ const ages = Object.entries(variants).map(([v, s]) => `${v}@${s.builtAt}`).join(' ');
+ logger.debug(`Stamped wasm.manifest.json (abi=${abiHash} git=${gitSha} ${ages || 'no variants'})`);
} catch (err) {
logger.warn(`Could not stamp wasm.manifest.json: ${err.message}`);
}
diff --git a/tools/lib/engineBuild.mjs b/tools/lib/engineBuild.mjs
index 5adc68bd5..a82984004 100644
--- a/tools/lib/engineBuild.mjs
+++ b/tools/lib/engineBuild.mjs
@@ -38,32 +38,43 @@ function newestSource(root) {
}
/**
- * A sentence naming the engine source that outran the binary, or null when the
- * binary is current (or when there is none to judge — that failure speaks for
- * itself downstream).
+ * When the binary of one build VARIANT was produced, from the manifest, or null
+ * when there is nothing to date it by. Per variant, because the variants are
+ * separate builds. A schema-1 manifest's single `builtAt` is the fallback: it is
+ * honest only for whichever variant was built last.
*/
-export function staleEngineBuild(root, wasmDir) {
+function variantBuiltAt(wasmDir, variant) {
const manifest = path.join(wasmDir, 'wasm.manifest.json');
if (!existsSync(manifest)) return null;
- let builtAt;
- try {
- builtAt = Date.parse(JSON.parse(readFileSync(manifest, 'utf8')).builtAt);
- } catch { return null; }
- if (!Number.isFinite(builtAt)) return null;
+ let m;
+ try { m = JSON.parse(readFileSync(manifest, 'utf8')); } catch { return null; }
+ const own = m.variants?.[variant]?.builtAt;
+ const at = Date.parse(own ?? m.builtAt ?? '');
+ return Number.isFinite(at) ? at : null;
+}
+
+/**
+ * A sentence naming the engine source that outran the binary, or null when the
+ * binary is current (or when there is none to judge — that failure speaks for
+ * itself downstream). `variant` is the build whose age is in question.
+ */
+export function staleEngineBuild(root, wasmDir, variant = 'web') {
+ const builtAt = variantBuiltAt(wasmDir, variant);
+ if (builtAt == null) return null;
const newest = newestSource(root);
if (!newest.file || newest.at <= builtAt) return null;
const hours = Math.round((newest.at - builtAt) / 36e5);
const behind = hours >= 1 ? `${hours}h` : `${Math.round((newest.at - builtAt) / 6e4)}min`;
- return `the engine binary in ${path.relative(root, wasmDir).split(path.sep).join('/')} was built `
+ return `the ${variant} engine binary in ${path.relative(root, wasmDir).split(path.sep).join('/')} was built `
+ `${behind} before ${newest.file} was last changed — every pixel verdict below would be `
- + `about an engine this checkout does not have.\nBuild it: node build-tools/cli.js build -t web`;
+ + `about an engine this checkout does not have.\nBuild it: node build-tools/cli.js build -t ${variant}`;
}
/** Exit unless the binary is current. `--allow-stale-engine` says you meant it. */
-export function requireCurrentEngine(root, wasmDir, argv = process.argv) {
+export function requireCurrentEngine(root, wasmDir, argv = process.argv, variant = 'web') {
if (argv.includes('--allow-stale-engine')) return;
- const stale = staleEngineBuild(root, wasmDir);
+ const stale = staleEngineBuild(root, wasmDir, variant);
if (!stale) return;
console.error(`\n✗ ${stale}\n`);
process.exit(1);
diff --git a/tools/tests/engine-build.test.ts b/tools/tests/engine-build.test.ts
new file mode 100644
index 000000000..87a12231f
--- /dev/null
+++ b/tools/tests/engine-build.test.ts
@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file engine-build.test.ts — is the binary a verifier judges the one this
+ * checkout builds, per BUILD VARIANT?
+ *
+ * The variants are separate builds that share one manifest. Dating them all from
+ * the moment the manifest was written makes a `-t web` build vouch for a wechat
+ * binary of any age — and a stale one does not fail as stale: the package boots,
+ * fails its ABI handshake, and reads as the game being broken.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+// @ts-expect-error — a .mjs tool module, typed by its own JSDoc
+import { staleEngineBuild } from '../lib/engineBuild.mjs';
+
+const HOUR = 3600_000;
+let root = '';
+let wasmDir = '';
+
+/** A checkout whose newest engine source was touched at `sourceAt`. */
+function checkout(sourceAt: number) {
+ mkdirSync(path.join(root, 'src'), { recursive: true });
+ const file = path.join(root, 'src', 'renderer.cpp');
+ writeFileSync(file, '// engine\n');
+ utimesSync(file, sourceAt / 1000, sourceAt / 1000);
+}
+
+const manifest = (body: Record<string, unknown>) =>
+ writeFileSync(path.join(wasmDir, 'wasm.manifest.json'), JSON.stringify(body));
+
+beforeEach(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'engine-build-'));
+ wasmDir = path.join(root, 'build', 'wasm', 'wechat');
+ mkdirSync(wasmDir, { recursive: true });
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+describe('staleEngineBuild, per variant', () => {
+ it('dates a variant by its OWN build, not by when the manifest was written', () => {
+ const now = Date.now();
+ checkout(now - HOUR); // source changed an hour ago
+ manifest({
+ schema: 2,
+ variants: { web: { builtAt: new Date(now).toISOString() }, // built since
+ wechat: { builtAt: new Date(now - 48 * HOUR).toISOString() } }, // two days behind
+ });
+ expect(staleEngineBuild(root, wasmDir, 'web')).toBeNull();
+ const stale = staleEngineBuild(root, wasmDir, 'wechat');
+ expect(stale).toContain('wechat engine binary');
+ // The way out has to name the build that is behind — `-t web` would rebuild
+ // the one that was already current and leave the failure exactly as it was.
+ expect(stale).toContain('-t wechat');
+ });
+
+ it('is silent when the variant outlives the source', () => {
+ const now = Date.now();
+ checkout(now - 48 * HOUR);
+ manifest({ schema: 2, variants: { wechat: { builtAt: new Date(now).toISOString() } } });
+ expect(staleEngineBuild(root, wasmDir, 'wechat')).toBeNull();
+ });
+
+ // A manifest written before this was per-variant is still on disk in every
+ // working tree that has not rebuilt; reading it as "no answer" would turn the
+ // gate off silently, which is worse than the imprecision it replaces.
+ it('falls back to a schema-1 manifest single stamp', () => {
+ const now = Date.now();
+ checkout(now - HOUR);
+ manifest({ schema: 1, builtAt: new Date(now - 48 * HOUR).toISOString() });
+ expect(staleEngineBuild(root, wasmDir, 'wechat')).toContain('wechat engine binary');
+ });
+
+ it('has nothing to say without a manifest, or with an unreadable one', () => {
+ checkout(Date.now());
+ expect(staleEngineBuild(root, wasmDir, 'web')).toBeNull();
+ writeFileSync(path.join(wasmDir, 'wasm.manifest.json'), 'not json');
+ expect(staleEngineBuild(root, wasmDir, 'web')).toBeNull();
+ });
+
+ // The variant asked about is the one answered about: a manifest that knows
+ // only `web` must not date `wechat` by it.
+ it('does not answer for a variant the manifest does not carry', () => {
+ const now = Date.now();
+ checkout(now - HOUR);
+ manifest({ schema: 2, variants: { web: { builtAt: new Date(now - 48 * HOUR).toISOString() } } });
+ expect(staleEngineBuild(root, wasmDir, 'wechat')).toBeNull();
+ });
+});
diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjs
index 3c1c5c068..04fa1dcac 100644
--- a/tools/verify-golden.mjs
+++ b/tools/verify-golden.mjs
@@ -47,7 +47,16 @@ const LAUNCHER = (target) => path.join(ROOT, 'tools', 'launchers',
const COMPARABLE = OWNED;
const DESKTOP = path.join(ROOT, 'desktop');
-requireCurrentEngine(ROOT, path.join(DESKTOP, 'public', 'wasm'));
+
+/**
+ * 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
+ * does not announce itself — the package boots, fails its ABI handshake and
+ * reads as the game being broken.
+ */
+const ENGINE_OF = (target) => (target === 'wechat'
+ ? { dir: path.join(ROOT, 'build', 'wasm', 'wechat'), variant: 'wechat' }
+ : { dir: path.join(DESKTOP, 'public', 'wasm'), variant: 'web' });
if (SHOTS) mkdirSync(SHOTS, { recursive: true });
const only = ONLY ? new Set(ONLY.split(',').map((s) => s.trim())) : null;
@@ -205,6 +214,13 @@ function launchPackage(id, target, args) {
return { ...run.r, gpuDied: Boolean(run.gpuDied) };
}
+// Every engine build this tier's pairs will package, before any of them runs:
+// finding out at pair fourteen costs the thirteen packages before it.
+for (const key of new Set(pairs.map((p) => JSON.stringify(ENGINE_OF(p.target))))) {
+ const { dir, variant } = JSON.parse(key);
+ requireCurrentEngine(ROOT, dir, process.argv, variant);
+}
+
const results = [];
for (const { id, target } of pairs) {
const out = path.join(WORK, `${id}-${target}`);