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(editor): the desktop runtime templates can be downloaded

esengine2f14701e4d40
diff --git a/build-tools/utils/nativeTemplate.d.ts b/build-tools/utils/nativeTemplate.d.ts
index 4645e5ddf..f1cfd9f15 100644
--- a/build-tools/utils/nativeTemplate.d.ts
+++ b/build-tools/utils/nativeTemplate.d.ts
@@ -7,13 +7,19 @@
/** Every platform a runtime template exists for. `macos` is one of them because a
* desktop package is assembled from a template exactly as a phone's is — that
* sameness is the point (see docs/REARCH_STEAM.md §6.0). */
-export type NativePlatform = 'android' | 'ios' | 'macos' | 'windows' | 'linux';
+/**
+ * Every platform a runtime TEMPLATE is published for. Distinct from the export
+ * target vocabulary in desktop/src/project/platforms.ts, which spells the three
+ * desktop OSes as one `desktop` target — the two shared the name `NativePlatform`,
+ * and every layer above hand-narrowed this one back to the mobile pair.
+ */
+export type TemplatePlatform = 'android' | 'ios' | 'macos' | 'windows' | 'linux';
export interface NativeTemplateManifest {
kind: 'estella-native-template';
formatVersion: number;
id: string;
- platform: NativePlatform;
+ platform: TemplatePlatform;
/** Android only: the architectures this template carries. */
abis?: string[];
/** Matched EXACTLY against the editor's version: the SDK bundle is compiled
@@ -27,7 +33,7 @@ export interface NativeTemplateManifest {
}
export interface TemplateWant {
- platform: NativePlatform;
+ platform: TemplatePlatform;
engineVersion: string;
}
@@ -43,12 +49,12 @@ export const TEMPLATE_MANIFEST: string;
export const BYTECODE_FILE: string;
export const ANDROID_ABIS: readonly string[];
-export function templateId(platform: NativePlatform): string;
+export function templateId(platform: TemplatePlatform): TemplatePlatform;
/** Every platform a template is built and published for — the one list the
* layouts and the release verifier both ask. */
-export const TEMPLATE_PLATFORMS: readonly NativePlatform[];
-export function isTemplatePlatform(platform: unknown): platform is NativePlatform;
+export const TEMPLATE_PLATFORMS: readonly TemplatePlatform[];
+export function isTemplatePlatform(platform: unknown): platform is TemplatePlatform;
export function templateAbis(dir: string): string[];
export interface TemplateEntry {
/** Path inside the template. */
@@ -61,31 +67,31 @@ export interface TemplateEntry {
produced?: boolean;
}
-export function templateLayout(platform: NativePlatform, options?: { abis?: readonly string[] }): TemplateEntry[];
-export function requiredTemplateFiles(platform: NativePlatform, options?: { abis?: readonly string[]; release?: boolean }): string[];
-export function missingTemplateFiles(dir: string, platform: NativePlatform, options?: { abis?: readonly string[] }): string[];
+export function templateLayout(platform: TemplatePlatform, options?: { abis?: readonly string[] }): TemplateEntry[];
+export function requiredTemplateFiles(platform: TemplatePlatform, options?: { abis?: readonly string[]; release?: boolean }): string[];
+export function missingTemplateFiles(dir: string, platform: TemplatePlatform, options?: { abis?: readonly string[] }): string[];
/** The same question asked of a NAME LIST rather than a directory — what a zip
* is missing, checked before it is unpacked. */
export function missingTemplateEntries(
names: readonly string[],
- platform: NativePlatform,
+ platform: TemplatePlatform,
options?: { abis?: readonly string[]; release?: boolean },
): string[];
export function writeTemplateManifest(
dir: string,
- meta: { platform: NativePlatform; engineVersion: string; abi?: string } & Record<string, unknown>,
+ meta: { platform: TemplatePlatform; engineVersion: string; abi?: string } & Record<string, unknown>,
): NativeTemplateManifest;
export function readTemplateManifest(dir: string): NativeTemplateManifest | null;
export function templateMatches(manifest: NativeTemplateManifest | null, want: TemplateWant): boolean;
-export function templateZipName(platform: NativePlatform, engineVersion: string): string;
+export function templateZipName(platform: TemplatePlatform, engineVersion: string): string;
export function estellaDataDir(): string;
export function templateStoreDir(): string;
export function installedTemplateDir(
- engineVersion: string, platform: NativePlatform, storeDir?: string): string;
+ engineVersion: string, platform: TemplatePlatform, storeDir?: string): string;
export function findTemplate(want: TemplateWant, storeDir?: string): FoundTemplate | null;
export interface PublishedTemplate {
id: string;
- platform: NativePlatform;
+ platform: TemplatePlatform;
/** Archive filename, resolved against the release's asset base. */
file: string;
bytes: number;
@@ -121,7 +127,7 @@ export function androidTemplateSources(dir: string): {
bytecode: string;
};
-export function desktopTemplateSources(dir: string, platform?: NativePlatform): {
+export function desktopTemplateSources(dir: string, platform?: TemplatePlatform): {
/** The runtime binary; the assembler renames it to the app. */
executable: string;
infoPlistIn: string;
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 4caa6935f..3773edb47 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -36,8 +36,9 @@ import { importAssets, createAsset, IMPORT_EXTENSIONS } from './importAssets';
import { exportGame } from './exportGame';
import {
iosSourcesFromTemplate, resolveNativeTemplate, installNativeTemplate, listNativeTemplates,
- removeNativeTemplate, downloadNativeTemplate,
+ removeNativeTemplate, downloadNativeTemplate, type TemplatePlatform,
} from './nativeTemplates';
+import { isTemplatePlatform } from '../../build-tools/utils/nativeTemplate.js';
import { DESKTOP_OSES } from '../src/project/platforms';
import { loopbackServer, closeAllLoopbackServers } from './loopbackServer';
import { httpContentType } from './mimeTypes';
@@ -1432,16 +1433,19 @@ ipcMain.handle('nativeTemplates:install', async () => {
if (res.canceled || res.filePaths.length === 0) return { ok: false, canceled: true };
return installNativeTemplate(res.filePaths[0], app.getVersion());
});
-ipcMain.handle('nativeTemplates:remove', (_e, platform: 'android' | 'ios', version: string) =>
- removeNativeTemplate(platform, version),
+ipcMain.handle('nativeTemplates:remove', (_e, platform: TemplatePlatform, version: string) =>
+ (isTemplatePlatform(platform) ? removeNativeTemplate(platform, version) : false),
);
// Download + install this editor version's template. Progress is pushed rather
// than polled: the renderer drew the button, so it owns the progress bar.
-ipcMain.handle('nativeTemplates:download', (e, platform: 'android' | 'ios') =>
- downloadNativeTemplate(platform, app.getVersion(), {
+ipcMain.handle('nativeTemplates:download', (e, platform: TemplatePlatform) => {
+ // Validated at the trust boundary against the list that publishes them, so no
+ // caller has to keep its own copy of which platforms have a template.
+ if (!isTemplatePlatform(platform)) return { ok: false, error: `no runtime template for "${platform}"` };
+ return downloadNativeTemplate(platform, app.getVersion(), {
onProgress: (p) => e.sender.send('nativeTemplates:downloadProgress', { platform, ...p }),
- }),
-);
+ });
+});
// New-project templates + creation (launcher New tab).
ipcMain.handle('templates:list', () => listTemplates());
diff --git a/desktop/electron/nativeTemplates.ts b/desktop/electron/nativeTemplates.ts
index 17b3dd0d7..92a2b0b3d 100644
--- a/desktop/electron/nativeTemplates.ts
+++ b/desktop/electron/nativeTemplates.ts
@@ -23,11 +23,11 @@ import {
findTemplate, readTemplateManifest, missingTemplateFiles, installedTemplateDir,
templateStoreDir, iosTemplateSources, releaseAssetBases, parseTemplateIndex,
TEMPLATE_INDEX,
- type NativePlatform, type NativeTemplateManifest,
+ type TemplatePlatform, type NativeTemplateManifest,
} from '../../build-tools/utils/nativeTemplate.js';
import { extractZip } from '../../build-tools/utils/zip.js';
-export type { NativePlatform, NativeTemplateManifest };
+export type { TemplatePlatform, NativeTemplateManifest };
/** A template this editor can actually use, with where it came from. */
export interface UsableTemplate {
@@ -42,7 +42,7 @@ export interface UsableTemplate {
* A template whose files are incomplete counts as absent: half a template
* produces an app that fails to link, which is worse than one that is not offered.
*/
-export function resolveNativeTemplate(platform: NativePlatform, engineVersion: string): UsableTemplate | null {
+export function resolveNativeTemplate(platform: TemplatePlatform, engineVersion: string): UsableTemplate | null {
const found = findTemplate({ platform, engineVersion });
if (!found || found.missing.length > 0) return null;
return { dir: found.dir, manifest: found.manifest };
@@ -164,7 +164,7 @@ export interface TemplateDownloadProgress {
* Never throws: every failure is a message on the row that offered the button.
*/
export async function downloadNativeTemplate(
- platform: NativePlatform,
+ platform: TemplatePlatform,
engineVersion: string,
options: {
onProgress?: (progress: TemplateDownloadProgress) => void;
@@ -191,7 +191,7 @@ export async function downloadNativeTemplate(
async function downloadFrom(
base: string,
- platform: NativePlatform,
+ platform: TemplatePlatform,
engineVersion: string,
fetchImpl: typeof fetch,
onProgress?: (progress: TemplateDownloadProgress) => void,
@@ -242,7 +242,7 @@ async function downloadFrom(
/** Delete an installed template. Takes the id + version rather than a path, so a
* renderer can never ask the main process to remove an arbitrary directory. */
-export function removeNativeTemplate(platform: NativePlatform, engineVersion: string): boolean {
+export function removeNativeTemplate(platform: TemplatePlatform, engineVersion: string): boolean {
const dir = installedTemplateDir(engineVersion, platform);
if (!readTemplateManifest(dir)) return false;
rmSync(dir, { recursive: true, force: true });
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 390a8143e..f508840b5 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -18,7 +18,7 @@ import type { DetectedEditor } from './editorCatalog';
import type { DiscoveredPlugin, CompiledPlugin } from './pluginHost';
import type { ScaffoldPluginOptions, ScaffoldPluginResult } from './pluginScaffold';
import type { PluginPackageInfo, InstallPluginResult } from './pluginPackage';
-import type { NativeTemplateEntry, InstallResult } from './nativeTemplates';
+import type { NativeTemplateEntry, InstallResult, TemplatePlatform } from './nativeTemplates';
import type { McpEndpointStatus } from './mcpEndpoint';
import type { SecretStatus } from './secrets';
import type { AgentStatus, AgentMessage } from './agent/host';
@@ -358,10 +358,10 @@ const api = {
/** Pick an archive and install it. Main owns the file dialog, so the renderer
* never handles a path it could have made up. */
install: (): Promise<InstallResult & { canceled?: boolean }> => ipcRenderer.invoke('nativeTemplates:install'),
- remove: (platform: 'android' | 'ios', version: string): Promise<boolean> =>
+ remove: (platform: TemplatePlatform, version: string): Promise<boolean> =>
ipcRenderer.invoke('nativeTemplates:remove', platform, version),
/** Fetch this editor version's template from the release and install it. */
- download: (platform: 'android' | 'ios'): Promise<InstallResult> =>
+ download: (platform: TemplatePlatform): Promise<InstallResult> =>
ipcRenderer.invoke('nativeTemplates:download', platform),
/** Subscribe to download progress; returns an unsubscribe. */
onDownloadProgress: (cb: (p: { platform: string; received: number; total: number }) => void): (() => void) => {
diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsx
index e397a0df0..bbec2b67c 100644
--- a/desktop/src/components/BuildDialog.tsx
+++ b/desktop/src/components/BuildDialog.tsx
@@ -36,6 +36,7 @@ import {
import type { ExportPlatform, NativeToolchain, PlatformPrereq } from '@/project/platforms';
import { platformLabel } from '@/project/platformLabels';
import type { PlayableNetworkOption } from '../../electron/platformCatalog';
+import type { TemplatePlatform } from '../../electron/nativeTemplates';
import type { BuildSizeReport } from '../../electron/sizeReport';
import { formatBytes } from '@/project/sizeBudget';
import { BuildSizePanel } from '@/components/BuildSizePanel';
@@ -118,9 +119,9 @@ interface PlatformDef {
/** What KIND of prerequisite — a missing engine runtime blocks the package, a
* missing native toolchain only blocks the final app assembly. */
prereqKind?: PlatformPrereq['kind'];
- /** The runtime template this target wants, when that is what is missing. Kept so
- * the install action can say which version a wrong archive should have been. */
- templateWant?: { id: string; version: string };
+ /** The runtime template this target wants, when that is what is missing — the
+ * id the download asks for, and the version a wrong archive should have been. */
+ templateWant?: { id: TemplatePlatform; version: string };
/** http-servable target → offer a loopback-http Preview (opening the build via
* file:// hits the browser's opaque-origin rules; http is its real surface). */
httpPreview?: boolean;
@@ -505,9 +506,12 @@ export function BuildDialog() {
afterTemplate(res);
};
- /** Fetch it from this version's release. */
- const downloadTemplate = async (platform: string) => {
- if (platform !== 'android' && platform !== 'ios') return;
+ /** Fetch it from this version's release.
+ *
+ * Takes the id the PREREQUISITE named, not the export target: `desktop` is one
+ * target and three templates, and asking by target is how this button did
+ * nothing at all on Windows, macOS and Linux. */
+ const downloadTemplate = async (platform: TemplatePlatform) => {
setTemplateNote(null);
setDownloading({ received: 0, total: 0 });
try {
@@ -772,7 +776,7 @@ export function BuildDialog() {
</span>
{def.prereqKind === 'template-missing' && (
<div className="build__fix">
- <Button variant="primary" disabled={!!downloading} onClick={() => void downloadTemplate(def.id)}>
+ <Button variant="primary" disabled={!!downloading} onClick={() => void downloadTemplate(def.templateWant!.id)}>
{downloading
? <><Loader2 size={12} className="spin" /> {downloading.total > 0
? t('build.downloadingTemplatePct', {
diff --git a/desktop/src/project/platforms.ts b/desktop/src/project/platforms.ts
index 94dc50606..1ea76fcfc 100644
--- a/desktop/src/project/platforms.ts
+++ b/desktop/src/project/platforms.ts
@@ -65,6 +65,10 @@ export function isNativePlatform(platform: ExportPlatform): platform is NativePl
* signing a macOS bundle is, and that is a warning on one output rather than a
* reason to withhold the others.
*/
+/** Every platform a runtime template is published for — the mobile hosts plus
+ * each desktop OS. Mirrors build-tools' TemplatePlatform; a test pins them equal. */
+export type TemplatePlatform = 'android' | 'ios' | DesktopOs;
+
export const DESKTOP_OSES = ['windows', 'macos', 'linux'] as const;
export type DesktopOs = (typeof DESKTOP_OSES)[number];
@@ -130,8 +134,10 @@ export type PlatformPrereq =
* it is an artifact this editor release ships, installed once.
*/
kind: 'template-missing';
- /** The template looked for (`ios-arm64`). */
- id: string;
+ /** The template looked for, in the vocabulary the release PUBLISHES them
+ * in (`windows`, not the `desktop` target it belongs to) — this is the id
+ * the download asks for. */
+ id: TemplatePlatform;
/** The version it must carry — this editor's. A template is matched exactly:
* the SDK bundle is compiled into the app binary. */
version: string;
diff --git a/desktop/tests/native-template.test.ts b/desktop/tests/native-template.test.ts
index baabe8c2b..f5563fd4b 100644
--- a/desktop/tests/native-template.test.ts
+++ b/desktop/tests/native-template.test.ts
@@ -23,7 +23,7 @@ import {
requiredTemplateFiles, templateLayout, installedTemplateDir, parseTemplateIndex,
missingTemplateEntries, isTemplatePlatform,
TEMPLATE_FORMAT, TEMPLATE_MANIFEST, TEMPLATE_INDEX, TEMPLATE_PLATFORMS,
- type NativePlatform,
+ type TemplatePlatform,
} from '../../build-tools/utils/nativeTemplate.js';
import { verifyTemplateZip } from '../../build-tools/tasks/verifyTemplate.js';
import { makeZip } from '../../build-tools/utils/zip.js';
@@ -46,8 +46,10 @@ afterEach(() => {
/** Every file the layout declares required, with a stand-in body — so the fixture
* follows the contract rather than a copy of it that can go stale. */
-function templateEntries(version: string, omit?: string): { name: string; data: Buffer }[] {
- const entries = requiredTemplateFiles('ios')
+function templateEntries(
+ version: string, omit?: string, platform: TemplatePlatform = 'ios',
+): { name: string; data: Buffer }[] {
+ const entries = requiredTemplateFiles(platform)
.filter((rel) => rel !== omit)
.map((rel) => ({ name: rel, data: Buffer.from(`stand-in for ${rel}`) }));
entries.push({
@@ -55,8 +57,8 @@ function templateEntries(version: string, omit?: string): { name: string; data:
data: Buffer.from(JSON.stringify({
kind: 'estella-native-template',
formatVersion: TEMPLATE_FORMAT,
- id: 'ios',
- platform: 'ios',
+ id: platform,
+ platform,
engineVersion: version,
spineVersion: '4.2',
deploymentTarget: '17.0',
@@ -65,9 +67,9 @@ function templateEntries(version: string, omit?: string): { name: string; data:
return entries;
}
-function writeTemplateZip(version: string, omit?: string): string {
- const file = path.join(scratch, `template-${version}.zip`);
- writeFileSync(file, makeZip(templateEntries(version, omit)));
+function writeTemplateZip(version: string, omit?: string, platform: TemplatePlatform = 'ios'): string {
+ const file = path.join(scratch, `template-${version}-${platform}.zip`);
+ writeFileSync(file, makeZip(templateEntries(version, omit, platform)));
return file;
}
@@ -178,6 +180,42 @@ describe('downloading a template from a release', () => {
return { fetchImpl, served, zip };
}
+ // Desktop templates are published per OS, and the download path takes them by
+ // that name rather than by the one export target they share.
+ it('installs a DESKTOP template, which is published per OS', async () => {
+ const zip = readFileSync(writeTemplateZip(VERSION, undefined, 'windows'));
+ const index = {
+ kind: 'estella-native-templates',
+ formatVersion: TEMPLATE_FORMAT,
+ engineVersion: VERSION,
+ templates: [{
+ id: 'windows', platform: 'windows',
+ file: `estella-native-windows-${VERSION}.zip`,
+ bytes: zip.length,
+ sha256: createHash('sha256').update(zip).digest('hex'),
+ }],
+ };
+ const fetchImpl = (async (url: string) => (url.endsWith(TEMPLATE_INDEX)
+ ? { ok: true, status: 200, json: async () => index } as unknown as Response
+ : { ok: true, status: 200, body: (async function* () { yield zip; })() } as unknown as Response
+ )) as unknown as typeof fetch;
+
+ const res = await downloadNativeTemplate('windows', VERSION, { fetchImpl, baseUrl: 'https://example.test/r' });
+ expect(res).toMatchObject({ ok: true, id: 'windows' });
+ expect(resolveNativeTemplate('windows', VERSION)).not.toBeNull();
+ });
+
+ // `desktop` is an export target, not a template platform: the index publishes
+ // three desktop templates and none of them under that name.
+ it('says so when asked for a platform no template is published for', async () => {
+ const { fetchImpl } = release();
+ const res = await downloadNativeTemplate('desktop' as TemplatePlatform, VERSION, {
+ fetchImpl, baseUrl: 'https://example.test/r',
+ });
+ expect(res.ok).toBe(false);
+ expect(res.error).toContain('no desktop template');
+ });
+
it('installs what the index describes, and reports progress on the way', async () => {
const { fetchImpl, served, zip } = release();
const progress: number[] = [];
@@ -342,7 +380,7 @@ describe('what a PUBLISHED template must carry', () => {
describe('the platforms templates are published for', () => {
/** A release-complete archive for any platform, built from that platform's own
* layout so the fixture follows the contract instead of restating it. */
- function releaseZip(platform: NativePlatform): Buffer {
+ function releaseZip(platform: TemplatePlatform): Buffer {
const entries = requiredTemplateFiles(platform, { release: true })
.map((rel: string) => ({ name: rel, data: Buffer.from(`stand-in for ${rel}`) }));
entries.push({
@@ -367,7 +405,7 @@ describe('the platforms templates are published for', () => {
expect(templateLayout(p).length).toBeGreaterThan(0);
}
expect(isTemplatePlatform('playstation')).toBe(false);
- expect(() => templateLayout('playstation' as NativePlatform)).toThrow();
+ expect(() => templateLayout('playstation' as TemplatePlatform)).toThrow();
});
it('are each accepted by the release verifier', () => {