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.

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.yml
index 6a9223c70..f50e9cee9 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -393,6 +393,22 @@ jobs:
exit 1
fi
+ # 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: Publish
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/build-tools/cli.js b/build-tools/cli.js
index 6365c1115..9808f41ae 100644
--- a/build-tools/cli.js
+++ b/build-tools/cli.js
@@ -279,6 +279,22 @@ program
logger.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.js
new file mode 100644
index 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.js
index 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.ts
index 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([]);
+ });
+});