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.

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.yml
index 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: ios
os: macos-latest
+ - target: macos
+ os: macos-latest
+ - target: windows
+ os: windows-latest
steps:
# 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 pins
id: 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@v4
with:
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 found
run: |
@@ -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 commits
if: steps.restore.outputs.cache-hit != 'true'
run: node build-tools/cli.js native --fetch-deps
@@ -122,4 +137,4 @@ jobs:
uses: actions/cache/save@v4
with:
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.yml
index 4295a3990..f4f7f5e30 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -119,6 +119,10 @@ jobs:
os: macos-latest
- name: android
os: ubuntu-latest
+ - name: macos
+ os: macos-latest
+ - name: windows
+ os: windows-latest
runs-on: ${{ matrix.os }}
timeout-minutes: 120
steps:
@@ -139,9 +143,7 @@ jobs:
- name: Read the native dependency pins
id: pins
shell: 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@v4
with:
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 NDK
if: matrix.name == 'android'
uses: nttld/setup-ndk@v1
@@ -187,6 +199,21 @@ jobs:
node build-tools/cli.js native --abi arm64-v8a
node 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 artifact
uses: actions/upload-artifact@v7
with:
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 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 @@ program
templateOnly: 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.js
index 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.ts
new file mode 100644
index 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.js
index 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.ts
new file mode 100644
index 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.mjs
new file mode 100644
index 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}.`);