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(export): a shipping Android build is signed with the project's release key
esengine9ff004ee8f2b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1d42722f1..042331b28 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,10 +16,12 @@ published separately; it ships inside the editor.### Added+- **Android release signing.** A Shipping APK (and App Bundle) is signed with the release key the project names under Project Settings → Android → Signing — two PEM paths, the passphrase kept in this machine's keychain (the command line reads `ESTELLA_ANDROID_KEY_PASSPHRASE`); Development builds keep the development key. A Shipping build without one says it will be refused by Google Play.- **Export profiles.** A project can name several exports of one target in `packaging.profiles` — a test and a production WeChat build, each with its own AppID, CDN root and development or shipping configuration, writing only what differs from the project's settings. The Build dialog creates, edits and deletes them per target, marking each setting a profile overrides with a reset that hands it back to the project; `estella export --profile <name>` and the agent's `export_game` build the same one, and the size history records which profile a build used.### Fixed+- An export warns when a signing key the project names (a quick game's or Android's) sits inside the project and is committed to its repository, or is not ignored and would be committed next.- Opening a project no longer holds the editor behind "Preparing play realm…" for about ten seconds: the play realm's warm-up was being cut off and the editor waited out its deadline. A project now opens in under a second, and the first Play is still warm.- An export from the Build dialog and one from `estella export` now read the project the same way. The dialog's builds keep the engine modules a project includes or excludes, which they ignored; the command line's carry the project's app id (a native package was always `com.estella.game`, so two games replaced each other on a phone), its script entry and scenes folder, its desktop channel and Steam app, and a playable's ad network.- Android's "Android Studio project" and "App Bundle (.aab)" settings take effect: the project file never read them back, so every Android export wrote an APK and nothing else.diff --git a/desktop b/desktopindex 32a6e3830..286109b49 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 32a6e3830e8a5a222d57a06aa16fe15ee4256e2e+Subproject commit 286109b49e02655d43ecd7e4b44456b315656076diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex 510bddd68..69e42fbf3 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -22,6 +22,9 @@ const USAGE = `usage: node pipeline/bin/estella.mjs export <projectDir> [optionsor a platform the project defines in .esengine/platforms/ (default web)--profile <name> one of the project's export profiles (packaging.profiles): itstarget, development or shipping, and the settings it overrides+ A shipping Android build is signed with the project's release+ key (platforms.android.releaseKey); its passphrase comes from+ ESTELLA_ANDROID_KEY_PASSPHRASE--out <dir> output dir (default <projectDir>/dist-<platform>)--wasm <dir> engine runtime to ship (default: the build tree, else the editor's copy)--scene <path> entry scene, project-relative (default: the project's own)@@ -815,7 +818,8 @@ if (!fmt.BUILTIN_PLATFORMS.includes(platform)) {let code = 1;try {const result = await exporter.exportGame({- ...await projectOpts.projectExportOptions(opts.projectDir, manifest, platform, opts.profile),+ ...await projectOpts.projectExportOptions(opts.projectDir, manifest, platform, opts.profile,+ { androidKeyPassphrase: process.env.ESTELLA_ANDROID_KEY_PASSPHRASE }),entryScene,...(opts.scripts ? { scriptsEntry: opts.scripts } : {}),...(opts.title ? { title: opts.title } : {}),diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex dbf45de55..520c35ab6 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -24,6 +24,8 @@ import { loadEsbuild } from '../bundle/esbuildRuntime';import { runtimeHostEntry } from '../bundle/runtimeHosts';import { writeFile, readFile, mkdir, cp, readdir, rm } from 'node:fs/promises';import { existsSync, readFileSync, statSync } from 'node:fs';+import { spawnSync } from 'node:child_process';+import { isInsideRoot } from '../fs/pathSandbox';import path from 'node:path';import { cookAssets, type CookManifest, type Inclusion } from '../assets/cookAssets';import { cookWorlds, streamedScenes } from '../world/cookWorld';@@ -555,6 +557,8 @@ export interface ExportGameOptions {hotUpdate?: { remoteRoot?: string; persistUpdateKey?: string };/** The export profile this build was made with, recorded in its size history. */profile?: string;+ /** Signing key files the project names, checked against its repository. */+ secretFiles?: readonly string[];/** iOS: where the prebuilt engine + app shell live, so the export can wrap* itself in an Xcode project. Omitted (or null) exports content only. */iosSources?: IosProjectSources | null;@@ -579,9 +583,11 @@ export interface ExportGameOptions {* and the only route for a game that has to add an SDK of its own.*/androidOutput?: 'package' | 'project';- /** Android: the identity to sign with. Omitted uses the development key, which- * installs on a device and is refused by every store. */- androidKey?: SigningKey;+ /** Android: the release identity a shipping build (`minify`) is signed with.+ * A development build, or a shipping one without it, uses the development key,+ * which installs on a device and is refused by every store. Read only when a+ * shipping build needs it, so a development build asks for no passphrase. */+ androidKey?: SigningKey | (() => SigningKey);/** The app's launcher icon (project-relative). Omitted ⇒ the template's default. */appIcon?: string;/** `packaging.sizeBudget[platform]` — the project's own package-size ceiling in@@ -598,7 +604,31 @@ export interface ExportGameOptions {* defines for itself would have none. See sizeReport.ts for what is counted.*/export async function exportGame(opts: ExportGameOptions): Promise<ExportGameResult> {- return attachSizeReport(await produceExport(opts), opts);+ const result = await attachSizeReport(await produceExport(opts), opts);+ const exposed = committableSecrets(opts.root, opts.secretFiles ?? []);+ return exposed.length > 0 ? { ...result, warnings: [...result.warnings, ...exposed] } : result;+}++/**+ * Signing keys a commit of the project would publish: inside it, and either+ * tracked or not ignored. A project that is not a git checkout says nothing,+ * since there is no repository to leak into.+ */+export function committableSecrets(root: string, files: readonly string[]): string[] {+ const git = (...args: string[]) => spawnSync('git', args, { cwd: root, encoding: 'utf8' });+ if (files.length === 0 || git('rev-parse', '--is-inside-work-tree').stdout.trim() !== 'true') return [];+ const out: string[] = [];+ for (const file of files) {+ const abs = path.resolve(root, file);+ if (!isInsideRoot(root, abs) || !existsSync(abs)) continue;+ const rel = path.relative(root, abs).split(path.sep).join('/');+ if (git('ls-files', '--error-unmatch', '--', rel).status === 0) {+ out.push(`The signing key ${rel} is committed to the project's repository: anyone with the repository can sign as you. Move it out of the project and remove it from git history.`);+ } else if (git('check-ignore', '-q', '--', rel).status !== 0) {+ out.push(`The signing key ${rel} is in the project and not ignored, so the next commit of everything would publish it. Move it out of the project, or add it to .gitignore.`);+ }+ }+ return out;}/**@@ -1230,7 +1260,13 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>absOut, appConfig, androidTemplateSources(template), icon);} else {progress({ phase: 'Assembling the APK' });- const key = opts.androidKey ?? debugSigningKey();+ const release = opts.minify && opts.androidKey+ ? (typeof opts.androidKey === 'function' ? opts.androidKey() : opts.androidKey) : null;+ const key = release ?? debugSigningKey();+ if (opts.minify && !opts.androidKey) {+ warnings.push('This shipping APK is signed with the development key, which Google Play refuses: '+ + 'set a release key under Project Settings → Android → Signing.');+ }const assembly = { templateDir: template, contentDir: absOut, app: appConfig, key, icon };apkFile = path.join(absOut, apkFileName(appConfig.id));await writeFile(apkFile, assembleApk(assembly));diff --git a/pipeline/src/export/projectExportOptions.ts b/pipeline/src/export/projectExportOptions.tsindex dd0c0f587..f56212d63 100644--- a/pipeline/src/export/projectExportOptions.ts+++ b/pipeline/src/export/projectExportOptions.ts@@ -13,6 +13,7 @@import path from 'node:path';import type { ExportGameOptions } from './exportGame';import { readReleaseKey } from './rpk';+import { signingKeyFromPem, type SigningKey } from '../../../build-tools/utils/androidKeystore.js';import { loadPlayableProfile } from './platformCatalog';import {EXPORT_PROFILE_FIELDS, resolveAppId, resolveLayout, resolveOrientation, resolveScripts,@@ -58,8 +59,13 @@ export function withExportProfile(manifest: ProjectManifest, name: string): Proj};}+/** What a project may not hold, handed in by whoever keeps it on this machine. */+export interface ExportSecrets {+ androidKeyPassphrase?: string;+}+export async function projectExportOptions(- root: string, source: ProjectManifest, platform: ExportPlatform, profileName?: string,+ root: string, source: ProjectManifest, platform: ExportPlatform, profileName?: string, secrets: ExportSecrets = {},): Promise<ProjectExportOptions> {const profile = profileName ? source.packaging?.profiles?.[profileName] : undefined;const manifest = profileName ? withExportProfile(source, profileName) : source;@@ -95,6 +101,9 @@ export async function projectExportOptions(androidVersionCode: plat?.android?.versionCode,androidAppBundle: plat?.android?.appBundle,androidOutput: plat?.android?.output,+ ...(platform === 'android' && plat?.android?.releaseKey+ ? { androidKey: () => androidReleaseKey(root, plat.android!.releaseKey!, secrets.androidKeyPassphrase) }+ : {}),desktopProductName: plat?.desktop?.productName,desktopChannel: plat?.desktop?.channel,steam: plat?.desktop?.steam,@@ -102,6 +111,8 @@ export async function projectExportOptions(? { playableAdProfile: (await loadPlayableProfile(root, plat?.playable?.network)) ?? undefined }: {}),sizeBudgetBytes: packaging?.sizeBudget?.[platform],+ secretFiles: [quickGame?.releaseKey, platform === 'android' ? plat?.android?.releaseKey : undefined]+ .flatMap((k) => (k ? [k.privateKey, k.certificate] : [])).filter((f) => f !== ''),...(profile ? {profile: profileName,...(profile.config ? { minify: profile.config === 'shipping' } : {}),@@ -109,3 +120,19 @@ export async function projectExportOptions(} : {}),};}++/** A named key that cannot be read is an error, not a quiet fall back to the+ * development key: that package would be refused at upload. */+function androidReleaseKey(+ root: string, paths: { privateKey: string; certificate: string }, passphrase: string | undefined,+): SigningKey {+ try {+ return signingKeyFromPem({+ key: path.resolve(root, paths.privateKey),+ cert: path.resolve(root, paths.certificate),+ ...(passphrase ? { passphrase } : {}),+ });+ } catch (e) {+ throw new Error(`the Android release key could not be read (${paths.privateKey}, ${paths.certificate}): ${(e as Error).message}`);+ }+}diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex e94bafed7..8f3f310aa 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -275,6 +275,13 @@ export interface AndroidPackaging {* output for the one that is not being used.*/appBundle?: boolean;+ /**+ * The release identity a shipping build is signed with: two PEM paths, relative+ * to the project or absolute. Keep the files out of the project's repository;+ * a passphrase never lives here (the editor's keychain, or+ * ESTELLA_ANDROID_KEY_PASSPHRASE for the command line).+ */+ releaseKey?: { privateKey: string; certificate: string };}/** iOS's slice: the bundle identifier Xcode signs against. */export interface IosPackaging { appId?: string; }@@ -906,6 +913,10 @@ export function parseManifest(raw: unknown): ProjectManifest {}if (an.output === 'package' || an.output === 'project') a.output = an.output;if (typeof an.appBundle === 'boolean') a.appBundle = an.appBundle;+ const key = an.releaseKey as Record<string, unknown> | undefined;+ if (key && typeof key.privateKey === 'string' && typeof key.certificate === 'string') {+ a.releaseKey = { privateKey: key.privateKey, certificate: key.certificate };+ }if (Object.keys(a).length > 0) platforms.android = a;}const io = pl.ios as Record<string, unknown> | undefined;diff --git a/pipeline/tests/committable-secrets.test.ts b/pipeline/tests/committable-secrets.test.tsnew file mode 100644index 000000000..01bc7b6f5--- /dev/null+++ b/pipeline/tests/committable-secrets.test.ts@@ -0,0 +1,48 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A signing key the project's repository would publish is said so at export.+ */+import { describe, it, expect, afterEach } from 'vitest';+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';+import { execFileSync } from 'node:child_process';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { committableSecrets } from '../src/export/exportGame';++const dirs: string[] = [];+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });++function project(git: boolean): string {+ const root = mkdtempSync(path.join(tmpdir(), 'secrets-'));+ dirs.push(root);+ mkdirSync(path.join(root, 'sign'));+ for (const f of ['tracked.pem', 'ignored.pem', 'loose.pem']) writeFileSync(path.join(root, 'sign', f), 'KEY');+ if (git) {+ const g = (...a: string[]) => execFileSync('git', a, { cwd: root, stdio: 'ignore' });+ g('init', '-q');+ writeFileSync(path.join(root, '.gitignore'), 'sign/ignored.pem\n');+ g('add', 'sign/tracked.pem', '.gitignore');+ g('-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-q', '-m', 'x');+ }+ return root;+}++describe('a signing key the repository would publish', () => {+ it('is named when committed, and when neither committed nor ignored', () => {+ const root = project(true);+ const said = committableSecrets(root, ['sign/tracked.pem', 'sign/ignored.pem', 'sign/loose.pem']);+ expect(said).toHaveLength(2);+ expect(said[0]).toMatch(/sign\/tracked\.pem is committed/);+ expect(said[1]).toMatch(/sign\/loose\.pem is in the project and not ignored/);+ });++ it('is not a concern outside the project, or where there is no repository', () => {+ const root = project(true);+ const outside = mkdtempSync(path.join(tmpdir(), 'keys-'));+ dirs.push(outside);+ writeFileSync(path.join(outside, 'k.pem'), 'KEY');+ expect(committableSecrets(root, [path.join(outside, 'k.pem')])).toEqual([]);+ expect(committableSecrets(project(false), ['sign/loose.pem'])).toEqual([]);+ });+});diff --git a/pipeline/tests/project-export-options.test.ts b/pipeline/tests/project-export-options.test.tsindex 543947c4e..238e50c6e 100644--- a/pipeline/tests/project-export-options.test.ts+++ b/pipeline/tests/project-export-options.test.ts@@ -162,3 +162,38 @@ describe('an export profile', () => {await expect(projectExportOptions(root, withProfiles, 'douyin', 'test')).rejects.toThrow(/is for wechat, not douyin/);});});++describe('an Android release key', () => {+ it('is read only when a shipping build asks for it, from paths the project names', async () => {+ const keys = mkdtempSync(path.join(tmpdir(), 'android-release-'));+ const was = process.env.ESTELLA_ANDROID_KEYS;+ process.env.ESTELLA_ANDROID_KEYS = keys;+ try {+ const { debugSigningKey } = await import('../../build-tools/utils/androidKeystore.js');+ debugSigningKey();+ const m = parseManifest({+ formatVersion: '1', name: 'p',+ packaging: { platforms: { android: { releaseKey: {+ privateKey: path.join(keys, 'debug.key.pem'), certificate: path.join(keys, 'debug.cert.pem'),+ } } } },+ });+ const o = await projectExportOptions(root, m, 'android');+ expect(typeof o.androidKey).toBe('function');+ const key = (o.androidKey as () => { certificate: Buffer })();+ expect(key.certificate.length).toBeGreaterThan(0);+ expect((await projectExportOptions(root, m, 'web')).androidKey).toBeUndefined();+ } finally {+ if (was === undefined) delete process.env.ESTELLA_ANDROID_KEYS; else process.env.ESTELLA_ANDROID_KEYS = was;+ rmSync(keys, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });+ }+ });++ it('that cannot be read says so when it is needed, and not before', async () => {+ const m = parseManifest({+ formatVersion: '1', name: 'p',+ packaging: { platforms: { android: { releaseKey: { privateKey: 'nope.pem', certificate: 'nope.cert.pem' } } } },+ });+ const o = await projectExportOptions(root, m, 'android');+ expect(() => (o.androidKey as () => unknown)()).toThrow(/Android release key could not be read \(nope\.pem/);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex f906c5b85..2ef89a90d 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -1160,4 +1160,8 @@ export const NOTED = {{ note: 'Opening a project no longer holds the editor behind "Preparing play realm…" for about ten seconds: the play realm\'s warm-up was being cut off and the editor waited out its deadline. A project now opens in under a second, and the first Play is still warm.' },'feat(build): export profiles are created, edited and deleted in the Build dialog':{ note: '**Export profiles.** A project can name several exports of one target in `packaging.profiles` — a test and a production WeChat build, each with its own AppID, CDN root and development or shipping configuration, writing only what differs from the project\'s settings. The Build dialog creates, edits and deletes them per target, marking each setting a profile overrides with a reset that hands it back to the project; `estella export --profile <name>` and the agent\'s `export_game` build the same one, and the size history records which profile a build used.' },+ 'feat(export): a shipping Android build is signed with the project\'s release key':+ { note: '**Android release signing.** A Shipping APK (and App Bundle) is signed with the release key the project names under Project Settings → Android → Signing — two PEM paths, the passphrase kept in this machine\'s keychain (the command line reads `ESTELLA_ANDROID_KEY_PASSPHRASE`); Development builds keep the development key. A Shipping build without one says it will be refused by Google Play.' },+ 'feat(settings): Android release signing is set in Project Settings':+ { note: '**Android release signing.** A Shipping APK (and App Bundle) is signed with the release key the project names under Project Settings → Android → Signing — two PEM paths, the passphrase kept in this machine\'s keychain (the command line reads `ESTELLA_ANDROID_KEY_PASSPHRASE`); Development builds keep the development key. A Shipping build without one says it will be refused by Google Play.' },};