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
fix(release): check what is inside a template, not just that its name is there
yhh9eac982f440d
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.ymlindex 6a9223c70..f50e9cee9 100644--- a/.github/workflows/release-desktop.yml+++ b/.github/workflows/release-desktop.yml@@ -393,6 +393,22 @@ jobs:exit 1fi+ # Names on a release say nothing about what is inside the archives, and the+ # thing that goes wrong is inside: v0.36.0 published an Android template with+ # no precompiled bytecode, so every game packaged from it opened on a black+ # screen the first time and nothing here noticed. Check the contents against+ # the same table the emitter writes from, under release strictness.+ - uses: actions/checkout@v7+ - uses: actions/setup-node@v6+ with:+ node-version: 22+ - name: Check the templates carry everything+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ run: |+ gh release download "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" -p 'estella-native-*.zip' -D templates+ node build-tools/cli.js verify-template templates/*.zip+- name: Publishenv:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}diff --git a/build-tools/cli.js b/build-tools/cli.jsindex 6365c1115..9808f41ae 100644--- a/build-tools/cli.js+++ b/build-tools/cli.js@@ -279,6 +279,22 @@ programlogger.printTime(startTime);});+program+ .command('verify-template <archives...>')+ .description('Check published runtime-template archives carry everything a release must')+ .action(async (archives) => {+ logger.header('Verify Runtime Templates');+ const { verifyTemplates } = await import('./tasks/verifyTemplate.js');+ try {+ verifyTemplates(archives);+ } catch (err) {+ // The reason is already printed per archive; a stack trace on top of it+ // only buries what a release engineer has to read.+ logger.error(err.message);+ process.exit(1);+ }+ });+program.command('toolchain').description('Package local emsdk + cmake into Tauri resources for bundling')diff --git a/build-tools/tasks/verifyTemplate.js b/build-tools/tasks/verifyTemplate.jsnew file mode 100644index 000000000..d98687599--- /dev/null+++ b/build-tools/tasks/verifyTemplate.js@@ -0,0 +1,103 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+//+// Does a template archive hold what a template must hold?+//+// The release gate used to check that the asset NAMES were on the release, which+// a zip missing half its contents passes. v0.36.0 published an Android template+// with no precompiled bytecode that way, and every game packaged from it opened+// on a black screen the first time — a failure that reached players before it+// reached us, because nothing between the build and the store looked inside.+//+// The check reads the archive's central directory rather than unpacking it, and+// asks the SAME table the emitter writes from, under release strictness: what a+// contributor's local build may omit, a published template may not.++import { basename } from 'path';+import { readFileSync } from 'fs';+import * as logger from '../utils/logger.js';+import { readZip } from '../utils/zip.js';+import {+ missingTemplateEntries, readTemplateManifest, TEMPLATE_MANIFEST, TEMPLATE_FORMAT,+} from '../utils/nativeTemplate.js';++/** The manifest inside the archive, without unpacking it. */+function manifestOf(entries) {+ const entry = entries.find((e) => e.name === TEMPLATE_MANIFEST);+ if (!entry) return null;+ try {+ return JSON.parse(entry.data.toString('utf8'));+ } catch {+ return null;+ }+}++/**+ * Verify one template archive.+ *+ * @param {string} zipPath+ * @returns {{ok: boolean, problems: string[], platform: string|null, engineVersion: string|null}}+ */+export function verifyTemplateZip(zipPath) {+ const problems = [];+ let entries;+ try {+ entries = readZip(readFileSync(zipPath));+ } catch (err) {+ return { ok: false, problems: [`unreadable archive: ${err.message}`], platform: null, engineVersion: null };+ }++ const manifest = manifestOf(entries);+ if (!manifest) {+ return {+ ok: false,+ problems: [`no readable ${TEMPLATE_MANIFEST} inside`],+ platform: null,+ engineVersion: null,+ };+ }+ if (manifest.kind !== 'estella-native-template') problems.push(`kind is "${manifest.kind}"`);+ if (manifest.formatVersion !== TEMPLATE_FORMAT) {+ problems.push(`formatVersion ${manifest.formatVersion} (this build writes ${TEMPLATE_FORMAT})`);+ }++ const platform = manifest.platform ?? null;+ if (platform !== 'android' && platform !== 'ios') {+ problems.push(`platform "${platform}" is not one this build knows`);+ return { ok: false, problems, platform, engineVersion: manifest.engineVersion ?? null };+ }++ // Under the ABIs the manifest CLAIMS: a template that says it carries two and+ // ships one is the interesting failure, and asking for the ones it lists is+ // what catches it.+ const missing = missingTemplateEntries(entries.map((e) => e.name), platform, {+ abis: manifest.abis, release: true,+ });+ for (const rel of missing) problems.push(`missing ${rel}`);++ return { ok: problems.length === 0, problems, platform, engineVersion: manifest.engineVersion ?? null };+}++/**+ * Verify every archive named, and report. Throws when any fails, so a workflow+ * step fails the job without a second exit-code convention.+ */+export function verifyTemplates(zipPaths) {+ if (zipPaths.length === 0) throw new Error('no template archives to verify');+ let bad = 0;+ for (const zip of zipPaths) {+ const { ok, problems, platform, engineVersion } = verifyTemplateZip(zip);+ const what = `${basename(zip)} (${platform ?? '?'} ${engineVersion ?? '?'})`;+ if (ok) {+ logger.success(`${what}: complete`);+ } else {+ bad++;+ logger.error(`${what}:`);+ for (const p of problems) logger.error(` ${p}`);+ }+ }+ if (bad > 0) {+ throw new Error(`${bad} of ${zipPaths.length} template archive(s) are incomplete — `+ + 'publishing one ships the failure to every game packaged from it.');+ }+}diff --git a/build-tools/utils/nativeTemplate.js b/build-tools/utils/nativeTemplate.jsindex fe211d0a9..5ccef14f2 100644--- a/build-tools/utils/nativeTemplate.js+++ b/build-tools/utils/nativeTemplate.js@@ -86,10 +86,11 @@ export function templateLayout(platform, options = {}) {{ rel: DEFAULT_ICON, from: (ctx) => path.join(ctx.root, 'native', 'icon.png') },// The same first-launch fix the Android template carries: without it the// host parses the ~700 KB SDK bundle on first run, which is seconds of- // black screen after an install. Absent is valid — the host compiles and- // caches instead.+ // black screen after an install. A local build without it still works —+ // a PUBLISHED one may not ship that first launch to every game made with+ // it, so `release` requires what `optional` excuses.{- rel: `assets/${BYTECODE_FILE}`, optional: true,+ rel: `assets/${BYTECODE_FILE}`, optional: true, releaseRequired: true,from: (ctx) => path.join(ctx.root, 'build/cmake/native-ios', 'gen', BYTECODE_FILE),},];@@ -97,18 +98,20 @@ export function templateLayout(platform, options = {}) {if (platform === 'android') {// Every ABI the build machine produced. Only the first is required: one// architecture is a working template, two is one package that installs on a- // phone and in an emulator alike.+ // phone and in an emulator alike. A release builds both, so a release is+ // held to both — losing the emulator ABI costs everyone without a phone+ // their only way to run the game.const libs = abis.flatMap((abi, n) => [{- rel: `lib/${abi}/libestella_js_host.so`, strip: true, abi, optional: n > 0,+ rel: `lib/${abi}/libestella_js_host.so`, strip: true, abi, optional: n > 0, releaseRequired: true,from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, 'libestella_js_host.so'),},{- rel: `lib/${abi}/libwebgpu_dawn.so`, strip: true, abi, optional: n > 0,+ rel: `lib/${abi}/libwebgpu_dawn.so`, strip: true, abi, optional: n > 0, releaseRequired: true,from: (ctx) => ctx.dawnLibrary?.(abi),},{- rel: `lib/${abi}/libc++_shared.so`, abi, optional: n > 0,+ rel: `lib/${abi}/libc++_shared.so`, abi, optional: n > 0, releaseRequired: true,from: (ctx) => ctx.libcxxShared?.(abi),},]);@@ -126,10 +129,12 @@ export function templateLayout(platform, options = {}) {rel: 'java', kind: 'dir',from: (ctx) => path.join(ctx.root, 'native', 'android', 'java'),},- // Absent is valid — the host falls back to compiling the bundle, at the- // cost of a ~14 s black screen on first launch.+ // Absent is valid in a local build — the host falls back to compiling the+ // bundle, at the cost of a ~14 s black screen on first launch. Not valid+ // in a release: v0.36.0 shipped without it, and every Android package+ // built from that template opened black.{- rel: `assets/${BYTECODE_FILE}`, optional: true,+ rel: `assets/${BYTECODE_FILE}`, optional: true, releaseRequired: true,from: (ctx) => path.join(ctx.root, 'build/cmake/native', 'gen', BYTECODE_FILE),},{@@ -142,9 +147,23 @@ export function templateLayout(platform, options = {}) {throw new Error(`Unknown native platform "${platform}" (expected android or ios).`);}+/**+ * The entries a template must carry, for one audience.+ *+ * `optional` is not one question but two, and conflating them is how a release+ * shipped an Android template with no precompiled bytecode: a contributor's local+ * build is fine without it (the host compiles on the device instead), and a+ * PUBLISHED template is not — every game packaged from it then opens on a black+ * screen the first time. `release: true` applies the stricter rule.+ */+function requiredTemplateEntries(platform, options = {}) {+ return templateLayout(platform, options)+ .filter((e) => !e.optional || (options.release && e.releaseRequired));+}+/** Template-relative paths that must be present for a template to be usable. */export function requiredTemplateFiles(platform, options) {- return templateLayout(platform, options).filter((e) => !e.optional).map((e) => e.rel);+ return requiredTemplateEntries(platform, options).map((e) => e.rel);}/**@@ -177,6 +196,23 @@ export function missingTemplateFiles(dir, platform, options) {return requiredTemplateFiles(platform, options).filter((rel) => !existsSync(path.join(dir, rel)));}+/**+ * The same test over a LISTING rather than a directory — for an archive that has+ * not been unpacked, which is the form a template is published in and therefore+ * the form worth checking before anyone can install it.+ *+ * A directory entry is present when something inside it is: a zip stores the+ * files, not the folder.+ */+export function missingTemplateEntries(names, platform, options = {}) {+ const held = names.map((n) => n.split('\\').join('/').replace(/\/+$/, ''));+ const set = new Set(held);+ const has = (e) => (e.kind === 'dir'+ ? held.some((n) => n === e.rel || n.startsWith(`${e.rel}/`))+ : set.has(e.rel));+ return requiredTemplateEntries(platform, options).filter((e) => !has(e)).map((e) => e.rel);+}+// =============================================================================// The manifest// =============================================================================diff --git a/desktop/tests/native-template.test.ts b/desktop/tests/native-template.test.tsindex 2c7d10f36..0e25bb2f1 100644--- a/desktop/tests/native-template.test.ts+++ b/desktop/tests/native-template.test.ts@@ -21,7 +21,7 @@ import {import { listPlatforms } from '../electron/platformCatalog';import {requiredTemplateFiles, templateLayout, installedTemplateDir, parseTemplateIndex,- TEMPLATE_FORMAT, TEMPLATE_MANIFEST, TEMPLATE_INDEX,+ missingTemplateEntries, TEMPLATE_FORMAT, TEMPLATE_MANIFEST, TEMPLATE_INDEX,} from '../../build-tools/utils/nativeTemplate.js';import { makeZip } from '../../build-tools/utils/zip.js';@@ -288,3 +288,50 @@ describe('the template layout is the one source of filenames', () => {path.relative(dir, sources.bytecode).split(path.sep).join('/'));});});++describe('what a PUBLISHED template must carry', () => {+ // The bytecode is optional for a local build and not for a release, and reading+ // "optional" as one answer to both is what let v0.36.0 ship an Android template+ // without it — every game packaged from that template opened on a black screen+ // while the host compiled the bundle on the device.+ const BYTECODE = 'assets/esengine.native.qjsbc';++ // What v0.36.0 actually published, minus the bytecode: complete by the rule a+ // contributor's build is held to.+ const shipped = (extra: string[] = []) => [+ 'AndroidManifest.xml.in', 'classes.dex', 'icon.png',+ 'java/com/estella/host/TextEditor.java',+ 'lib/arm64-v8a/libestella_js_host.so', 'lib/arm64-v8a/libwebgpu_dawn.so',+ 'lib/arm64-v8a/libc++_shared.so',+ 'lib/x86_64/libestella_js_host.so', 'lib/x86_64/libwebgpu_dawn.so',+ 'lib/x86_64/libc++_shared.so',+ 'template.json', ...extra,+ ];++ it('accepts a template without bytecode, and refuses to publish it', () => {+ expect(missingTemplateEntries(shipped(), 'android')).toEqual([]);+ expect(missingTemplateEntries(shipped(), 'android', { release: true })).toEqual([BYTECODE]);+ expect(missingTemplateEntries(shipped([BYTECODE]), 'android', { release: true })).toEqual([]);+ });++ it('holds a release to every ABI the template claims', () => {+ // One ABI is a usable template; a release builds both, and losing the emulator+ // one leaves everybody without a phone unable to run the game at all.+ const oneAbi = shipped([BYTECODE]).filter((n) => !n.startsWith('lib/x86_64/'));+ expect(missingTemplateEntries(oneAbi, 'android')).toEqual([]);+ expect(missingTemplateEntries(oneAbi, 'android', { release: true }))+ .toEqual(expect.arrayContaining(['lib/x86_64/libestella_js_host.so']));+ });++ it('counts a directory entry as held when something inside it is', () => {+ // A zip stores files, never the folder — so `java` is present because+ // `java/com/...` is, and absent when nothing under it shipped.+ const noJava = shipped([BYTECODE]).filter((n) => !n.startsWith('java/'));+ expect(missingTemplateEntries(noJava, 'android', { release: true })).toEqual(['java']);+ });++ it('reads Windows separators, since that is where an archive may be listed', () => {+ const win = shipped([BYTECODE]).map((n) => n.split('/').join(String.fromCharCode(92)));+ expect(missingTemplateEntries(win, 'android', { release: true })).toEqual([]);+ });+});