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(gates): the app a runner launches is the one the assembler wrote

esengine55a4c70f578f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 81241d79f..f9f8b241c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -105,6 +105,22 @@ published separately; it ships inside the editor.
to stop a list and its checks drifting apart; it cannot be a second place the
version is written.
+- **Three release criteria could not pass on a Mac, and one of them blamed the
+ engine for it.** `verify-aot-native` and the native frame bench both located
+ the app they had just exported by searching it for "a file with no extension".
+ Every signed macOS bundle carries `Contents/_CodeSignature/CodeResources`,
+ which has that shape, and which of the two a directory walk reached first was
+ decided by directory order — so both runners launched the signature manifest.
+ The bench said the host printed no bench line; `verify-aot-native` said the
+ game had installed no module, dispatched to no compiled system and never drawn
+ a frame. All three were true of a text file.
+
+ The executable is found through `desktopExecutableIn` now — the same LAYOUT
+ table the assembler used to put it there, so there is one answer to where it
+ is rather than a search and a guess. Signing has been unconditional on darwin
+ since the desktop assembler landed, which means these criteria had never been
+ answerable on the platform they were written on.
+
- **`World.layoutEpoch()` answers on a native host.** It returned null there —
"assume everything moved" — because the epoch was reachable only as a function
on the wasm module, and a native host has no module. It is a registry binding
diff --git a/bench/aot-native/frame-bench.mjs b/bench/aot-native/frame-bench.mjs
index cec98655e..2368636e7 100644
--- a/bench/aot-native/frame-bench.mjs
+++ b/bench/aot-native/frame-bench.mjs
@@ -33,11 +33,12 @@
* BENCH_BUILDS=compiled BENCH_BYSTANDERS=95000 node bench/aot-native/frame-bench.mjs
*/
import { spawnSync } from 'node:child_process';
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { installedTemplateDir } from '../../build-tools/utils/nativeTemplate.js';
+import { desktopExecutableIn } from '../../build-tools/utils/desktopApp.js';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
/** The one source both AOT benchmarks measure. */
@@ -229,7 +230,7 @@ function exportApp(project, out, compiled) {
console.error((r.stderr || r.stdout || '').trim().slice(-1500));
process.exit(1);
}
- const exe = findExecutable(out);
+ const exe = desktopExecutableIn(out, os);
if (exe === null) {
console.error(`✗ the export assembled no app under ${out}`);
process.exit(1);
@@ -237,22 +238,6 @@ function exportApp(project, out, compiled) {
return exe;
}
-/** The assembled app's executable, wherever the assembler put it. */
-function findExecutable(dir) {
- const stack = [dir];
- while (stack.length > 0) {
- const at = stack.pop();
- for (const entry of readdirSync(at, { withFileTypes: true })) {
- const full = path.join(at, entry.name);
- if (entry.isDirectory()) { stack.push(full); continue; }
- if (process.platform === 'win32' ? entry.name.endsWith('.exe') : !path.extname(entry.name)) {
- if (!full.includes(`${path.sep}Content${path.sep}`)) return full;
- }
- }
- }
- return null;
-}
-
function run(exe, label) {
const r = spawnSync(exe, [], {
encoding: 'utf8', cwd: path.dirname(exe),
diff --git a/build-tools/utils/desktopApp.d.ts b/build-tools/utils/desktopApp.d.ts
index 73ad27c04..ff6a4e6df 100644
--- a/build-tools/utils/desktopApp.d.ts
+++ b/build-tools/utils/desktopApp.d.ts
@@ -38,3 +38,9 @@ export function assembleDesktopApp(options: {
* and every achievement silently reaches nobody. */
steamLibrary: string | null;
}>;
+
+/** The executable inside an app assembled under `dir`, or null when there is none. */
+export function desktopExecutableIn(
+ dir: string,
+ platform: 'macos' | 'windows' | 'linux',
+): string | null;
diff --git a/build-tools/utils/desktopApp.js b/build-tools/utils/desktopApp.js
index 651bff737..6f704aa60 100644
--- a/build-tools/utils/desktopApp.js
+++ b/build-tools/utils/desktopApp.js
@@ -15,7 +15,7 @@
*/
import path from 'path';
-import { existsSync } from 'fs';
+import { existsSync, readdirSync, statSync } from 'fs';
import { chmod, cp, mkdir, readdir, readFile, rm, writeFile } from 'fs/promises';
import { pngToIcns } from './icns.js';
import { setExeIcon } from './peResource.js';
@@ -34,12 +34,14 @@ const PLIST_DEFAULT_MIN = '11.0';
const LAYOUT = {
macos: {
root: (name) => `${name}.app`,
+ appName: (dir) => (dir.endsWith('.app') ? dir.slice(0, -'.app'.length) : null),
executable: (name) => path.join('Contents', 'MacOS', name),
content: path.join('Contents', 'Resources', 'Content'),
beside: path.join('Contents', 'Resources'),
},
windows: {
root: (name) => name,
+ appName: (dir) => dir,
executable: (name) => `${name}.exe`,
content: 'Content',
beside: '.',
@@ -48,6 +50,7 @@ const LAYOUT = {
// whole, with the runtime at its root.
linux: {
root: (name) => name,
+ appName: (dir) => dir,
executable: (name) => name,
content: 'Content',
beside: '.',
@@ -185,3 +188,37 @@ async function signBundle(bundle, options, nested = []) {
for (const item of nested) await sign(item);
await sign(bundle);
}
+
+
+/**
+ * The executable inside an assembled app, located through the same table that
+ * put it there.
+ *
+ * Two runners searched for it instead, by the shape "a file with no extension".
+ * Every signed macOS bundle carries `Contents/_CodeSignature/CodeResources`,
+ * which has that shape, and which of the two a directory walk reaches first is
+ * decided by directory order — so they launched the signature manifest and then
+ * reported that the engine had installed no module and drawn no frame.
+ *
+ * @param {string} dir A directory an export wrote an app into, at any depth.
+ * @param {'macos'|'windows'|'linux'} platform Whose layout to read.
+ * @returns {string|null} The executable, or null when no app is under @p dir.
+ */
+export function desktopExecutableIn(dir, platform) {
+ const layout = LAYOUT[platform];
+ if (layout === undefined) throw new Error(`no desktop layout for "${platform}"`);
+ // Breadth first over sorted names, so a nested app is still found and the
+ // answer does not depend on the order a filesystem hands entries back.
+ for (const queue = [dir]; queue.length > 0;) {
+ const at = queue.shift();
+ const name = layout.appName(path.basename(at));
+ if (name) {
+ const exe = path.join(at, layout.executable(name));
+ if (existsSync(exe) && statSync(exe).isFile()) return exe;
+ }
+ for (const entry of readdirSync(at, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+ if (entry.isDirectory()) queue.push(path.join(at, entry.name));
+ }
+ }
+ return null;
+}
diff --git a/tools/tests/desktop-executable.test.ts b/tools/tests/desktop-executable.test.ts
new file mode 100644
index 000000000..51ccea584
--- /dev/null
+++ b/tools/tests/desktop-executable.test.ts
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Which file inside an assembled app is the one you run.
+ *
+ * Two gate runners answered this by searching for "a file with no
+ * extension". Every signed macOS bundle carries
+ * `Contents/_CodeSignature/CodeResources`, which fits that shape, and
+ * directory order decided which of the two a walk reached first — so they
+ * launched the signature manifest and reported that the engine had
+ * installed no module, dispatched to nothing and never drawn a frame.
+ *
+ * The signed bundle is therefore the case that matters here: a fixture
+ * with only the executable in it would pass against the old answer too.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+// @ts-expect-error — a build-tools .js helper the CLI runs unbuilt
+import { desktopExecutableIn } from '../../build-tools/utils/desktopApp.js';
+
+let root = '';
+
+function file(...parts: string[]): string {
+ const full = path.join(root, ...parts);
+ mkdirSync(path.dirname(full), { recursive: true });
+ writeFileSync(full, '');
+ return full;
+}
+
+beforeAll(() => { root = mkdtempSync(path.join(tmpdir(), 'estella-exe-')); });
+afterAll(() => { rmSync(root, { recursive: true, force: true }); });
+
+describe('desktopExecutableIn', () => {
+ it('picks the bundle executable over a signed bundle\'s CodeResources', () => {
+ const exe = file('mac', 'Game.app', 'Contents', 'MacOS', 'Game');
+ file('mac', 'Game.app', 'Contents', '_CodeSignature', 'CodeResources');
+ file('mac', 'Game.app', 'Contents', 'Info.plist');
+ expect(desktopExecutableIn(path.join(root, 'mac'), 'macos')).toBe(exe);
+ });
+
+ it('finds an app nested under the export directory', () => {
+ const exe = file('nested', 'out', 'deep', 'Game.app', 'Contents', 'MacOS', 'Game');
+ expect(desktopExecutableIn(path.join(root, 'nested'), 'macos')).toBe(exe);
+ });
+
+ // The content directory is the GAME's files, and it is full of names with no
+ // extension once assets are cooked. It is not somewhere to look for a binary.
+ it('does not mistake cooked content for the executable', () => {
+ const exe = file('content', 'Game.app', 'Contents', 'MacOS', 'Game');
+ file('content', 'Game.app', 'Contents', 'Resources', 'Content', 'a1b2c3d4');
+ file('content', 'Game.app', 'Contents', 'Resources', 'Content', 'e5f6a7b8');
+ expect(desktopExecutableIn(path.join(root, 'content'), 'macos')).toBe(exe);
+ });
+
+ it('reads the windows and linux layouts by their own rule', () => {
+ const win = file('win', 'Game', 'Game.exe');
+ file('win', 'Game', 'Content', 'a1b2c3d4');
+ expect(desktopExecutableIn(path.join(root, 'win'), 'windows')).toBe(win);
+
+ const lin = file('lin', 'Game', 'Game');
+ file('lin', 'Game', 'Content', 'a1b2c3d4');
+ expect(desktopExecutableIn(path.join(root, 'lin'), 'linux')).toBe(lin);
+ });
+
+ // Null is a runner saying "the export assembled no app", which is a different
+ // sentence from "the app it assembled does not work".
+ it('answers null when no app was assembled', () => {
+ file('empty', 'notes.txt');
+ expect(desktopExecutableIn(path.join(root, 'empty'), 'macos')).toBeNull();
+ });
+});
diff --git a/tools/verify-aot-native.mjs b/tools/verify-aot-native.mjs
index 772f9dfd2..c8b8d2347 100644
--- a/tools/verify-aot-native.mjs
+++ b/tools/verify-aot-native.mjs
@@ -18,11 +18,12 @@
* node tools/verify-aot-native.mjs
*/
import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { installedTemplateDir } from '../build-tools/utils/nativeTemplate.js';
+import { desktopExecutableIn } from '../build-tools/utils/desktopApp.js';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
/** The example whose system carries the marker. */
@@ -60,7 +61,7 @@ try {
process.exit(1);
}
- const exe = findExecutable(out);
+ const exe = desktopExecutableIn(out, os);
if (exe === null) {
console.error(`✗ the export assembled no app under ${out}`);
process.exit(1);
@@ -100,20 +101,3 @@ try {
} finally {
rmSync(out, { recursive: true, force: true });
}
-
-/** The assembled app's executable, wherever the assembler put it. */
-function findExecutable(dir) {
- const stack = [dir];
- while (stack.length > 0) {
- const at = stack.pop();
- for (const entry of readdirSync(at, { withFileTypes: true })) {
- const full = path.join(at, entry.name);
- if (entry.isDirectory()) { stack.push(full); continue; }
- if (process.platform === 'win32' ? entry.name.endsWith('.exe') : !path.extname(entry.name)) {
- // The content dir holds no executable, so anything found is the app's.
- if (!full.includes(`${path.sep}Content${path.sep}`)) return full;
- }
- }
- }
- return null;
-}