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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.ymlnew file mode 100644index 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: warndiff --git a/build-tools/utils/png.js b/build-tools/utils/png.jsnew file mode 100644index 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.mjsindex 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 thisdiff --git a/tools/verify-native-boot.mjs b/tools/verify-native-boot.mjsnew file mode 100644index 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);