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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// The runtime template contract — what a prebuilt native runtime IS, and where it
// lives once installed.
//
// A native app's binary carries no project data: the export is content only, and
// `native/CMakeLists.txt` takes no project input (every ES_ENABLE_* is on, and the
// optional runtimes are linked in). So the compiled half is the SAME for every
// game, and belongs in an artifact built once per release rather than on each
// user's machine. That artifact is a runtime template.
//
// This module is the ONE place that names the files in one: the emitter writes
// what the table says, the editor looks for what the table says, and a template
// that satisfies the table is usable by definition. Plain ESM because both halves
// read it — build-tools and the packaged editor.
import path from 'path';
import { existsSync, readFileSync, writeFileSync } from 'fs';
/** Bumped when the LAYOUT changes shape — an older template is then refused by
* name instead of failing halfway through an assembly. */
export const TEMPLATE_FORMAT = 1;
export const TEMPLATE_MANIFEST = 'template.json';
/** The shipped bytecode's filename. NOT `.bc`: that is LLVM bitcode's extension,
* and aapt2 treats a `.bc` asset as RenderScript output — which silently drops
* the APK's native-code declaration, so the package installs nowhere. */
export const BYTECODE_FILE = 'esengine.native.qjsbc';
/**
* The launcher icon an app gets when the project does not set one.
*
* In the template rather than in the editor because the CLI packages without an
* editor, and shipped at all because the alternative — the platform's default —
* is a green robot on a published game.
*/
export const DEFAULT_ICON = 'icon.png';
/**
* The HLSL compiler Dawn's D3D backend loads before it can create a device.
*
* It ships WITH the game rather than being taken from System32: Dawn's own note
* says the OS copy has functionality and heap-corruption bugs on older Windows,
* so a game carries the SDK's. Dawn looks beside the executable first.
*/
export const D3D_COMPILER = 'd3dcompiler_47.dll';
/**
* What a V8 desktop host loads beside itself on Windows: V8 is a set of DLLs plus
* the Intl data its build carries. All or none — a QuickJS host has none of them,
* and a V8 host missing one does not start (see native/host/js/esjs_v8.cpp).
*/
export const V8_WINDOWS_RUNTIME = [
'v8.dll', 'v8_libbase.dll', 'v8_libplatform.dll', 'icuuc.dll', 'icui18n.dll', 'zlib.dll', 'icudtl.dat',
];
/** The V8 an Android V8 host links, one per ABI beside the host library. */
export const V8_ANDROID_LIBRARY = 'libv8android.so';
/**
* PhysX, as the Android host's optional library (native/CMakeLists.txt). The
* template keeps it under `plugins/<abi>/`, outside the `lib/` every package
* copies, so a package carries it only when its project's 3D solver is PhysX
* ({@link androidPhysXLibs}); the host dlopens it by name when it is there.
*/
export const ANDROID_PHYSX_LIBRARY = 'libestella_physx.so';
/**
* PhysX's library for each of `abis`, for a package's `lib/<abi>/` — or null when
* the template carries none (a host built with -DESTELLA_PHYSX=OFF), in which case
* a PhysX project runs on Jolt and its log says so.
*
* @param {string} dir An installed android template.
* @param {string[]} abis The ABIs the package carries.
* @returns {Record<string, string[]> | null}
*/
export function androidPhysXLibs(dir, abis) {
const found = abis
.map((abi) => [abi, path.join(dir, 'plugins', abi, ANDROID_PHYSX_LIBRARY)])
.filter(([, file]) => existsSync(file));
return found.length === 0 ? null : Object.fromEntries(found.map(([abi, file]) => [abi, [file]]));
}
/** Where an Android V8 host reads its startup snapshot from, inside the package's
* assets — the name native/CMakeLists.txt compiles in as ESJS_V8_SNAPSHOT_ASSET. */
export function v8SnapshotAsset(abi) {
return `v8/${abi}/snapshot_blob.bin`;
}
/** The JS engine a template's host embeds, read off the files it carries: 'v8'
* when the V8 runtime is there, 'quickjs' otherwise. */
export function templateJsEngine(dir, platform) {
if (platform === 'windows') return existsSync(path.join(dir, 'v8.dll')) ? 'v8' : 'quickjs';
if (platform === 'android') {
return ANDROID_ABIS.some((abi) => existsSync(path.join(dir, 'lib', abi, V8_ANDROID_LIBRARY)))
? 'v8' : 'quickjs';
}
return 'quickjs';
}
/** Steam's redistributable, per platform — the filename the host dlopens. */
export const STEAM_REDIST = {
windows: 'steam_api64.dll',
macos: 'libsteam_api.dylib',
linux: 'libsteam_api.so',
};
/**
* The redistributable inside a Steamworks SDK checkout, or null.
*
* The one place that knows an SDK's layout: the template build reads it here, and
* so does the assembler, which is where a project's own SDK reaches a package.
*/
export function steamRedistIn(sdkDir, platform) {
if (!sdkDir) return null;
const sub = { windows: 'win64', macos: 'osx', linux: 'linux64' }[platform];
const file = path.join(sdkDir, 'redistributable_bin', sub, STEAM_REDIST[platform]);
return existsSync(file) ? file : null;
}
/** Where the Windows SDK keeps the redistributable D3D compiler, newest first. */
function windowsSdkD3DRedist() {
const root = 'C:/Program Files (x86)/Windows Kits/10/Redist/D3D/x64';
return existsSync(path.join(root, D3D_COMPILER)) ? path.join(root, D3D_COMPILER) : null;
}
/**
* A template's id: ONE per platform.
*
* Not per architecture. A platform's template carries every architecture that
* platform needs — iOS already did, with the device and simulator slices inside
* one xcframework — so naming an architecture in the id would make a second
* architecture a second artifact the editor never asks for. Architectures are
* data inside a template, not an axis of them.
*/
export function templateId(platform) {
return platform;
}
/**
* Every platform a template is built and published for. One list, because the
* alternative already failed: the release gate kept its own pair of names while
* three desktop platforms landed in {@link templateLayout}, and the publish step
* then rejected three archives it had just built correctly.
*/
export const TEMPLATE_PLATFORMS = ['android', 'ios', 'macos', 'windows', 'linux'];
/** Whether {@link templateLayout} can describe this platform. */
export function isTemplatePlatform(platform) {
return TEMPLATE_PLATFORMS.includes(platform);
}
/**
* The Android ABIs a template can carry, in the order a package lists them.
* `arm64-v8a` is every real device; `x86_64` is the emulator, which is how anyone
* without a phone tries the game at all.
*
* The FIRST is required — a template with no device ABI packages nothing — and the
* rest are optional, so a build machine that only did one still produces a usable
* template.
*/
export const ANDROID_ABIS = ['arm64-v8a', 'x86_64'];
/**
* The ABIs a phone can run. A package carries only these unless it is asked for the
* emulator's too: x86_64 is the other half of the engine's size, and no player's device
* can use it.
*/
export const ANDROID_DEVICE_ABIS = ['arm64-v8a'];
/**
* What a template holds, per platform.
*
* `from` resolves the file in a BUILD TREE (the emitter's input); `rel` is where
* it sits inside the template (what every consumer sees). `strip` marks a binary
* whose debug info an app does not need — the host's is most of its size, and
* shipping it unstripped also broke installing onto a clean device.
*
* @param {'android'|'ios'|'macos'} platform
* @param {{abis?: readonly string[]}} [options] Android ABIs to describe.
*/
export function templateLayout(platform, options = {}) {
const abis = options.abis || ANDROID_ABIS;
if (platform === 'ios') {
return [
{
rel: 'Estella.xcframework', kind: 'dir',
from: (ctx) => path.join(ctx.root, 'build/cmake/native-ios', 'Estella.xcframework'),
},
{ rel: 'App/main.m', from: (ctx) => path.join(ctx.root, 'native', 'ios', 'App', 'main.m') },
// What an app target includes to answer the game from its own Objective-C
// or Swift; the class is in the xcframework.
{
rel: 'App/EstellaNativeChannel.h',
from: (ctx) => path.join(ctx.root, 'native', 'ios', 'App', 'EstellaNativeChannel.h'),
},
{ rel: 'App/Info.plist.in', from: (ctx) => path.join(ctx.root, 'native', 'ios', 'App', 'Info.plist.in') },
{ rel: DEFAULT_ICON, from: (ctx) => path.join(ctx.root, 'native', 'icon.png') },
// The same first-launch fix the Android template carries: without it the
// host parses the ~700 KB SDK bundle on first run, which is seconds of
// black screen after an install. A local build without it still works —
// a PUBLISHED one may not ship that first launch to every game made with
// it, so `release` requires what `optional` excuses.
{
rel: `assets/${BYTECODE_FILE}`, optional: true, releaseRequired: true,
from: (ctx) => path.join(ctx.root, 'build/cmake/native-ios', 'gen', BYTECODE_FILE),
},
];
}
if (platform === 'macos' || platform === 'windows' || platform === 'linux') {
const exe = platform === 'windows' ? 'estella_desktop.exe' : 'estella_desktop';
const buildDir = `build/cmake/native-${platform}`;
// The shortest layout of the three, because a desktop build embeds
// everything: Dawn and SDL are linked statically, so the runtime is one
// executable and there is no second file to find at run time.
return [
{
// MSVC leaves debug info in a separate .pdb, so there is nothing to
// strip out of the executable — and no signature to invalidate.
rel: exe, strip: platform === 'macos',
from: (ctx) => path.join(ctx.root, buildDir, exe),
},
// Beside the game's own files, not in a directory of its own: the host
// reads it through Platform::readAsset, which is one namespace — the
// same one the APK's assets/ is.
// QuickJS only: a V8 host compiles the bundle on the device (and caches
// it), so its template carries the V8 runtime instead and owes no bytecode.
{
rel: BYTECODE_FILE, optional: true, releaseRequired: true,
excusedBy: platform === 'windows' ? 'v8.dll' : undefined,
from: (ctx) => path.join(ctx.root, buildDir, 'gen', BYTECODE_FILE),
},
...(platform === 'windows' ? V8_WINDOWS_RUNTIME.map((rel) => ({
rel, optional: true,
from: (ctx) => path.join(ctx.root, buildDir, rel),
})) : []),
// The bundle description macOS wants; Windows has no counterpart, and
// an entry every consumer would have to check for is worse than a
// layout that differs where the platforms do.
...(platform === 'macos' ? [{
rel: 'Info.plist.in',
from: (ctx) => path.join(ctx.root, 'native', 'desktop', 'Info.plist.in'),
}] : []),
// Required to create a device at all, so a template without it produces
// an app that opens and immediately reports a lost device.
...(platform === 'windows' ? [{
rel: D3D_COMPILER, releaseRequired: true, optional: true,
from: () => windowsSdkD3DRedist(),
}] : []),
// Steam's redistributable, from an SDK on the BUILD machine
// (`--steam-sdk <dir>`) and never from this repository. Optional — a
// template without it still packages every game.
{
rel: STEAM_REDIST[platform], optional: true,
from: (ctx) => steamRedistIn(ctx.steamSdk, platform),
},
{ rel: DEFAULT_ICON, from: (ctx) => path.join(ctx.root, 'native', 'icon.png') },
];
}
if (platform === 'android') {
// Every ABI the build machine produced. Only the first is required: one
// architecture is a working template, two is one package that installs on a
// phone and in an emulator alike. A release builds both, so a release is
// held to both — losing the emulator ABI costs everyone without a phone
// their only way to run the game.
const libs = abis.flatMap((abi, n) => [
{
rel: `lib/${abi}/libestella_js_host.so`, strip: true, abi, optional: n > 0, releaseRequired: true,
from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, 'libestella_js_host.so'),
},
{
rel: `lib/${abi}/libwebgpu_dawn.so`, strip: true, abi, optional: n > 0, releaseRequired: true,
from: (ctx) => ctx.dawnLibrary?.(abi),
},
{
// Stripped like the two above: the NDK's own copy carries 7.5 MB of debug
// info per ABI, which is 8 of the 9.2 MB it weighs.
rel: `lib/${abi}/libc++_shared.so`, strip: true, abi, optional: n > 0, releaseRequired: true,
from: (ctx) => ctx.libcxxShared?.(abi),
},
{
// The JIT a V8 host runs on — placed beside the host by its build
// (native/CMakeLists.txt). Absent from a QuickJS build, which is why
// it is optional: the host it belongs to cannot load without it.
rel: `lib/${abi}/${V8_ANDROID_LIBRARY}`, strip: true, abi, optional: true,
from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, V8_ANDROID_LIBRARY),
},
{
// PhysX, the optional 3D solver: outside lib/ so that only a
// package whose project picked it carries it (androidPhysXLibs).
rel: `plugins/${abi}/${ANDROID_PHYSX_LIBRARY}`, strip: true, abi, optional: true,
from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, ANDROID_PHYSX_LIBRARY),
},
// Each Spine release, outside lib/ for the same reason: a package carries
// the ones its skeletons were exported from (androidSpineLibs). Optional,
// since a build narrowed with --spine leaves the others out.
...SPINE_RELEASES.map((version) => ({
rel: `plugins/${abi}/${androidSpineLibrary(version)}`, strip: true, abi, optional: true,
from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, androidSpineLibrary(version)),
})),
{
// Its startup snapshot, which this V8 keeps outside the library. An
// asset, read by the host before the engine starts (Runtime.cpp).
rel: `assets/${v8SnapshotAsset(abi)}`, abi, optional: true,
from: (ctx) => path.join(ctx.root, 'build/cmake/native', abi, 'v8_snapshot_blob.bin'),
},
]);
return [
...libs,
// Compiled by the emitter (javac + d8), not copied: the IME's own side
// of an editable field has to be Java, and a template exists so that no
// user needs a JDK to package.
{ rel: 'classes.dex', produced: true },
// The same Java, as source. The dex above is what the one-click package
// needs (no JDK on the user's machine); these are what an exported
// Android Studio project compiles, and what a game adding its own SDK
// extends. One template carries both because both are the same shim.
{
rel: 'java', kind: 'dir',
from: (ctx) => path.join(ctx.root, 'native', 'android', 'java'),
},
// Absent is valid in a local build — the host falls back to compiling the
// bundle, at the cost of a ~14 s black screen on first launch. Not valid
// in a release: v0.36.0 shipped without it, and every Android package
// built from that template opened black.
{
rel: `assets/${BYTECODE_FILE}`, optional: true, releaseRequired: true,
excusedBy: `lib/${abis[0]}/${V8_ANDROID_LIBRARY}`,
from: (ctx) => path.join(ctx.root, 'build/cmake/native', 'gen', BYTECODE_FILE),
},
{
rel: 'AndroidManifest.xml.in',
from: (ctx) => path.join(ctx.root, 'native', 'android', 'host', 'AndroidManifest.xml.in'),
},
{ rel: DEFAULT_ICON, from: (ctx) => path.join(ctx.root, 'native', 'icon.png') },
];
}
throw new Error(`No template layout for "${platform}" — ${TEMPLATE_PLATFORMS.join(', ')} have one.`);
}
/**
* The entries a template must carry, for one audience.
*
* `optional` is not one question but two, and conflating them is how a release
* shipped an Android template with no precompiled bytecode: a contributor's local
* build is fine without it (the host compiles on the device instead), and a
* PUBLISHED template is not — every game packaged from it then opens on a black
* screen the first time. `release: true` applies the stricter rule.
*/
function requiredTemplateEntries(platform, options = {}) {
return templateLayout(platform, options)
.filter((e) => !e.optional || (options.release && e.releaseRequired));
}
/** Template-relative paths that must be present for a template to be usable. */
export function requiredTemplateFiles(platform, options) {
return requiredTemplateEntries(platform, options).map((e) => e.rel);
}
/**
* The Android ABIs a template actually holds — what a package can offer.
*
* Read off the files rather than the manifest: a template is usable if its files
* are there, and asking the directory is what makes that true by construction.
*/
/**
* The pieces an exported Android Studio project is assembled from, out of an
* installed template — the Android side of {@link iosTemplateSources}.
*/
export function androidTemplateSources(dir) {
return {
libs: path.join(dir, 'lib'),
java: path.join(dir, 'java'),
dex: path.join(dir, 'classes.dex'),
manifestIn: path.join(dir, 'AndroidManifest.xml.in'),
icon: path.join(dir, DEFAULT_ICON),
bytecode: path.join(dir, 'assets', BYTECODE_FILE),
/** A V8 host's startup snapshots, one per ABI; absent from a QuickJS template. */
v8Snapshots: path.join(dir, 'assets', 'v8'),
};
}
export function templateAbis(dir) {
return ANDROID_ABIS.filter((abi) => existsSync(path.join(dir, 'lib', abi, 'libestella_js_host.so')));
}
/**
* The ABIs one package carries: the template's device ABIs, and the emulator's as well
* when `emulator` asks. Empty when the template has none of what was asked for, which the
* assembler reports by name rather than writing an app that installs on nothing.
*
* @param {string} dir An installed android template.
* @param {{emulator?: boolean}} [options]
*/
export function packageAbis(dir, options = {}) {
return templateAbis(dir).filter((abi) => options.emulator || ANDROID_DEVICE_ABIS.includes(abi));
}
/** The message for a template that has nothing to package under the ABI choice made. */
export function noPackageAbisMessage(dir, options = {}) {
const has = templateAbis(dir);
if (has.length === 0) return 'The runtime template carries no native libraries.';
return `The runtime template carries only ${has.join(', ')}, and ${options.emulator ? 'none of it' : 'no device ABI'} `
+ 'can be packaged. Install a template that includes arm64-v8a'
+ `${options.emulator ? '' : ', or ask for the emulator ABI (emulatorAbi / --emulator-abi) to package an emulator-only template'}.`;
}
/** What a template is missing, if anything — the one readiness test. An entry
* `excusedBy` another is not owed when that other is there: a V8 host's template
* owes no QuickJS bytecode. */
export function missingTemplateFiles(dir, platform, options) {
const has = (rel) => existsSync(path.join(dir, rel));
return requiredTemplateEntries(platform, options)
.filter((e) => !has(e.rel) && !(e.excusedBy && has(e.excusedBy))).map((e) => e.rel);
}
/**
* The same test over a LISTING rather than a directory — for an archive that has
* not been unpacked, which is the form a template is published in and therefore
* the form worth checking before anyone can install it.
*
* A directory entry is present when something inside it is: a zip stores the
* files, not the folder.
*/
export function missingTemplateEntries(names, platform, options = {}) {
const held = names.map((n) => n.split('\\').join('/').replace(/\/+$/, ''));
const set = new Set(held);
const has = (e) => (e.kind === 'dir'
? held.some((n) => n === e.rel || n.startsWith(`${e.rel}/`))
: set.has(e.rel));
return requiredTemplateEntries(platform, options)
.filter((e) => !has(e) && !(e.excusedBy && set.has(e.excusedBy))).map((e) => e.rel);
}
// =============================================================================
// The manifest
// =============================================================================
/**
* Read a template's `template.json`. Null when the directory holds no template,
* or one this build cannot read — callers treat both as "not installed", which is
* the only honest answer either way.
*/
export function readTemplateManifest(dir) {
const file = path.join(dir, TEMPLATE_MANIFEST);
if (!existsSync(file)) return null;
try {
const parsed = JSON.parse(readFileSync(file, 'utf8'));
if (parsed?.kind !== 'estella-native-template') return null;
if (parsed.formatVersion !== TEMPLATE_FORMAT) return null;
return parsed;
} catch {
return null;
}
}
/** What a template written before the manifest recorded Spine links: every one
* of those was built with native/CMakeLists.txt's single-release default. */
export const LEGACY_TEMPLATE_SPINE = '4.2';
/**
* The Spine releases a template's host carries. Current templates carry every
* vendored release (`spineVersions`); one from before carried a single release
* (`spineVersion`), or did not say, which meant the 4.2 default.
*/
export function templateSpineVersions(manifest) {
if (Array.isArray(manifest?.spineVersions)) return manifest.spineVersions;
return [manifest?.spineVersion || LEGACY_TEMPLATE_SPINE];
}
/** The build directories a template for `platform` is packed from. */
function hostBuildDirs(root, platform, abis) {
if (platform === 'ios') return [path.join(root, 'build/cmake/native-ios')];
if (platform === 'android') return (abis ?? []).map((abi) => path.join(root, 'build/cmake/native', abi));
return [path.join(root, `build/cmake/native-${platform}`)];
}
/**
* The Spine releases the host builds behind a template linked, read from their
* CMake caches (ESTELLA_SPINE_VERSIONS). The manifest is what an export holds a
* package's skeletons to, so it records what the build DID, a narrowed --spine or
* a cache edited by hand included. Null when no build dir has a cache to read.
*/
export function builtSpineVersions(root, platform, abis) {
const seen = new Map();
for (const dir of hostBuildDirs(root, platform, abis)) {
const cache = path.join(dir, 'CMakeCache.txt');
if (!existsSync(cache)) continue;
const text = readFileSync(cache, 'utf8');
const list = /^ESTELLA_SPINE_VERSIONS:[A-Z]+=(.*)$/m.exec(text);
const single = /^ESTELLA_SPINE_VERSION:[A-Z]+=(.*)$/m.exec(text);
const versions = list ? list[1].trim().split(';').filter(Boolean)
: [single ? single[1].trim() : LEGACY_TEMPLATE_SPINE];
seen.set(dir, versions.sort().join(';'));
}
const sets = new Set(seen.values());
if (sets.size > 1) {
throw new Error(`The ${platform} builds carry different Spine releases (${[...seen].map(([d, v]) => `${path.basename(d)}: ${v}`).join(', ')}): `
+ 'one template carries one set. Rebuild them with the same --spine.');
}
return sets.size ? [...sets][0].split(';') : null;
}
/**
* The Spine releases a template can carry. Written out because the editor reads
* this file where no third_party/ exists; pipeline/tests/native-template.test.ts
* holds it to the vendored trees and to the SDK's SPINE_VERSIONS.
*/
export const SPINE_RELEASES = ['2.1', '3.8', '4.1', '4.2', '4.3'];
/** One Spine release's library on Android, kept under plugins/<abi>/ in the template. */
export const androidSpineLibrary = (version) => `libestella_spine${version.replace('.', '')}.so`;
/**
* The Spine libraries for `versions` in each of `abis`, for a package's lib/<abi>/:
* the releases its skeletons were exported from, and no others.
*
* @param {string} dir An installed android template.
* @param {string[]} abis The ABIs the package carries.
* @param {Iterable<string>} versions The Spine releases the package's skeletons need.
* @returns {Record<string, string[]>}
*/
export function androidSpineLibs(dir, abis, versions) {
// Read once: an iterator (a Map's keys) is spent by the first ABI, and every
// ABI after it would get no Spine at all — v0.101.0's x86_64 emulator did.
const releases = [...versions];
const out = {};
for (const abi of abis) {
const files = releases.map((v) => path.join(dir, 'plugins', abi, androidSpineLibrary(v)))
.filter((file) => existsSync(file));
if (files.length) out[abi] = files;
}
return out;
}
export function writeTemplateManifest(dir, meta) {
const manifest = {
kind: 'estella-native-template',
formatVersion: TEMPLATE_FORMAT,
id: templateId(meta.platform, meta.abi),
...meta,
};
// No timestamp: two builds of the same commit must produce byte-identical
// artifacts, or a published checksum means nothing.
writeFileSync(path.join(dir, TEMPLATE_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
return manifest;
}
/**
* Whether an installed template can run this editor's exports.
*
* The match is EXACT on version. The SDK bundle is compiled into the host binary,
* and the cooked content, the scene format and the `es_*` surface all travel with
* it — a near-miss is a crash on a device rather than a smaller problem.
*/
export function templateMatches(manifest, want) {
return !!manifest
&& manifest.platform === want.platform
&& manifest.engineVersion === want.engineVersion;
}
/** The distributed artifact's filename. */
export function templateZipName(platform, engineVersion) {
return `estella-native-${templateId(platform)}-${engineVersion}.zip`;
}
// =============================================================================
// The published index
// =============================================================================
/** What a release publishes beside the archives: which templates exist for that
* version, and what each one must hash to. */
export const TEMPLATE_INDEX = 'native-templates.json';
/**
* The mirror a release is copied to, and the environment variable that overrides
* it. Empty until one is configured — a build with no mirror simply has one source.
*
* A mirror is a convenience, never an authority: every archive is checked against
* the size and SHA-256 the index states, so the worst a wrong or stale mirror can
* do is fail and hand the download back to the origin.
*/
export const RELEASE_MIRROR_ENV = 'ESTELLA_RELEASE_MIRROR';
// The project's own mirror: an R2 bucket in APAC, which is where the reports of
// slow downloads come from, behind the project's domain rather than Cloudflare's
// built-in r2.dev hostname — that one is rate limited and meant for development.
export const DEFAULT_RELEASE_MIRROR = 'https://dl.estella.games';
/** The release origin: where a version is published, and the last word on it. */
export const RELEASE_ORIGIN = 'https://github.com/esengine/estella/releases/download';
/** Mirrors to try before the origin, fastest-first. `,`-separated in the env. */
export function releaseMirrors(env = process.env) {
const configured = env[RELEASE_MIRROR_ENV] ?? DEFAULT_RELEASE_MIRROR;
return configured.split(',').map((s) => s.trim().replace(/\/+$/, '')).filter(Boolean);
}
/**
* Where a release's assets live. Composed rather than stored in the index, so the
* same index works from a mirror, a local directory or a company file share — the
* editor is told a base, not a set of absolute URLs.
*/
export function releaseAssetBase(engineVersion) {
return `${RELEASE_ORIGIN}/v${engineVersion}`;
}
/**
* Every base to try for one version, in order: the mirrors, then the origin.
*
* One list, so the download path cannot prefer a mirror the update check has never
* heard of. A mirror lays its versions out exactly as the origin does — `v<version>`
* holding that release's assets — so a base swap is the whole difference.
*/
export function releaseAssetBases(engineVersion, env = process.env) {
return [
...releaseMirrors(env).map((base) => `${base}/v${engineVersion}`),
releaseAssetBase(engineVersion),
];
}
/**
* Validate a published index. Returns its entries, or null when the document is
* not one — a 404 page and a truncated download are both "no index", and neither
* should reach the code that decides what to install.
*/
export function parseTemplateIndex(doc, engineVersion) {
if (doc?.kind !== 'estella-native-templates' || doc.formatVersion !== TEMPLATE_FORMAT) return null;
if (engineVersion && doc.engineVersion !== engineVersion) return null;
if (!Array.isArray(doc.templates)) return null;
const entries = doc.templates.filter((t) => typeof t?.id === 'string'
&& typeof t.platform === 'string'
&& typeof t.file === 'string' && /^[\w.-]+$/.test(t.file)
&& typeof t.sha256 === 'string' && /^[0-9a-f]{64}$/.test(t.sha256)
&& Number.isInteger(t.bytes) && t.bytes > 0);
return entries.length > 0 ? entries : null;
}
// =============================================================================
// Where templates live
// =============================================================================
/**
* Estella's own data directory. Deliberately not Electron's `userData`: the CLI
* emits templates and the editor consumes them, so the path has to be one both
* can compute the same way, without importing Electron.
*/
export function estellaDataDir() {
const home = process.env.HOME || process.env.USERPROFILE || '';
if (process.platform === 'win32') return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Estella');
if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Estella');
return path.join(process.env.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'Estella');
}
/** The template store. `ESTELLA_NATIVE_TEMPLATES` overrides it — for CI, for a
* shared network location, and for tests. */
export function templateStoreDir() {
return process.env.ESTELLA_NATIVE_TEMPLATES || path.join(estellaDataDir(), 'native-templates');
}
/** Where one template installs to. Versioned, so upgrading the editor never
* silently reuses the previous release's binary. */
export function installedTemplateDir(engineVersion, platform, storeDir = templateStoreDir()) {
return path.join(storeDir, engineVersion, templateId(platform));
}
/**
* The installed template for this platform, or null.
*
* @returns {{dir: string, manifest: object, missing: string[]}|null}
*/
export function findTemplate(want, storeDir = templateStoreDir()) {
const dir = installedTemplateDir(want.engineVersion, want.platform, storeDir);
const manifest = readTemplateManifest(dir);
if (!templateMatches(manifest, want)) return null;
return { dir, manifest, missing: missingTemplateFiles(dir, want.platform) };
}
// =============================================================================
// Per-platform consumers
// =============================================================================
/**
* The three pieces an iOS Xcode project is built around. Named here rather than
* at the call site so the layout table stays the only thing that knows filenames.
*/
export function iosTemplateSources(dir) {
return {
xcframework: path.join(dir, 'Estella.xcframework'),
mainM: path.join(dir, 'App', 'main.m'),
channelHeader: path.join(dir, 'App', 'EstellaNativeChannel.h'),
infoPlistIn: path.join(dir, 'App', 'Info.plist.in'),
icon: path.join(dir, DEFAULT_ICON),
bytecode: path.join(dir, 'assets', BYTECODE_FILE),
};
}
/** The desktop equivalent — the runtime binary and the three files the assembler
* composes an app bundle from. */
export function desktopTemplateSources(dir, platform = 'macos') {
return {
executable: path.join(dir, platform === 'windows' ? 'estella_desktop.exe' : 'estella_desktop'),
infoPlistIn: path.join(dir, 'Info.plist.in'),
icon: path.join(dir, DEFAULT_ICON),
bytecode: path.join(dir, BYTECODE_FILE),
/** Windows only; absent elsewhere. */
d3dCompiler: path.join(dir, D3D_COMPILER),
/** A V8 host's runtime, beside the executable; none of it in a QuickJS template. */
v8Runtime: platform === 'windows' ? V8_WINDOWS_RUNTIME.map((rel) => path.join(dir, rel)) : [],
/** Steam's redistributable, when the template was emitted with an SDK. */
steamRedist: path.join(dir, STEAM_REDIST[platform] ?? STEAM_REDIST.macos),
};
}