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 project names its exports as profiles, and the command line builds one
esengine88bc737e6cb0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3cdac5ae7..f48400d95 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,10 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **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. `estella export --profile <name>` builds one, and the size history records which profile a build used.+### Fixed- 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.diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex 12ccadfb1..510bddd68 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -20,16 +20,18 @@ const USAGE = `usage: node pipeline/bin/estella.mjs export <projectDir> [options--platform <id> a built-in (web, desktop, wechat, douyin, kuaishou, bilibili, playable, android, ios)or a platform the project defines in .esengine/platforms/ (default web)+ --profile <name> one of the project's export profiles (packaging.profiles): its+ target, development or shipping, and the settings it overrides--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)--title <name> app title (default: the project's name)- --scripts <path> scripts entry, project-relative (default src/main.ts if present)+ --scripts <path> scripts entry, project-relative (default: the project's scripts.main)--template <dir> android/ios/desktop: the runtime template to wrap, else the installed one--output project android: emit a Gradle project instead of an apk--json <file> also write the result here, for a caller that reads it back--enforce-budget fail (exit 1) when the package is over a size limit- --minify minify the bundled scripts, as a shipping build does+ --minify minify the bundled scripts, as a shipping build (or profile) does--debug-channel <url> a development build dials this editor address(ws://host:port/?token=…) so its frames can be captured;refused together with --minify@@ -93,7 +95,7 @@ function parseArgs(argv) {console.error(USAGE);process.exit(2);}- const opts = { projectDir: path.resolve(projectDir), platform: 'web' };+ const opts = { projectDir: path.resolve(projectDir) };for (let i = 0; i < rest.length;) {const key = rest[i]?.replace(/^--/, '');if (!key) break;@@ -744,7 +746,9 @@ if (opts.command === 'import-hdr') {}const project = projectSettings(opts.projectDir);-const platform = opts.platform;+// A profile names its target, so `--profile` alone is enough; the parser that+// applies it refuses one that disagrees with an explicit --platform.+const platform = opts.platform ?? project.packaging?.profiles?.[opts.profile]?.platform ?? 'web';const entryScene = opts.scene ?? project.defaultScene ?? (firstExisting([@@ -811,7 +815,7 @@ if (!fmt.BUILTIN_PLATFORMS.includes(platform)) {let code = 1;try {const result = await exporter.exportGame({- ...await projectOpts.projectExportOptions(opts.projectDir, manifest, platform),+ ...await projectOpts.projectExportOptions(opts.projectDir, manifest, platform, opts.profile),entryScene,...(opts.scripts ? { scriptsEntry: opts.scripts } : {}),...(opts.title ? { title: opts.title } : {}),@@ -833,7 +837,7 @@ try {} : {}),iosSources: platform === 'ios' && templateDir ? iosTemplateSources(templateDir) : null,...(opts.output === 'project' ? { androidOutput: 'project' } : {}),- minify: opts.minify,+ ...(opts.minify ? { minify: true } : {}),...(opts['debug-channel'] ? { debugChannel: { url: opts['debug-channel'] } } : {}),// `dev` is what the AOT step calls "do not compile" — the editor's preview// mode, reused here so there is one word for it (docs/REARCH_AOT.md §9).diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.tsindex bc5bfb7c7..dbf45de55 100644--- a/pipeline/src/export/exportGame.ts+++ b/pipeline/src/export/exportGame.ts@@ -553,6 +553,8 @@ export interface ExportGameOptions {* assets resolve against + the storage key an applied update persists under.* The addressable `asset-manifest.json` this export always emits enables it. */hotUpdate?: { remoteRoot?: string; persistUpdateKey?: string };+ /** The export profile this build was made with, recorded in its size history. */+ profile?: 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;diff --git a/pipeline/src/export/projectExportOptions.ts b/pipeline/src/export/projectExportOptions.tsindex f9a4fb4d6..dd0c0f587 100644--- a/pipeline/src/export/projectExportOptions.ts+++ b/pipeline/src/export/projectExportOptions.ts@@ -15,8 +15,8 @@ import type { ExportGameOptions } from './exportGame';import { readReleaseKey } from './rpk';import { loadPlayableProfile } from './platformCatalog';import {- resolveAppId, resolveLayout, resolveOrientation, resolveScripts,- type ExportPlatform, type ProjectManifest,+ EXPORT_PROFILE_FIELDS, resolveAppId, resolveLayout, resolveOrientation, resolveScripts,+ type ExportPlatform, type ProjectManifest, type ProjectPackaging,} from '../project/format';import { BUILTIN_PLATFORMS, isMiniGamePlatform } from '../project/platforms';import { cookOptionsOf, packagingOptionsOf, runtimeConfigOf } from '../project/runtimeConfig';@@ -30,9 +30,42 @@ const NATIVE_IDENTITY: Partial<Record<ExportPlatform, 'android' | 'ios' | 'desktandroid: 'android', ios: 'ios', desktop: 'desktop',};+/**+ * The project as one of its export profiles describes it: the profile's settings+ * laid over the project's, its target's slice merged field by field so a profile+ * that names only a test appid keeps the project's version code.+ */+export function withExportProfile(manifest: ProjectManifest, name: string): ProjectManifest {+ const profiles = manifest.packaging?.profiles ?? {};+ const profile = profiles[name];+ if (!profile) {+ const known = Object.keys(profiles);+ throw new Error(`no export profile "${name}" — ${known.length ? `this project has ${known.join(', ')}` : 'this project defines none'}`);+ }+ const packaging = manifest.packaging ?? {};+ const target = profile.platform as keyof NonNullable<ProjectPackaging['platforms']>;+ const slice = { ...packaging.platforms?.[target], ...profile.platforms?.[target] };+ const overrides = Object.fromEntries(EXPORT_PROFILE_FIELDS+ .filter((key) => profile[key] !== undefined).map((key) => [key, profile[key]]));+ return {+ ...manifest,+ packaging: {+ ...packaging,+ ...overrides,+ platform: profile.platform,+ platforms: { ...packaging.platforms, ...(Object.keys(slice).length > 0 ? { [target]: slice } : {}) },+ },+ };+}+export async function projectExportOptions(- root: string, manifest: ProjectManifest, platform: ExportPlatform,+ root: string, source: ProjectManifest, platform: ExportPlatform, profileName?: string,): Promise<ProjectExportOptions> {+ const profile = profileName ? source.packaging?.profiles?.[profileName] : undefined;+ const manifest = profileName ? withExportProfile(source, profileName) : source;+ if (profile && profile.platform !== platform) {+ throw new Error(`export profile "${profileName}" is for ${profile.platform}, not ${platform}`);+ }const packaging = manifest.packaging;const plat = packaging?.platforms;const vendor = (plat as Record<string, { appid?: string } | undefined> | undefined)?.[platform];@@ -69,5 +102,10 @@ export async function projectExportOptions(? { playableAdProfile: (await loadPlayableProfile(root, plat?.playable?.network)) ?? undefined }: {}),sizeBudgetBytes: packaging?.sizeBudget?.[platform],+ ...(profile ? {+ profile: profileName,+ ...(profile.config ? { minify: profile.config === 'shipping' } : {}),+ ...(profile.remoteRoot !== undefined ? { hotUpdate: { remoteRoot: profile.remoteRoot } } : {}),+ } : {}),};}diff --git a/pipeline/src/export/sizeHistory.ts b/pipeline/src/export/sizeHistory.tsindex c0e1458e1..f0d4d9a28 100644--- a/pipeline/src/export/sizeHistory.ts+++ b/pipeline/src/export/sizeHistory.ts@@ -34,6 +34,8 @@ export interface SizeSettings {sourcemap?: boolean;compressWasm?: boolean;engineSubpackage?: boolean;+ /** The export profile the build was made with, if any. */+ profile?: string;}/**@@ -66,17 +68,18 @@ export const PACKAGING_SIZE_ROLE: Readonly<Record<string, keyof SizeSettings | '// A logo is inlined into the page, so choosing one changes what ships.splash: 'content',platforms: 'content',+ profiles: 'profile',};/** The settings this build ran with, out of everything the export was given. */export function sizeSettingsOf(opts: SizeSettings): SizeSettings {const keys: (keyof SizeSettings)[] = ['contentAddressed', 'compressTextures', 'compressAudio', 'atlasTextures',- 'minify', 'sourcemap', 'compressWasm', 'engineSubpackage',+ 'minify', 'sourcemap', 'compressWasm', 'engineSubpackage', 'profile',];- const out: SizeSettings = {};+ const out: Record<string, unknown> = {};for (const k of keys) if (opts[k] !== undefined) out[k] = opts[k];- return out;+ return out as SizeSettings;}/** One build's measurement, as the history file stores it. */diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex 1496af83a..5f5ff45c0 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -400,6 +400,27 @@ export interface ProjectPackaging {ios?: IosPackaging;playable?: PlayablePackaging;};+ /** Named exports of one target each (a test and a production WeChat build),+ * picked in the Build dialog or with `estella export --profile <name>`. */+ profiles?: Record<string, ExportProfile>;+}++/** The packaging settings a profile may set; the rest are the project's. */+export const EXPORT_PROFILE_FIELDS = [+ 'config', 'sourceMaps', 'assetCompression', 'compressWasm', 'engineSubpackage', 'excludeScenes',+] as const satisfies readonly (keyof ProjectPackaging)[];++/**+ * One named export of one target. Written in the shape of `packaging` itself, so+ * a profile reads as the settings it changes and nothing else; a setting it leaves+ * out is the project's.+ */+export interface ExportProfile extends Pick<ProjectPackaging, typeof EXPORT_PROFILE_FIELDS[number]> {+ platform: ExportPlatform;+ /** Only the profile's own target's slice is kept. */+ platforms?: ProjectPackaging['platforms'];+ /** The CDN root remote asset groups and hot updates are served from. */+ remoteRoot?: string;}/**@@ -904,11 +925,36 @@ export function parseManifest(raw: unknown): ProjectManifest {if (Object.keys(platforms).length > 0) pkg.platforms = platforms;}if (orientation) pkg.orientation = orientation;+ const profiles = parseExportProfiles(p.profiles);+ if (profiles) pkg.profiles = profiles;if (Object.keys(pkg).length > 0) manifest.packaging = pkg;}return manifest;}+/** Profiles are read by the packaging parser itself, then cut to what a profile+ * may set: one parser, so a profile field cannot be read differently from the+ * project setting it overrides. A profile with no target is dropped. */+function parseExportProfiles(raw: unknown): Record<string, ExportProfile> | undefined {+ if (!raw || typeof raw !== 'object') return undefined;+ const profiles: Record<string, ExportProfile> = {};+ for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {+ if (name === '' || !value || typeof value !== 'object') continue;+ const { profiles: _nested, ...fields } = value as Record<string, unknown>;+ const parsed = parseManifest({ name: 'profile', packaging: fields }).packaging;+ if (!parsed?.platform) continue;+ const profile: ExportProfile = { platform: parsed.platform };+ for (const key of EXPORT_PROFILE_FIELDS) {+ if (parsed[key] !== undefined) (profile as unknown as Record<string, unknown>)[key] = parsed[key];+ }+ const slice = (parsed.platforms as Record<string, unknown> | undefined)?.[parsed.platform];+ if (slice) profile.platforms = { [parsed.platform]: slice } as ProjectPackaging['platforms'];+ if (typeof fields.remoteRoot === 'string') profile.remoteRoot = fields.remoteRoot;+ profiles[name] = profile;+ }+ return Object.keys(profiles).length > 0 ? profiles : undefined;+}+/** Effective layout = defaults overlaid with the manifest's overrides. */export function resolveLayout(manifest: Pick<ProjectManifest, 'layout'>): ProjectLayout {return { ...DEFAULT_LAYOUT, ...(manifest.layout ?? {}) };diff --git a/pipeline/tests/project-export-options.test.ts b/pipeline/tests/project-export-options.test.tsindex b210efa95..51c1de86b 100644--- a/pipeline/tests/project-export-options.test.ts+++ b/pipeline/tests/project-export-options.test.ts@@ -93,3 +93,65 @@ describe('the export a project describes', () => {expect((await projectExportOptions(root, manifest, 'playable')).playableAdProfile?.id).toBe('meta');});});++describe('an export profile', () => {+ const withProfiles = parseManifest({+ formatVersion: '1',+ name: 'Star Hopper',+ defaultScene: 'levels/start.esscene',+ packaging: {+ sourceMaps: false,+ platforms: { wechat: { appid: 'wx-prod' }, quickgame: { appid: 'qg', versionCode: 7 } },+ profiles: {+ test: {+ platform: 'wechat', config: 'development', sourceMaps: true,+ remoteRoot: 'http://192.168.1.5:8080/cdn',+ platforms: { wechat: { appid: 'wx-test' }, android: { versionCode: 99 } },+ },+ prod: { platform: 'wechat', config: 'shipping', remoteRoot: 'https://cdn.example.com/hop' },+ vivo: { platform: 'quickgame', platforms: { quickgame: { appid: 'qg-test' } } },+ broken: { config: 'shipping' },+ },+ },+ });++ it('keeps only what a profile may set, and only its own target\'s slice', () => {+ expect(withProfiles.packaging?.profiles?.test).toEqual({+ platform: 'wechat', config: 'development', sourceMaps: true,+ remoteRoot: 'http://192.168.1.5:8080/cdn',+ platforms: { wechat: { appid: 'wx-test' } },+ });+ });++ it('is dropped when it names no target', () => {+ expect(withProfiles.packaging?.profiles?.broken).toBeUndefined();+ });++ it('lays its settings over the project\'s', async () => {+ const o = await projectExportOptions(root, withProfiles, 'wechat', 'test');+ expect(o).toMatchObject({+ miniGameAppid: 'wx-test', sourcemap: true, minify: false, profile: 'test',+ hotUpdate: { remoteRoot: 'http://192.168.1.5:8080/cdn' },+ });+ expect(await projectExportOptions(root, withProfiles, 'wechat', 'prod'))+ .toMatchObject({ miniGameAppid: 'wx-prod', minify: true, sourcemap: false, hotUpdate: { remoteRoot: 'https://cdn.example.com/hop' } });+ });++ it('keeps the project\'s fields in its target\'s slice that it does not name', async () => {+ const o = await projectExportOptions(root, withProfiles, 'quickgame', 'vivo');+ expect(o).toMatchObject({ miniGameAppid: 'qg-test', miniGameVersionCode: 7 });+ expect(o.minify).toBeUndefined();+ });++ it('leaves an export without a profile as the project describes it', async () => {+ const o = await projectExportOptions(root, withProfiles, 'wechat');+ expect(o).toMatchObject({ miniGameAppid: 'wx-prod', sourcemap: false });+ expect(o.profile).toBeUndefined();+ expect(o.hotUpdate).toBeUndefined();+ });++ it('refuses a name the project does not define, and a profile for another target', async () => {+ await expect(projectExportOptions(root, withProfiles, 'wechat', 'staging')).rejects.toThrow(/this project has test, prod, vivo/);+ await expect(projectExportOptions(root, withProfiles, 'douyin', 'test')).rejects.toThrow(/is for wechat, not douyin/);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 1ca27d48d..456dc2424 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -1150,4 +1150,6 @@ export const NOTED = {{ note: '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.' },'fix(export): the editor and the command line export a project from one reading of it':{ note: '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.' },+ 'feat(export): a project names its exports as profiles, and the command line builds one':+ { 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. `estella export --profile <name>` builds one, and the size history records which profile a build used.' },};