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(editor): per-platform Project Settings (Packaging) consumed by export

esengineb6b9ef77eae1
diff --git a/desktop/electron/exportGame.ts b/desktop/electron/exportGame.ts
index f9d1ee506..faf1f377d 100644
--- a/desktop/electron/exportGame.ts
+++ b/desktop/electron/exportGame.ts
@@ -139,8 +139,8 @@ app.on('window-all-closed', () => { if (process.platform !== 'darwin') app.quit(
`;
}
-function desktopPackageJson(title: string): string {
- const slug = slugify(title);
+function desktopPackageJson(title: string, appId?: string, productName?: string): string {
+ const slug = slugify(productName || title);
return JSON.stringify({
name: slug,
version: '1.0.0',
@@ -149,8 +149,8 @@ function desktopPackageJson(title: string): string {
scripts: { start: 'electron .', dist: 'electron-builder' },
devDependencies: { electron: '^42.0.0', 'electron-builder': '^25.0.0' },
build: {
- appId: `com.estella.${slug}`,
- productName: title,
+ appId: appId || `com.estella.${slug}`,
+ productName: productName || title,
files: ['main.cjs', 'app/**/*'],
directories: { output: 'installer' },
mac: { target: 'dmg' },
@@ -182,10 +182,11 @@ The installer is written to \`installer/\`. Build each OS's installer on that OS
}
/** Stage the Electron shell around the web payload already built under `<absOut>/app`. */
-async function stageDesktopApp(absOut: string, title: string): Promise<void> {
- await writeFile(path.join(absOut, 'main.cjs'), desktopMain(title));
- await writeFile(path.join(absOut, 'package.json'), desktopPackageJson(title));
- await writeFile(path.join(absOut, 'README.md'), desktopReadme(title));
+async function stageDesktopApp(absOut: string, title: string, appId?: string, productName?: string): Promise<void> {
+ const display = productName || title;
+ await writeFile(path.join(absOut, 'main.cjs'), desktopMain(display));
+ await writeFile(path.join(absOut, 'package.json'), desktopPackageJson(title, appId, productName));
+ await writeFile(path.join(absOut, 'README.md'), desktopReadme(display));
}
/**
@@ -210,6 +211,13 @@ export async function exportGame(opts: {
playableHostEntry?: string;
/** SINGLE_FILE engine glue (esengine.single.js from `-t playable`) for playable ads. */
glueFile?: string;
+ /** Desktop installer id (Project Settings → Packaging → Desktop); default com.estella.<slug>. */
+ desktopAppId?: string;
+ /** Desktop product/display name (Project Settings); default the project title. */
+ desktopProductName?: string;
+ /** WeChat appid / orientation (Project Settings → Packaging → WeChat). */
+ wechatAppid?: string;
+ wechatOrientation?: 'portrait' | 'landscape';
/** Per-phase progress (build log). */
onProgress?: OnExportProgress;
/** Shipping config: minify the bundles, no sourcemap. Default off (dev). */
@@ -230,6 +238,8 @@ export async function exportGame(opts: {
wasmDir: opts.wasmDir,
outDir: opts.outDir,
title,
+ appid: opts.wechatAppid,
+ orientation: opts.wechatOrientation,
minify: opts.minify,
onProgress: opts.onProgress,
});
@@ -310,7 +320,7 @@ export async function exportGame(opts: {
);
// 6. Desktop: wrap the payload in a runnable Electron app.
- if (platform === 'desktop') { progress({ phase: 'Staging Electron app' }); await stageDesktopApp(absOut, title); }
+ if (platform === 'desktop') { progress({ phase: 'Staging Electron app' }); await stageDesktopApp(absOut, title, opts.desktopAppId, opts.desktopProductName); }
return { ok: errors.length === 0, platform, outDir: absOut, included: cook.included.length, warnings, errors };
}
diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.ts
index afc02310e..f09d4540b 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -66,15 +66,15 @@ function stripUuidRefs(v: unknown): unknown {
return v;
}
-function gameJson(): string {
- return JSON.stringify({ deviceOrientation: 'portrait', showStatusBar: false }, null, 2) + '\n';
+function gameJson(orientation: 'portrait' | 'landscape'): string {
+ return JSON.stringify({ deviceOrientation: orientation, showStatusBar: false }, null, 2) + '\n';
}
-function projectConfigJson(title: string): string {
+function projectConfigJson(title: string, appid: string): string {
return JSON.stringify({
miniprogramRoot: './',
projectname: title,
- appid: '', // fill in your WeChat MiniGame appid in devtools
+ appid, // set in Project Settings → Packaging → WeChat (else fill in devtools)
setting: { es6: false, minified: false },
compileType: 'game',
}, null, 2) + '\n';
@@ -115,6 +115,10 @@ export async function exportWeChat(opts: {
wasmDir: string;
outDir: string;
title?: string;
+ /** WeChat MiniGame appid (Project Settings) → project.config.json. */
+ appid?: string;
+ /** Screen orientation (Project Settings) → game.json. */
+ orientation?: 'portrait' | 'landscape';
minify?: boolean;
onProgress?: OnExportProgress;
}): Promise<ExportWeChatResult> {
@@ -182,8 +186,8 @@ export async function exportWeChat(opts: {
// 5. Entry + config.
await writeFile(path.join(absOut, 'game.js'), gameEntryJs());
- await writeFile(path.join(absOut, 'game.json'), gameJson());
- await writeFile(path.join(absOut, 'project.config.json'), projectConfigJson(title));
+ await writeFile(path.join(absOut, 'game.json'), gameJson(opts.orientation ?? 'portrait'));
+ await writeFile(path.join(absOut, 'project.config.json'), projectConfigJson(title, opts.appid ?? ''));
// 6. The -t wechat engine runtime (WXWebAssembly glue + binary + side modules).
progress({ phase: 'Copying runtime' });
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index e178ef32c..24d740cea 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -294,6 +294,7 @@ ipcMain.handle(
path.join(process.env.APP_ROOT!, '..', 'build', 'wasm', 'playable', 'esengine.single.js'),
path.join(process.env.APP_ROOT!, '..', 'build-playable', 'sdk', 'esengine.single.js'),
].find(existsSync) ?? path.join(VITE_PUBLIC, 'esengine.single.js');
+ const plat = manifest.packaging?.platforms;
return exportGame({
root,
entryScene,
@@ -307,6 +308,10 @@ ipcMain.handle(
outDir: opts?.outDir || 'dist-game',
title: manifest.name,
platform: opts?.platform,
+ desktopAppId: plat?.desktop?.appId,
+ desktopProductName: plat?.desktop?.productName,
+ wechatAppid: plat?.wechat?.appid,
+ wechatOrientation: plat?.wechat?.orientation,
minify: opts?.minify,
sourcemap: opts?.sourcemap,
onProgress: (p) => e.sender.send('project:exportProgress', p),
diff --git a/desktop/src/components/SettingsDialog.tsx b/desktop/src/components/SettingsDialog.tsx
index 7b2e851a6..481569337 100644
--- a/desktop/src/components/SettingsDialog.tsx
+++ b/desktop/src/components/SettingsDialog.tsx
@@ -197,6 +197,16 @@ function Control({ setting }: { setting: Setting }) {
);
case 'keybinding':
return <KeybindCapture setting={setting} />;
+ case 'string':
+ return (
+ <input
+ className="set-str"
+ value={String(value ?? '')}
+ placeholder={setting.placeholder ?? ''}
+ spellCheck={false}
+ onChange={(e) => setValue(setting.id, e.target.value)}
+ />
+ );
case 'stringList':
return <StringListControl setting={setting} />;
}
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 7e07a0721..8620c5f01 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -588,6 +588,32 @@ class ProjectStoreImpl {
}
}
+ /** Per-platform packaging config (appid / app id / orientation), or {}. */
+ platformPackaging(): NonNullable<ProjectPackaging['platforms']> {
+ return this.state?.packaging?.platforms ?? {};
+ }
+
+ /** Persist one platform's packaging config (merged) to `project.esproject`. */
+ async setPlatformPackaging<K extends keyof NonNullable<ProjectPackaging['platforms']>>(
+ platform: K,
+ patch: Partial<NonNullable<NonNullable<ProjectPackaging['platforms']>[K]>>,
+ ): Promise<void> {
+ const st = this.state;
+ if (!st) return;
+ const prev = st.packaging?.platforms ?? {};
+ const platforms = { ...prev, [platform]: { ...prev[platform], ...patch } } as NonNullable<ProjectPackaging['platforms']>;
+ const packaging: ProjectPackaging = { ...st.packaging, platforms };
+ this.store.setState({ project: { ...st, packaging } });
+ try {
+ const raw = JSON.parse(await window.estella.fs.read(PROJECT_MANIFEST_FILE)) as Record<string, unknown>;
+ raw.packaging = packaging;
+ await window.estella.fs.write(PROJECT_MANIFEST_FILE, JSON.stringify(raw, null, 2) + '\n');
+ } catch (e) {
+ Toasts.push('Failed to save platform settings', 'error');
+ console.error('[project] setPlatformPackaging write failed', e);
+ }
+ }
+
/**
* Enable/configure the project's physics feature and persist to
* `project.esproject` (so the play realm installs physics even for
diff --git a/desktop/src/project/format.ts b/desktop/src/project/format.ts
index 903dbea75..aa2b0475f 100644
--- a/desktop/src/project/format.ts
+++ b/desktop/src/project/format.ts
@@ -76,8 +76,15 @@ export interface ProjectFeatures {
};
}
+export type ScreenOrientation = 'portrait' | 'landscape';
+/** Per-platform packaging config (the platform-specific Project Settings pages). */
+export interface WeChatPackaging { appid?: string; orientation?: ScreenOrientation; }
+export interface DesktopPackaging { appId?: string; productName?: string; }
+export interface PlayablePackaging { orientation?: ScreenOrientation; }
+
/** Persisted Package Project settings (UE's ProjectPackagingSettings analog) —
- * committed with the project so the build dialog restores the last target/config. */
+ * committed with the project so the build dialog restores the last target/config
+ * and the export reads per-platform config. */
export interface ProjectPackaging {
platform?: 'web' | 'desktop' | 'wechat' | 'playable';
config?: 'development' | 'shipping';
@@ -85,6 +92,8 @@ export interface ProjectPackaging {
openFolder?: boolean;
/** Per-platform output-dir overrides (else the per-platform default). */
outDir?: Partial<Record<'web' | 'desktop' | 'wechat' | 'playable', string>>;
+ /** Per-platform packaging config (appid, app id, orientation, …). */
+ platforms?: { wechat?: WeChatPackaging; desktop?: DesktopPackaging; playable?: PlayablePackaging };
}
/** Committed project identity + config (`project.esproject`). */
@@ -235,6 +244,31 @@ export function parseManifest(raw: unknown): ProjectManifest {
}
if (Object.keys(out).length > 0) pkg.outDir = out;
}
+ if (p.platforms && typeof p.platforms === 'object') {
+ const pl = p.platforms as Record<string, unknown>;
+ const platforms: NonNullable<ProjectPackaging['platforms']> = {};
+ const wx = pl.wechat as Record<string, unknown> | undefined;
+ if (wx && typeof wx === 'object') {
+ const w: WeChatPackaging = {};
+ if (typeof wx.appid === 'string') w.appid = wx.appid;
+ if (wx.orientation === 'portrait' || wx.orientation === 'landscape') w.orientation = wx.orientation;
+ if (Object.keys(w).length > 0) platforms.wechat = w;
+ }
+ const dt = pl.desktop as Record<string, unknown> | undefined;
+ if (dt && typeof dt === 'object') {
+ const d: DesktopPackaging = {};
+ if (typeof dt.appId === 'string') d.appId = dt.appId;
+ if (typeof dt.productName === 'string') d.productName = dt.productName;
+ if (Object.keys(d).length > 0) platforms.desktop = d;
+ }
+ const pa = pl.playable as Record<string, unknown> | undefined;
+ if (pa && typeof pa === 'object') {
+ const a: PlayablePackaging = {};
+ if (pa.orientation === 'portrait' || pa.orientation === 'landscape') a.orientation = pa.orientation;
+ if (Object.keys(a).length > 0) platforms.playable = a;
+ }
+ if (Object.keys(platforms).length > 0) pkg.platforms = platforms;
+ }
if (Object.keys(pkg).length > 0) manifest.packaging = pkg;
}
return manifest;
diff --git a/desktop/src/settings/projectSettings.ts b/desktop/src/settings/projectSettings.ts
index a4b91c5bd..7f90e8eff 100644
--- a/desktop/src/settings/projectSettings.ts
+++ b/desktop/src/settings/projectSettings.ts
@@ -80,6 +80,67 @@ settingsRegistry.register({
},
});
+// ── Packaging (per-platform Project Settings; read by the export, persisted to project.esproject) ──
+settingsRegistry.registerSection({ id: 'packaging', label: 'Packaging', category: 'project', order: 3 });
+
+const ORIENTATION = [{ value: 'portrait', label: 'Portrait' }, { value: 'landscape', label: 'Landscape' }];
+
+settingsRegistry.register({
+ id: 'project.packaging.wechat.appid',
+ type: 'string', scope: 'project', section: 'packaging', group: 'WeChat',
+ label: 'AppID',
+ description: 'Your WeChat MiniGame appid — written into project.config.json on export.',
+ placeholder: 'wx0123456789abcdef', default: '',
+ bind: {
+ get: () => ProjectStore.platformPackaging().wechat?.appid ?? '',
+ set: (v) => void ProjectStore.setPlatformPackaging('wechat', { appid: v }),
+ },
+});
+
+settingsRegistry.register({
+ id: 'project.packaging.wechat.orientation',
+ type: 'enum', scope: 'project', section: 'packaging', group: 'WeChat',
+ label: 'Orientation', options: ORIENTATION, segmented: true, default: 'portrait',
+ bind: {
+ get: () => ProjectStore.platformPackaging().wechat?.orientation ?? 'portrait',
+ set: (v) => void ProjectStore.setPlatformPackaging('wechat', { orientation: v as 'portrait' | 'landscape' }),
+ },
+});
+
+settingsRegistry.register({
+ id: 'project.packaging.desktop.appId',
+ type: 'string', scope: 'project', section: 'packaging', group: 'Desktop',
+ label: 'App ID',
+ description: 'Reverse-DNS id for the installer (electron-builder appId), e.g. com.studio.game.',
+ placeholder: 'com.studio.game', default: '',
+ bind: {
+ get: () => ProjectStore.platformPackaging().desktop?.appId ?? '',
+ set: (v) => void ProjectStore.setPlatformPackaging('desktop', { appId: v }),
+ },
+});
+
+settingsRegistry.register({
+ id: 'project.packaging.desktop.productName',
+ type: 'string', scope: 'project', section: 'packaging', group: 'Desktop',
+ label: 'Product name',
+ description: 'Display name for the desktop app + installer (defaults to the project name).',
+ placeholder: '(project name)', default: '',
+ bind: {
+ get: () => ProjectStore.platformPackaging().desktop?.productName ?? '',
+ set: (v) => void ProjectStore.setPlatformPackaging('desktop', { productName: v }),
+ },
+});
+
+settingsRegistry.register({
+ id: 'project.packaging.playable.orientation',
+ type: 'enum', scope: 'project', section: 'packaging', group: 'Playable',
+ label: 'Orientation', options: ORIENTATION, segmented: true, default: 'portrait',
+ bind: {
+ get: () => ProjectStore.platformPackaging().playable?.orientation ?? 'portrait',
+ set: (v) => void ProjectStore.setPlatformPackaging('playable', { orientation: v as 'portrait' | 'landscape' }),
+ },
+});
+
settingsRegistry.register({
id: 'project.physics.gravityY',
type: 'number',
diff --git a/desktop/src/settings/types.ts b/desktop/src/settings/types.ts
index 9f023687c..4d233741b 100644
--- a/desktop/src/settings/types.ts
+++ b/desktop/src/settings/types.ts
@@ -64,6 +64,12 @@ export interface EnumSetting extends BaseSetting<string> {
segmented?: boolean;
}
+/** A single-line free-text setting (e.g. a WeChat appid, a desktop product name). */
+export interface StringSetting extends BaseSetting<string> {
+ type: 'string';
+ placeholder?: string;
+}
+
export interface ColorSetting extends BaseSetting<string> {
type: 'color';
/** Preset swatches (hex). */
@@ -89,6 +95,7 @@ export type Setting =
| BooleanSetting
| NumberSetting
| EnumSetting
+ | StringSetting
| ColorSetting
| KeybindingSetting
| StringListSetting;
diff --git a/desktop/src/theme/settings.css b/desktop/src/theme/settings.css
index 4c03e10a4..6110d2068 100644
--- a/desktop/src/theme/settings.css
+++ b/desktop/src/theme/settings.css
@@ -153,6 +153,9 @@
.set-list-item { height: 24px; min-width: 0; background: var(--inset); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 0 7px; color: var(--text); font-size: var(--fs-xs); outline: none; }
.set-list-item:focus { border-color: var(--acc); box-shadow: 0 0 0 2px var(--acc-soft); }
.set-list-item::placeholder { color: var(--text-mute); }
+.set-str { width: 200px; height: 24px; background: var(--inset); border: 1px solid var(--border); border-radius: var(--r-sm); padding: 0 7px; color: var(--text); font-size: var(--fs-xs); font-family: var(--mono); outline: none; }
+.set-str:focus { border-color: var(--acc); box-shadow: 0 0 0 2px var(--acc-soft); }
+.set-str::placeholder { color: var(--text-mute); font-family: var(--sans, inherit); }
.set-reset { width: 16px; height: 16px; display: grid; place-items: center; color: var(--warn); opacity: 0; }
.set-row:hover .set-reset.show, .set-row.changed .set-reset.show { opacity: 0.85; }
.set-reset.show { cursor: pointer; }
diff --git a/desktop/tests/export-desktop.test.ts b/desktop/tests/export-desktop.test.ts
index 3bf21b3a2..418111c8d 100644
--- a/desktop/tests/export-desktop.test.ts
+++ b/desktop/tests/export-desktop.test.ts
@@ -57,6 +57,8 @@ describe('exportGame (desktop)', () => {
outDir: out,
title: 'My Cool Game',
platform: 'desktop',
+ desktopAppId: 'com.studio.cool',
+ desktopProductName: 'Cool Override',
});
expect(res.ok).toBe(true);
@@ -81,8 +83,9 @@ describe('exportGame (desktop)', () => {
expect(pkg.main).toBe('main.cjs');
expect(pkg.scripts.start).toBe('electron .');
expect(pkg.scripts.dist).toBe('electron-builder');
- expect(pkg.build.productName).toBe('My Cool Game');
- expect(pkg.name).toBe('my-cool-game'); // slugified
+ expect(pkg.build.appId).toBe('com.studio.cool'); // from Project Settings
+ expect(pkg.build.productName).toBe('Cool Override');
+ expect(pkg.name).toBe('cool-override'); // slugified from product name
expect(pkg.build.files).toContain('app/**/*');
expect(existsSync(path.join(out, 'README.md'))).toBe(true);
diff --git a/desktop/tests/export-wechat.test.ts b/desktop/tests/export-wechat.test.ts
index c9259a5d0..02292858c 100644
--- a/desktop/tests/export-wechat.test.ts
+++ b/desktop/tests/export-wechat.test.ts
@@ -58,6 +58,8 @@ describe('exportGame (wechat)', () => {
outDir: out,
title: 'My Game',
platform: 'wechat',
+ wechatAppid: 'wxTEST0123456789',
+ wechatOrientation: 'landscape',
});
expect(res.ok).toBe(true);
@@ -86,7 +88,9 @@ describe('exportGame (wechat)', () => {
const pcfg = JSON.parse(readFileSync(path.join(out, 'project.config.json'), 'utf8'));
expect(pcfg.compileType).toBe('game');
expect(pcfg.projectname).toBe('My Game');
- expect(existsSync(path.join(out, 'game.json'))).toBe(true);
+ expect(pcfg.appid).toBe('wxTEST0123456789'); // from Project Settings → Packaging
+ const gjson = JSON.parse(readFileSync(path.join(out, 'game.json'), 'utf8'));
+ expect(gjson.deviceOrientation).toBe('landscape');
expect(existsSync(path.join(out, 'wasm', 'esengine.js'))).toBe(true);
expect(existsSync(path.join(out, 'wasm', 'esengine.wasm'))).toBe(true);
}, 60_000);
diff --git a/desktop/tests/project-packaging.test.ts b/desktop/tests/project-packaging.test.ts
index 272414a96..6ea6f7947 100644
--- a/desktop/tests/project-packaging.test.ts
+++ b/desktop/tests/project-packaging.test.ts
@@ -29,4 +29,27 @@ describe('parseManifest — packaging', () => {
it('omits packaging when absent', () => {
expect(parseManifest({ name: 'X' }).packaging).toBeUndefined();
});
+
+ it('parses per-platform packaging config, dropping unknown fields', () => {
+ const m = parseManifest({
+ name: 'X',
+ packaging: {
+ platforms: {
+ wechat: { appid: 'wx123', orientation: 'landscape', junk: 1 },
+ desktop: { appId: 'com.x.y', productName: 'Y', extra: 'z' },
+ playable: { orientation: 'portrait' },
+ },
+ },
+ });
+ expect(m.packaging?.platforms).toEqual({
+ wechat: { appid: 'wx123', orientation: 'landscape' },
+ desktop: { appId: 'com.x.y', productName: 'Y' },
+ playable: { orientation: 'portrait' },
+ });
+ });
+
+ it('drops invalid orientation + empty platform objects', () => {
+ const m = parseManifest({ name: 'X', packaging: { platforms: { wechat: { orientation: 'diagonal' }, desktop: {} } } });
+ expect(m.packaging).toBeUndefined(); // nothing valid survives
+ });
});