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.

test(native): a packaged game is started on a simulator, not just assembled

esengine5954a159659c
diff --git a/.github/workflows/native-smoke.yml b/.github/workflows/native-smoke.yml
new file mode 100644
index 000000000..ca668e77d
--- /dev/null
+++ b/.github/workflows/native-smoke.yml
@@ -0,0 +1,178 @@
+name: Native smoke
+
+# Does a game packaged from the runtime templates actually start?
+#
+# `verify-template` reads what an archive carries, which is a weaker claim than it
+# sounds: v0.36.0's Android template carried a host that ran, and every game made
+# from it still opened on a black screen. This packages a real example around the
+# template the same way the editor's Package dialog does, installs it on a
+# simulator, and asks the two questions a completeness check cannot — did the boot
+# record reach "ready", and is the frame more than one flat color.
+#
+# A simulator is not a phone. Real GPU drivers, real compressed textures, thermal
+# throttling and memory pressure are all outside what this can see, and the two
+# Android rendering bugs this project has actually shipped were of that kind. What
+# this catches is the layer under them: a template that cannot produce a launching
+# app at all.
+
+on:
+ workflow_dispatch:
+ inputs:
+ template-tag:
+ description: "Release tag to take the templates from (blank = this run's own artifacts)."
+ required: false
+ type: string
+ example:
+ description: 'Example project to package.'
+ required: false
+ default: hello-world
+ type: string
+ workflow_call:
+ inputs:
+ template-tag:
+ required: false
+ type: string
+ example:
+ required: false
+ default: hello-world
+ type: string
+
+permissions:
+ contents: read
+
+jobs:
+ android:
+ name: Android emulator boot
+ runs-on: ubuntu-latest
+ timeout-minutes: 45
+ steps:
+ - uses: actions/checkout@v7
+
+ - uses: ./.github/actions/setup
+
+ - name: Take the template from the release
+ if: inputs.template-tag != ''
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ gh release download "${{ inputs.template-tag }}" --repo "$GITHUB_REPOSITORY" \
+ -p 'estella-native-android-*.zip' -D templates
+
+ - name: Take the template from this run
+ if: inputs.template-tag == ''
+ uses: actions/download-artifact@v8
+ with:
+ name: native-template-android
+ path: templates
+
+ # Under release strictness, so this never packages around an archive the
+ # publish gate would reject anyway.
+ - name: Unpack the template
+ run: |
+ node build-tools/cli.js verify-template templates/*.zip
+ mkdir -p template
+ unzip -q templates/*.zip -d template
+
+ - name: Build the SDK the game is bundled against
+ run: pnpm --filter ./sdk build
+
+ - name: Package the example as a signed APK
+ run: |
+ node desktop/scripts/export-project.mjs "examples/${{ inputs.example }}" \
+ --platform android --template template --out dist-android --json export.json
+ echo "APK=$(node -p "require('./export.json').apkFile")" >> "$GITHUB_ENV"
+
+ # Without this the emulator falls back to software CPU emulation and the
+ # boot alone outlasts the job.
+ - name: Enable KVM
+ run: |
+ echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
+ | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+ sudo udevadm control --reload-rules
+ sudo udevadm trigger --name-match=kvm
+
+ # The host is Dawn on Vulkan (the manifest requires it), which on a runner
+ # with no GPU means the emulator's bundled SwiftShader Vulkan.
+ - name: Boot it on an emulator
+ uses: reactivecircus/android-emulator-runner@v2
+ with:
+ api-level: 34
+ target: google_apis
+ arch: x86_64
+ emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none -camera-front none
+ script: node tools/verify-native-boot.mjs --platform android --apk "$APK"
+
+ - name: Keep the frame and the record
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: android-boot-${{ inputs.example }}
+ path: build/native-boot
+ if-no-files-found: warn
+
+ ios:
+ name: iOS simulator boot
+ runs-on: macos-latest
+ timeout-minutes: 45
+ steps:
+ - uses: actions/checkout@v7
+
+ - uses: ./.github/actions/setup
+
+ - name: Take the template from the release
+ if: inputs.template-tag != ''
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ gh release download "${{ inputs.template-tag }}" --repo "$GITHUB_REPOSITORY" \
+ -p 'estella-native-ios-*.zip' -D templates
+
+ - name: Take the template from this run
+ if: inputs.template-tag == ''
+ uses: actions/download-artifact@v8
+ with:
+ name: native-template-ios
+ path: templates
+
+ - name: Unpack the template
+ run: |
+ node build-tools/cli.js verify-template templates/*.zip
+ mkdir -p template
+ unzip -q templates/*.zip -d template
+
+ - name: Build the SDK the game is bundled against
+ run: pnpm --filter ./sdk build
+
+ - name: Write the Xcode project around the example
+ run: |
+ node desktop/scripts/export-project.mjs "examples/${{ inputs.example }}" \
+ --platform ios --template template --out dist-ios --json export.json
+ project=$(node -p "require('./export.json').xcodeProject")
+ if [ "$project" = "undefined" ]; then
+ echo "::error::the iOS export wrote no Xcode project — see the warnings above"
+ exit 1
+ fi
+ echo "XCODEPROJ=$project" >> "$GITHUB_ENV"
+ echo "SCHEME=$(basename "$project" .xcodeproj)" >> "$GITHUB_ENV"
+
+ # Simulator slices need no signing identity, which is the whole reason this
+ # can run on a hosted runner at all.
+ - name: Build it for the simulator
+ run: |
+ xcodebuild -project "$XCODEPROJ" -scheme "$SCHEME" -configuration Release \
+ -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
+ -derivedDataPath dd CODE_SIGNING_ALLOWED=NO build
+ app=$(find dd/Build/Products -maxdepth 2 -name '*.app' | head -1)
+ test -n "$app" || { echo "::error::xcodebuild produced no .app"; exit 1; }
+ echo "APP=$app" >> "$GITHUB_ENV"
+
+ - name: Boot it on a simulator
+ run: node tools/verify-native-boot.mjs --platform ios --app "$APP"
+
+ - name: Keep the frame and the record
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: ios-boot-${{ inputs.example }}
+ path: build/native-boot
+ if-no-files-found: warn
diff --git a/build-tools/utils/png.js b/build-tools/utils/png.js
new file mode 100644
index 000000000..ba4ec442d
--- /dev/null
+++ b/build-tools/utils/png.js
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// Read a PNG, for the one question a screenshot has to answer.
+//
+// A frame captured off a simulator is judged by whether anything was drawn into
+// it, which needs pixels — and the encoders this repo already writes rather than
+// depends on (solidPng.mjs, zip.js) set the precedent for the other direction.
+// The alternative is reaching into desktop/node_modules for pngjs from a tool
+// that has no other reason to know the editor exists.
+//
+// Scope is what a screen capture produces: 8 bits per channel, non-interlaced.
+// Anything else throws by name rather than decoding to garbage.
+
+import { inflateSync } from 'zlib';
+
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+/**
+ * Decode a PNG to interleaved 8-bit samples.
+ *
+ * @param {Buffer} buf
+ * @returns {{width: number, height: number, channels: number, data: Buffer}}
+ */
+export function decodePng(buf) {
+ if (buf.length < 8 || buf.readUInt32BE(0) !== 0x89504e47) throw new Error('not a PNG');
+
+ let width = 0; let height = 0; let depth = 0; let colorType = 0; let interlace = 0;
+ const idat = [];
+ for (let at = 8; at + 8 <= buf.length;) {
+ const len = buf.readUInt32BE(at);
+ const type = buf.toString('ascii', at + 4, at + 8);
+ const body = buf.subarray(at + 8, at + 8 + len);
+ if (type === 'IHDR') {
+ width = body.readUInt32BE(0);
+ height = body.readUInt32BE(4);
+ depth = body[8];
+ colorType = body[9];
+ interlace = body[12];
+ } else if (type === 'IDAT') {
+ idat.push(body);
+ } else if (type === 'IEND') {
+ break;
+ }
+ at += 12 + len;
+ }
+
+ if (depth !== 8) throw new Error(`PNG bit depth ${depth} — this decoder reads 8`);
+ if (interlace !== 0) throw new Error('interlaced PNG — this decoder reads non-interlaced');
+ const channels = CHANNELS[colorType];
+ if (!channels || colorType === 3) throw new Error(`PNG color type ${colorType} is not supported`);
+ if (!width || !height || idat.length === 0) throw new Error('PNG carries no image data');
+
+ const raw = inflateSync(Buffer.concat(idat));
+ const stride = width * channels;
+ const out = Buffer.alloc(stride * height);
+
+ // Undo the per-scanline filter. `prev` is the already-reconstructed line
+ // above, which is what makes this sequential rather than parallel.
+ for (let y = 0; y < height; y++) {
+ const filter = raw[y * (stride + 1)];
+ const src = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+ const line = out.subarray(y * stride, (y + 1) * stride);
+ const prev = y > 0 ? out.subarray((y - 1) * stride, y * stride) : null;
+ for (let x = 0; x < stride; x++) {
+ const a = x >= channels ? line[x - channels] : 0;
+ const b = prev ? prev[x] : 0;
+ const c = prev && x >= channels ? prev[x - channels] : 0;
+ let value = src[x];
+ if (filter === 1) value += a;
+ else if (filter === 2) value += b;
+ else if (filter === 3) value += (a + b) >> 1;
+ else if (filter === 4) {
+ const p = a + b - c;
+ const pa = Math.abs(p - a); const pb = Math.abs(p - b); const pc = Math.abs(p - c);
+ value += (pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c);
+ } else if (filter !== 0) {
+ throw new Error(`unknown PNG scanline filter ${filter}`);
+ }
+ line[x] = value & 0xff;
+ }
+ }
+
+ return { width, height, channels, data: out };
+}
+
+/**
+ * How many distinct colors a frame holds, counted up to @p cap.
+ *
+ * The question a captured frame is asked is "was anything drawn", and a clear
+ * that never got a scene is one flat color — which is the failure a launch that
+ * merely did not crash still hides.
+ */
+export function distinctColors(image, cap = 4096) {
+ const { data, channels } = image;
+ const seen = new Set();
+ for (let i = 0; i + channels <= data.length; i += channels) {
+ const r = data[i];
+ const g = channels >= 3 ? data[i + 1] : r;
+ const b = channels >= 3 ? data[i + 2] : r;
+ seen.add((r << 16) | (g << 8) | b);
+ if (seen.size >= cap) break;
+ }
+ return seen.size;
+}
diff --git a/desktop/scripts/export-project.mjs b/desktop/scripts/export-project.mjs
index 56b96fd71..33fd901e4 100644
--- a/desktop/scripts/export-project.mjs
+++ b/desktop/scripts/export-project.mjs
@@ -16,14 +16,16 @@
// --scene <path> entry scene, project-relative (default: the project's own)
// --title <name> app title (default: the project's name)
// --scripts <path> scripts entry, project-relative (default src/main.ts if present)
+// --template <dir> android/ios: the runtime template to wrap, else the installed one
+// --json <file> also write the result here, for a caller that reads it back
//
// Prints the export result as JSON — errors and warnings included, so a caller can
// tell a clean package from one that silently dropped half a scene.
import path from 'node:path';
-import { existsSync, readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { createRequire } from 'node:module';
-import { installedTemplateDir } from '../../build-tools/utils/nativeTemplate.js';
+import { installedTemplateDir, iosTemplateSources } from '../../build-tools/utils/nativeTemplate.js';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const DESKTOP = path.join(HERE, '..');
@@ -139,10 +141,11 @@ const outDir = path.resolve(opts.out ?? path.join(opts.projectDir, `dist-${platf
// explicitly with --template, else looked up the way the editor does, so a headless
// export assembles the same package the dialog would rather than content alone.
const engineVersion = JSON.parse(readFileSync(path.join(DESKTOP, 'package.json'), 'utf8')).version;
-const androidTemplate = platform === 'android'
+const nativePlatform = platform === 'android' || platform === 'ios';
+const templateDir = nativePlatform
? (opts.template
? path.resolve(opts.template)
- : firstExisting([installedTemplateDir(engineVersion, 'android')]) ?? null)
+ : firstExisting([installedTemplateDir(engineVersion, platform)]) ?? null)
: null;
const { resolveOrientation } = await loadProjectFormat();
const { exportGame, cleanup } = await loadExportGame();
@@ -159,10 +162,15 @@ try {
platform,
title: opts.title ?? project.name ?? path.basename(opts.projectDir),
orientation: resolveOrientation(project),
- androidTemplate,
+ androidTemplate: platform === 'android' ? templateDir : null,
+ iosSources: platform === 'ios' && templateDir ? iosTemplateSources(templateDir) : null,
androidOutput: opts.output === 'project' ? 'project' : undefined,
});
- console.log(JSON.stringify({ ...result, outDir }, null, 2));
+ const report = { ...result, outDir };
+ console.log(JSON.stringify(report, null, 2));
+ // stdout carries the cook's own progress too, so a caller that wants the
+ // result mechanically cannot just redirect it.
+ if (opts.json) writeFileSync(path.resolve(opts.json), `${JSON.stringify(report, null, 2)}\n`);
code = result.ok ? 0 : 1;
} finally {
// Before the exit, not after: process.exit() in the try block would skip this
diff --git a/tools/verify-native-boot.mjs b/tools/verify-native-boot.mjs
new file mode 100644
index 000000000..9c1bb3cf1
--- /dev/null
+++ b/tools/verify-native-boot.mjs
@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file verify-native-boot.mjs — a packaged game starts, and draws.
+ *
+ * `verify-template` proves an archive carries its files. That is a weaker claim
+ * than it sounds: v0.36.0's Android template carried a host that ran, and every
+ * game made from it still opened on a black screen. Between "the zip is complete"
+ * and "a player sees the game" sit the two failures nobody was checking — a
+ * launch that dies, and a launch that survives showing nothing.
+ *
+ * So the app is installed on a simulator, started, and asked two questions:
+ *
+ * 1. did the boot record reach `ready in` — the line the host writes only once
+ * the first frame is up, so its absence is where the launch stopped;
+ * 2. is the frame more than one flat color — because a launch that reports
+ * ready and clears to black is exactly the bug that shipped.
+ *
+ * The record is read from the FILE rather than the platform log on purpose:
+ * `bootPhase`/`bootReady` write to the file only (BootLog.cpp), so grepping
+ * logcat for "ready" finds nothing and calls a dead app healthy.
+ *
+ * node tools/verify-native-boot.mjs --platform android --apk <file>
+ * node tools/verify-native-boot.mjs --platform ios --app <bundle.app>
+ *
+ * Absent a device this FAILS rather than skipping, because its whole reason to
+ * exist is to be a gate. `--allow-skip` is for running it on a machine that may
+ * not have a simulator, and says so in the output when it takes that door.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { decodePng, distinctColors } from '../build-tools/utils/png.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const APP_ID = 'com.estella.game';
+const LOG_NAME = 'estella-boot.log';
+const READY = 'ready in';
+
+function parseArgs(argv) {
+ const opts = { platform: 'android', timeout: 120, minColors: 8, out: path.join(ROOT, 'build', 'native-boot') };
+ for (let i = 0; i < argv.length; i++) {
+ const key = argv[i].replace(/^--/, '');
+ if (key === 'allow-skip') { opts.allowSkip = true; continue; }
+ opts[key.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = argv[++i];
+ }
+ opts.timeout = Number(opts.timeout);
+ opts.minColors = Number(opts.minColors);
+ return opts;
+}
+
+const sh = (cmd, args, o = {}) => execFileSync(cmd, args, { encoding: 'utf8', ...o });
+const trySh = (cmd, args) => spawnSync(cmd, args, { encoding: 'utf8' });
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+
+// =============================================================================
+// Android — adb against whatever emulator or phone is attached
+// =============================================================================
+
+function androidDriver(opts) {
+ const adb = process.env.ANDROID_HOME
+ ? path.join(process.env.ANDROID_HOME, 'platform-tools', 'adb') : 'adb';
+ const shell = (...a) => sh(adb, ['shell', ...a]);
+ const logFile = `/sdcard/Android/data/${APP_ID}/files/${LOG_NAME}`;
+
+ return {
+ name: 'android',
+ available() {
+ const probe = trySh(adb, ['devices']);
+ if (probe.status !== 0) return null;
+ const devices = probe.stdout.split('\n').slice(1)
+ .filter((l) => /\tdevice$/.test(l.trim()));
+ return devices.length ? devices[0].split('\t')[0] : null;
+ },
+ install(apk) {
+ trySh(adb, ['uninstall', APP_ID]);
+ sh(adb, ['install', '-r', '-t', apk], { stdio: 'inherit' });
+ // A record left by an earlier run would answer for this one.
+ trySh(adb, ['shell', 'rm', '-f', logFile]);
+ trySh(adb, ['logcat', '-c']);
+ },
+ launch() {
+ sh(adb, ['shell', 'am', 'start', '-W', '-n', `${APP_ID}/android.app.NativeActivity`],
+ { stdio: 'inherit' });
+ },
+ readLog() {
+ const got = trySh(adb, ['shell', 'cat', logFile]);
+ return got.status === 0 ? got.stdout : '';
+ },
+ screenshot() {
+ return execFileSync(adb, ['exec-out', 'screencap', '-p'], { maxBuffer: 64 * 1024 * 1024 });
+ },
+ diagnostics() {
+ return [
+ ['logcat (EstellaSDK)', trySh(adb, ['logcat', '-d', '-s', 'EstellaSDK:*']).stdout],
+ ['logcat (crashes)', trySh(adb, ['logcat', '-d', '-b', 'crash']).stdout],
+ ];
+ },
+ };
+}
+
+// =============================================================================
+// iOS — simctl against a booted simulator
+// =============================================================================
+
+function iosDriver(opts) {
+ let udid = null;
+ const simctl = (...a) => sh('xcrun', ['simctl', ...a]);
+
+ return {
+ name: 'ios',
+ available() {
+ if (process.platform !== 'darwin') return null;
+ const probe = trySh('xcrun', ['simctl', 'list', 'devices', 'available', '--json']);
+ if (probe.status !== 0) return null;
+ const all = Object.values(JSON.parse(probe.stdout).devices).flat();
+ const want = opts.device
+ ? all.find((d) => d.name === opts.device)
+ : all.find((d) => d.state === 'Booted' && /iPhone/.test(d.name))
+ ?? all.find((d) => /iPhone/.test(d.name));
+ if (!want) return null;
+ udid = want.udid;
+ if (want.state !== 'Booted') {
+ simctl('boot', udid);
+ sh('xcrun', ['simctl', 'bootstatus', udid, '-b']);
+ }
+ return `${want.name} (${udid})`;
+ },
+ install(app) {
+ trySh('xcrun', ['simctl', 'terminate', udid, APP_ID]);
+ trySh('xcrun', ['simctl', 'uninstall', udid, APP_ID]);
+ simctl('install', udid, app);
+ },
+ launch() {
+ simctl('launch', udid, APP_ID);
+ },
+ readLog() {
+ const container = trySh('xcrun', ['simctl', 'get_app_container', udid, APP_ID, 'data']);
+ if (container.status !== 0) return '';
+ const file = path.join(container.stdout.trim(), 'Documents', LOG_NAME);
+ if (!existsSync(file)) return '';
+ return sh('cat', [file]);
+ },
+ screenshot() {
+ const shot = path.join(opts.out, 'raw.png');
+ simctl('io', udid, 'screenshot', shot);
+ return sh('cat', [shot], { encoding: 'buffer' });
+ },
+ diagnostics() {
+ const crash = trySh('xcrun', ['simctl', 'spawn', udid, 'log', 'show',
+ '--last', '3m', '--predicate', 'senderImagePath CONTAINS "Estella"']);
+ return [['simulator log', crash.stdout]];
+ },
+ };
+}
+
+// =============================================================================
+
+const opts = parseArgs(process.argv.slice(2));
+const driver = opts.platform === 'ios' ? iosDriver(opts) : androidDriver(opts);
+const artifact = opts.platform === 'ios' ? opts.app : opts.apk;
+
+if (!artifact || !existsSync(artifact)) {
+ console.error(`✗ no ${opts.platform} app to verify (pass --${opts.platform === 'ios' ? 'app' : 'apk'} <path>)`);
+ process.exit(2);
+}
+mkdirSync(opts.out, { recursive: true });
+
+const device = driver.available();
+if (!device) {
+ const what = `no ${driver.name} device or simulator is available`;
+ if (opts.allowSkip) {
+ console.log(`— skipped: ${what} (nothing was checked)`);
+ process.exit(0);
+ }
+ console.error(`✗ ${what}. This check is a gate; pass --allow-skip to run it where one may be absent.`);
+ process.exit(1);
+}
+
+console.log(`device: ${device}`);
+console.log(`app: ${artifact}`);
+driver.install(artifact);
+driver.launch();
+
+let log = '';
+const deadline = Date.now() + opts.timeout * 1000;
+while (Date.now() < deadline) {
+ log = driver.readLog();
+ if (log.includes(READY)) break;
+ await sleep(2000);
+}
+
+const frame = driver.screenshot();
+const shotPath = path.join(opts.out, `${driver.name}-frame.png`);
+writeFileSync(shotPath, frame);
+writeFileSync(path.join(opts.out, `${driver.name}-boot.log`), log);
+
+const image = decodePng(frame);
+const colors = distinctColors(image);
+const ready = log.includes(READY);
+const drew = colors >= opts.minColors;
+
+console.log(`\nboot record: ${ready ? log.trim().split('\n').filter((l) => l.includes(READY))[0] : 'never reached "ready in"'}`);
+console.log(`frame: ${image.width}x${image.height}, ${colors} distinct colors (need ${opts.minColors})`);
+console.log(`written: ${shotPath}`);
+
+if (ready && drew) {
+ console.log(`\n✓ ${driver.name}: the packaged game started and drew a frame`);
+ process.exit(0);
+}
+
+console.error(`\n✗ ${driver.name}: ${!ready ? 'the launch never reported ready' : 'the launch reported ready but the frame is blank'}`);
+console.error('\n--- boot record ---');
+console.error(log.trim() || '(empty — the app wrote no record at all)');
+for (const [title, text] of driver.diagnostics()) {
+ if (!text?.trim()) continue;
+ console.error(`\n--- ${title} ---`);
+ console.error(text.trim().split('\n').slice(-60).join('\n'));
+}
+process.exit(1);