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 app identity an editor export declares, and what each platform calls it.
//
// `app.config.json` sits beside `game.config.json` in an export for a native
// target. The split is deliberate: game.config.json is what the RUNTIME reads to
// play the game; this is what the PACKAGER reads to build an application around
// it. Identity, version and orientation are properties the OS owns — the engine
// can letterbox but cannot rotate a phone — so they are settled here, once, from
// the project, rather than by a flag on whoever happens to run the build.
import path from 'path';
import { existsSync, readFileSync } from 'fs';
/** What the editor writes; see desktop/electron/exportGame.ts NativeAppConfig. */
const DEFAULTS = {
id: 'com.estella.game',
name: 'Estella',
version: '1.0',
versionCode: 1,
orientation: 'landscape',
};
/**
* Read an export's `app.config.json`. Missing or unreadable falls back to the
* defaults with a warning rather than failing: a content dir produced by an older
* editor still packages, it just ships a generic identity.
*
* @param contentDir Absolute path of the exported project.
* @param warn Sink for the "no app.config.json" notice.
*/
export function readAppConfig(contentDir, warn = () => {}) {
const file = path.join(contentDir, 'app.config.json');
if (!existsSync(file)) {
warn(`no app.config.json in ${path.basename(contentDir)} — packaging with a default identity `
+ `(${DEFAULTS.id}). Re-export from the editor to carry the project's own.`);
return { ...DEFAULTS };
}
try {
const parsed = JSON.parse(readFileSync(file, 'utf8'));
return {
id: typeof parsed.id === 'string' && parsed.id ? parsed.id : DEFAULTS.id,
name: typeof parsed.name === 'string' && parsed.name ? parsed.name : DEFAULTS.name,
version: typeof parsed.version === 'string' && parsed.version ? parsed.version : DEFAULTS.version,
versionCode: Number.isInteger(parsed.versionCode) && parsed.versionCode > 0
? parsed.versionCode : DEFAULTS.versionCode,
orientation: parsed.orientation === 'portrait' ? 'portrait' : DEFAULTS.orientation,
};
} catch (err) {
warn(`app.config.json is unreadable (${err.message}) — packaging with a default identity.`);
return { ...DEFAULTS };
}
}
/**
* The manifest value for an orientation. `sensorPortrait` / `sensorLandscape`
* rather than the plain values: a phone held the other way up still works, but the
* app never crosses into the aspect it was not designed for. That is what a game
* ships with — a hard `portrait` leaves an upside-down phone stubbornly rotated.
*/
export function androidScreenOrientation(orientation) {
return orientation === 'portrait' ? 'sensorPortrait' : 'sensorLandscape';
}
/**
* The `UISupportedInterfaceOrientations` array for an orientation. iOS has no
* "sensor" mode: you list the ones you allow, and the OS rotates among them.
*/
export function iosInterfaceOrientations(orientation) {
return orientation === 'portrait'
? ['UIInterfaceOrientationPortrait', 'UIInterfaceOrientationPortraitUpsideDown']
: ['UIInterfaceOrientationLandscapeLeft', 'UIInterfaceOrientationLandscapeRight'];
}
/**
* The values `AndroidManifest.xml.in` is filled with, for every packager that
* writes one (the APK, the App Bundle, the Android Studio project). One list, so
* a placeholder added to the template cannot reach one package and not another.
*/
export function androidManifestValues(app, { hasCode }) {
return {
APP_ID: app.id,
APP_NAME: app.name,
VERSION_NAME: app.version,
VERSION_CODE: app.versionCode,
SCREEN_ORIENTATION: androidScreenOrientation(app.orientation),
HAS_CODE: hasCode ? 'true' : 'false',
USES_CLEARTEXT: app.allowHttp ? 'true' : 'false',
};
}
/** Substitute `@NAME@` placeholders in a committed template. */
export function fillTemplate(text, values) {
return text.replace(/@([A-Z_]+)@/g, (match, key) => (key in values ? String(values[key]) : match));
}