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(export): a project names its exports as profiles, and the command line builds one

esengine88bc737e6cb0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.mjs
index 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.ts
index 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.ts
index 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' | 'deskt
android: '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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.' },
};