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
feat(ci): the desktop templates are built, published and judged on pixels
esengine072cbe0ba2ea
diff --git a/.github/workflows/native-deps-cache.yml b/.github/workflows/native-deps-cache.ymlindex a16bd40f0..6427d6083 100644--- a/.github/workflows/native-deps-cache.yml+++ b/.github/workflows/native-deps-cache.yml@@ -59,6 +59,10 @@ jobs:os: ubuntu-latest- target: iosos: macos-latest+ - target: macos+ os: macos-latest+ - target: windows+ os: windows-lateststeps:# No submodules: Dawn and QuickJS are fetched into build/native-deps by# --fetch-deps, and third_party is the HOST's dependency, which this never@@ -67,11 +71,12 @@ jobs:- uses: ./.github/actions/setup+ # ONE cache key, computed where the pins are read: SDL is a desktop-only+ # dependency, so keying every target on it would cold-build Dawn for Android+ # and iOS — 16 minutes each — every time SDL moves.- name: Read the native dependency pinsid: pins- run: |- node -e "const p=require('./toolchain.manifest.json').native;\- console.log('dawn='+p.dawn.commit);console.log('quickjs='+p.quickjs.commit)" >> "$GITHUB_OUTPUT"+ run: node build-tools/cli.js native --deps-cache-key ${{ matrix.target }} >> "$GITHUB_OUTPUT"# restore, not the combined action: a hit must end this job rather than# trigger a save of what it just downloaded.@@ -81,7 +86,7 @@ jobs:uses: actions/cache/restore@v4with:path: build/native-deps- key: native-deps-${{ matrix.target }}-${{ steps.pins.outputs.dawn }}-${{ steps.pins.outputs.quickjs }}+ key: ${{ steps.pins.outputs.key }}- name: Report what the restore foundrun: |@@ -101,9 +106,19 @@ jobs:# Dawn builds with Ninja and a macOS runner has neither it nor CMake; the# Android SDK carries its own pair.- name: Set up CMake + Ninja- if: matrix.target == 'ios' && steps.restore.outputs.cache-hit != 'true'+ if: startsWith(matrix.os, 'macos') && steps.restore.outputs.cache-hit != 'true'run: brew install cmake ninja+ - name: Set up Ninja (Windows)+ if: matrix.target == 'windows' && steps.restore.outputs.cache-hit != 'true'+ uses: seanmiddleditch/gha-setup-ninja@v6++ # Ninja invokes the compiler directly, so cl.exe and the Windows SDK have to+ # be on PATH — a Developer Command Prompt's environment, without the prompt.+ - name: Set up MSVC+ if: matrix.target == 'windows' && steps.restore.outputs.cache-hit != 'true'+ uses: ilammy/msvc-dev-cmd@v1+- name: Fetch Dawn + QuickJS at their pinned commitsif: steps.restore.outputs.cache-hit != 'true'run: node build-tools/cli.js native --fetch-deps@@ -122,4 +137,4 @@ jobs:uses: actions/cache/save@v4with:path: build/native-deps- key: native-deps-${{ matrix.target }}-${{ steps.pins.outputs.dawn }}-${{ steps.pins.outputs.quickjs }}+ key: ${{ steps.pins.outputs.key }}diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.ymlindex 4295a3990..f4f7f5e30 100644--- a/.github/workflows/release-desktop.yml+++ b/.github/workflows/release-desktop.yml@@ -119,6 +119,10 @@ jobs:os: macos-latest- name: androidos: ubuntu-latest+ - name: macos+ os: macos-latest+ - name: windows+ os: windows-latestruns-on: ${{ matrix.os }}timeout-minutes: 120steps:@@ -139,9 +143,7 @@ jobs:- name: Read the native dependency pinsid: pinsshell: bash- run: |- node -e "const p=require('./toolchain.manifest.json').native;\- console.log('dawn='+p.dawn.commit);console.log('quickjs='+p.quickjs.commit)" >> "$GITHUB_OUTPUT"+ run: node build-tools/cli.js native --deps-cache-key ${{ matrix.name }} >> "$GITHUB_OUTPUT"# Keyed on the pins and the target: the checkout and the Dawn builds are# reproducible for a given commit, so this is warm on every release that@@ -150,14 +152,24 @@ jobs:uses: actions/cache@v4with:path: build/native-deps- key: native-deps-${{ matrix.name }}-${{ steps.pins.outputs.dawn }}-${{ steps.pins.outputs.quickjs }}+ key: ${{ steps.pins.outputs.key }}# Dawn and the host both build with Ninja; neither tool is guaranteed on a# macOS runner (the Android SDK carries its own pair).- name: Set up CMake + Ninja- if: matrix.name == 'ios'+ if: startsWith(matrix.os, 'macos')run: brew install cmake ninja+ - name: Set up Ninja (Windows)+ if: matrix.name == 'windows'+ uses: seanmiddleditch/gha-setup-ninja@v6++ # Ninja invokes the compiler directly, so cl.exe and the Windows SDK have to+ # be on PATH — a Developer Command Prompt's environment, without the prompt.+ - name: Set up MSVC+ if: matrix.name == 'windows'+ uses: ilammy/msvc-dev-cmd@v1+- name: Set up the Android NDKif: matrix.name == 'android'uses: nttld/setup-ndk@v1@@ -187,6 +199,21 @@ jobs:node build-tools/cli.js native --abi arm64-v8anode build-tools/cli.js native --abi x86_64 --template-out artifacts+ # One executable per OS, and no Steamworks SDK on it: the redistributable is+ # licensed to partners, so it reaches a package from the developer's own SDK+ # (Project Settings -> Packaging -> Steamworks SDK), never from here.+ - name: Build the desktop template+ if: matrix.name == 'macos' || matrix.name == 'windows'+ run: node build-tools/cli.js native --target ${{ matrix.name }} --template-out artifacts++ # The claim a template archive cannot make: that a game packaged from it+ # DRAWS. These two runners are the platforms themselves, so the pixel judge+ # the web target has always had finally reaches the native runtime — no+ # simulator, no device (docs/REARCH_STEAM.md 6.2).+ - name: A game packaged from it renders+ if: matrix.name == 'macos' || matrix.name == 'windows'+ run: node tools/verify-desktop-render.mjs --examples hello-world,particle-demo+- name: Upload template artifactuses: actions/upload-artifact@v7with:diff --git a/build-tools/cli.js b/build-tools/cli.jsindex f8496f418..114bc8793 100644--- a/build-tools/cli.js+++ b/build-tools/cli.js@@ -188,6 +188,7 @@ program.option('--template-only', 'Emit the runtime template from an existing build, without rebuilding', false).option('--template-out <dir>', 'Also write the distributable template archive here (for a release)').option('--template-index <dir>', 'Write native-templates.json describing the archives in this dir, then stop')+ .option('--deps-cache-key <target>', 'Print `key=<cache key>` for a target\'s prebuilt dependencies, then stop (CI)').option('-v, --verbose', 'Verbose output', false).action(async (options) => {logger.setVerbose(options.verbose);@@ -200,6 +201,7 @@ programtemplateOnly: options.templateOnly,templateOut: options.templateOut,templateIndex: options.templateIndex,+ depsCacheKey: options.depsCacheKey,dawn: options.dawn,dawnBuild: options.dawnBuild,quickjs: options.quickjs,diff --git a/build-tools/tasks/native.js b/build-tools/tasks/native.jsindex ef14b48f5..446dc9f5a 100644--- a/build-tools/tasks/native.js+++ b/build-tools/tasks/native.js@@ -18,7 +18,7 @@ import { requireSdk, requireNdk, sdkCmake } from '../utils/android.js';import { emitNativeTemplate, writeTemplateIndex, readEngineVersion } from './nativeTemplateEmit.js';import {fetchNativeDeps, pinnedDep, ensureDawnBuild, ensureSdlBuild, dawnLibrary,- isDesktopTarget, DAWN_TARGETS, MACOS_MIN,+ isDesktopTarget, depsCacheKey, DAWN_TARGETS, MACOS_MIN,} from './nativeDeps.js';import {ANDROID_ABIS, BYTECODE_FILE, findTemplate, iosTemplateSources, templateStoreDir,@@ -829,6 +829,12 @@ async function buildNativeDeps(options) {}export async function buildNative(options = {}) {+ // Before anything that needs a toolchain: this only reads the manifest, and CI+ // asks for it on a runner that has not set one up yet.+ if (options.depsCacheKey) {+ process.stdout.write(`key=${depsCacheKey(options.depsCacheKey)}\n`);+ return undefined;+ }if (options.fetchDeps) return fetchNativeDeps(options);if (options.buildDeps) return buildNativeDeps(options);if (options.templateIndex) {diff --git a/build-tools/tasks/nativeDeps.d.ts b/build-tools/tasks/nativeDeps.d.tsnew file mode 100644index 000000000..c7c9119b8--- /dev/null+++ b/build-tools/tasks/nativeDeps.d.ts@@ -0,0 +1,36 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+//+// Types for nativeDeps.js, which is plain ESM so the CLI runs it unbuilt.++/** One pinned dependency, as toolchain.manifest.json carries it. */+export interface NativePin {+ repo: string;+ commit: string;+}++export interface NativePins {+ dawn: NativePin;+ quickjs: NativePin;+ sdl?: NativePin;+}++export function nativeDepsDir(rootDir?: string): string;+export function nativePins(rootDir?: string): NativePins;++/** Whether a target's window and gamepads come from SDL rather than the OS's own+ * app framework — which is also what decides whether SDL keys its cache. */+export function isDesktopTarget(target: string): boolean;++/** The cache key for a target's prebuilt dependencies: every pin that build+ * consumes, and only those. */+export function depsCacheKey(target: string, rootDir?: string): string;++export function pinnedDep(name: string, rootDir?: string): string | null;+export function fetchNativeDeps(options?: Record<string, unknown>): Promise<void>;+export function ensureSdlBuild(options: Record<string, unknown>): Promise<string>;+export function ensureDawnBuild(options: Record<string, unknown>): Promise<string>;+export function dawnLibrary(dawnBuild: string, target: string): string;+export function dawnBuildDir(dawn: string, target: string, abi?: string): string;+export const DAWN_TARGETS: Record<string, unknown>;+export const MACOS_MIN: string;diff --git a/build-tools/tasks/nativeDeps.js b/build-tools/tasks/nativeDeps.jsindex 1f7cc3c21..687569edc 100644--- a/build-tools/tasks/nativeDeps.js+++ b/build-tools/tasks/nativeDeps.js@@ -36,6 +36,19 @@ export function isDesktopTarget(target) {return target === 'macos' || target === 'windows';}+/**+ * The cache key for a target's prebuilt dependencies: every pin that build+ * consumes, and only those. A key that forgets one serves a stale build under a+ * name saying it is current; SDL is desktop-only, so keying the phones on it+ * would rebuild Dawn whenever SDL moves.+ */+export function depsCacheKey(target, rootDir = config.paths.root) {+ const pins = nativePins(rootDir);+ const parts = [pins.dawn.commit, pins.quickjs.commit];+ if (isDesktopTarget(target)) parts.push(pins.sdl?.commit ?? 'no-sdl-pin');+ return `native-deps-${target}-${parts.join('-')}`;+}+/*** Check `repo` out at `commit` in `dir`, fetching only that commit.*diff --git a/desktop/tests/native-deps-cache.test.ts b/desktop/tests/native-deps-cache.test.tsnew file mode 100644index 000000000..68c053421--- /dev/null+++ b/desktop/tests/native-deps-cache.test.ts@@ -0,0 +1,40 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The key CI stores prebuilt native dependencies under.+ *+ * Its failure mode is the quiet one: a key that omits a pin the build consumes+ * serves a stale Dawn or a stale SDL under a name that says it is current, and+ * the release ships whatever that was. So the key is derived from the manifest+ * rather than spelled out per workflow, and what it must contain is pinned here.+ */+import { describe, it, expect } from 'vitest';+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { depsCacheKey } from '../../build-tools/tasks/nativeDeps.js';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');+const pins = JSON.parse(readFileSync(path.join(ROOT, 'toolchain.manifest.json'), 'utf8')).native;++describe('the native dependency cache key', () => {+ it('carries every pin the target actually builds', () => {+ const windows = depsCacheKey('windows');+ expect(windows).toContain(pins.dawn.commit);+ expect(windows).toContain(pins.quickjs.commit);+ expect(windows).toContain(pins.sdl.commit);+ });++ it('leaves SDL out of the phones, whose hosts never link it', () => {+ // Including it would cold-build Dawn for Android and iOS — a quarter hour+ // each — every time a desktop-only dependency moves.+ for (const target of ['android', 'ios']) {+ expect(depsCacheKey(target)).not.toContain(pins.sdl.commit);+ }+ });++ it('never lets two targets share one entry', () => {+ const keys = ['android', 'ios', 'macos', 'windows'].map((t) => depsCacheKey(t));+ expect(new Set(keys).size).toBe(keys.length);+ });+});diff --git a/tools/verify-desktop-render.mjs b/tools/verify-desktop-render.mjsnew file mode 100644index 000000000..30b29af81--- /dev/null+++ b/tools/verify-desktop-render.mjs@@ -0,0 +1,135 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file verify-desktop-render.mjs — a game packaged from the desktop template draws.+ *+ * `verify-template` proves an archive holds its files, which v0.36.0's Android+ * template also did while every game made from it opened on a black screen. The+ * native runtime could only ever be judged on a simulator or a phone — where an+ * OS dialog over the frame once made a dead app look healthy — because no runner+ * was the platform. The desktop runners ARE: this packages a real project the way+ * the editor's Package dialog does, runs the assembled app, and reads the frame it+ * put on the swapchain.+ *+ * The verdict is the host's own (native/host/Shot.cpp), which computes it exactly+ * as the web render checks do. Nothing here re-decides what "drew" means — a+ * second threshold would be a second answer to one question.+ *+ * node tools/verify-desktop-render.mjs --examples hello-world,particle-demo+ * node tools/verify-desktop-render.mjs --project examples/hello-world+ *+ * A missing template FAILS rather than skipping: this exists to gate a release,+ * and the release is the run that builds the template it is given.+ */+import { execFileSync, spawnSync } from 'node:child_process';+import { existsSync, mkdirSync, mkdtempSync, readFileSync, 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';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const HOST_OS = process.platform === 'darwin' ? 'macos' : process.platform === 'win32' ? 'windows' : 'linux';++/** The frame the shot is taken on. Late enough that the first scene has loaded+ * and its assets are resident; early enough that a hang is still a red run. */+const SHOT_FRAME = 60;++function parseArgs(argv) {+ const opts = { examples: 'hello-world' };+ for (let i = 0; i < argv.length; i += 2) {+ const key = argv[i]?.replace(/^--/, '');+ if (key && argv[i + 1] !== undefined) opts[key] = argv[i + 1];+ }+ return opts;+}++/** The verdict line the host logs, parsed. Null when it never got that far. */+function verdictIn(output) {+ const at = output.lastIndexOf('shot verdict:');+ if (at < 0) return null;+ const brace = output.indexOf('{', at);+ const end = output.indexOf('}', brace);+ if (brace < 0 || end < 0) return null;+ try {+ return JSON.parse(output.slice(brace, end + 1));+ } catch {+ return null;+ }+}++function packageAndRun(project, templateDir, work) {+ const out = path.join(work, path.basename(project));+ mkdirSync(out, { recursive: true });+ execFileSync(process.execPath, [+ path.join(ROOT, 'desktop', 'scripts', 'export-project.mjs'), project,+ '--platform', 'desktop', '--out', out, '--template', templateDir,+ ], { cwd: ROOT, stdio: 'inherit' });++ const name = JSON.parse(readFileSync(path.join(out, 'app.config.json'), 'utf8')).name;+ const exe = HOST_OS === 'macos'+ ? path.join(out, `${name}.app`, 'Contents', 'MacOS', name)+ : path.join(out, name, `${name}.exe`);+ if (!existsSync(exe)) throw new Error(`no assembled app at ${exe}`);++ // From a directory that is NOT the app's: a player's launcher does the same,+ // and anything the host resolves relative to the working directory rather than+ // to itself passes here and fails on their machine.+ const run = spawnSync(exe, [], {+ cwd: ROOT,+ env: { ...process.env, ESTELLA_SHOT: path.join(out, 'frame.raw'), ESTELLA_SHOT_FRAME: String(SHOT_FRAME), ESTELLA_SHOT_QUIT: '1' },+ encoding: 'utf8',+ timeout: 120_000,+ });+ return { verdict: verdictIn(`${run.stdout ?? ''}${run.stderr ?? ''}`), status: run.status, output: `${run.stdout ?? ''}${run.stderr ?? ''}` };+}++const opts = parseArgs(process.argv.slice(2));+const templateDir = opts.template ?? installedTemplateDir(+ JSON.parse(readFileSync(path.join(ROOT, 'desktop', 'package.json'), 'utf8')).version, HOST_OS);+if (!templateDir || !existsSync(templateDir)) {+ console.error(`verify-desktop-render: no ${HOST_OS} runtime template installed — build one with `+ + `\`node build-tools/cli.js native --target ${HOST_OS}\`.`);+ process.exit(1);+}++const projects = opts.project+ ? [path.resolve(opts.project)]+ : opts.examples.split(',').map((n) => path.join(ROOT, 'examples', n.trim()));++const work = mkdtempSync(path.join(tmpdir(), 'estella-desktop-render-'));+let failed = 0;+try {+ for (const project of projects) {+ const label = path.basename(project);+ let result;+ try {+ result = packageAndRun(project, templateDir, work);+ } catch (err) {+ console.error(`✗ ${label}: ${err.message}`);+ failed += 1;+ continue;+ }+ const { verdict } = result;+ if (!verdict) {+ // No verdict at all is the launch that died, and the tail is the only+ // evidence of where.+ console.error(`✗ ${label}: no frame was captured (exit ${result.status})`);+ console.error(result.output.split('\n').slice(-25).join('\n'));+ failed += 1;+ } else if (!verdict.rendered) {+ console.error(`✗ ${label}: ran and drew nothing — ${JSON.stringify(verdict)}`);+ failed += 1;+ } else {+ console.log(`✓ ${label}: ${verdict.w}x${verdict.h}, spread ${verdict.spread}`);+ }+ }+} finally {+ rmSync(work, { recursive: true, force: true });+}++if (failed > 0) {+ console.error(`verify-desktop-render: ${failed} of ${projects.length} did not draw.`);+ process.exit(1);+}+console.log(`verify-desktop-render: ${projects.length} packaged game(s) drew on ${HOST_OS}.`);