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
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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', () => {