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
//
// Turning an iOS export into a project the user can open.
//
// An export that hands back a content folder plus two commands to type is not a
// build — every engine worth using gives you an Xcode project you can
// double-click. Generating one needs NO compiler: the engine is a prebuilt
// xcframework from the runtime template and the app shell is a `main.m` plus a
// plist, so the whole step is copy + write.
//
// Plain ESM, and the ONE implementation: the editor's export and
// `cli native --target ios --package` both call it, so a project written by the
// CLI and one written by the editor cannot differ.
import path from 'path';
import { existsSync } from 'fs';
import { cp, mkdir, readdir, rm, readFile, writeFile } from 'fs/promises';
import { renderPbxproj, renderScheme } from './xcodeProject.js';
import { iosInterfaceOrientations } from './nativeApp.js';
/** The asset catalog Xcode compiles the app icon out of. A single 1024×1024 image
* is all a modern catalog needs — Xcode derives every size the system asks for,
* so nothing here resizes anything. */
const ICON_CATALOG = 'Assets.xcassets';
async function writeIconCatalog(contentDir, iconPng) {
const iconSet = path.join(contentDir, ICON_CATALOG, 'AppIcon.appiconset');
await mkdir(iconSet, { recursive: true });
await writeFile(path.join(iconSet, 'icon.png'), iconPng);
await writeFile(path.join(iconSet, 'Contents.json'), `${JSON.stringify({
images: [{ filename: 'icon.png', idiom: 'universal', platform: 'ios', size: '1024x1024' }],
info: { author: 'estella', version: 1 },
}, null, 2)}\n`);
await writeFile(path.join(contentDir, ICON_CATALOG, 'Contents.json'), `${JSON.stringify({
info: { author: 'estella', version: 1 },
}, null, 2)}\n`);
}
/** A target/product name Xcode and the shell can both carry unquoted. */
function targetName(appName) {
return appName.replace(/[^A-Za-z0-9]+/g, '') || 'EstellaGame';
}
/**
* Text safe to substitute into the Info.plist, which is XML.
*
* A game called "Save & Load" wrote a plist Xcode could not parse, and the build
* failed with "unable to read property list" naming neither the ampersand nor
* the name it came from. Every project whose title contains `&`, `<` or `>` was
* unbuildable for iOS.
*/
function xmlText(value) {
return String(value).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
}
/**
* Write the Xcode project into an export, in place: the export directory BECOMES
* the project. Its cooked files stay where they are and join the resources phase
* directly — they land at the bundle root, which is where the host reads them.
*
* @param {string} contentDir The export (cooked content + the two configs).
* @param {{id: string, name: string, version: string, versionCode: number,
* orientation: 'landscape'|'portrait'}} app From `app.config.json`.
* @param {{xcframework: string, mainM: string, infoPlistIn: string, icon?: string}} sources
* The prebuilt pieces, out of the installed runtime template.
* @param {string} [deploymentTarget]
* @param {Buffer} [icon] The launcher icon; the template's default when absent.
* @returns {Promise<string>} The `.xcodeproj` path, to reveal or open.
*/
export async function emitIosXcodeProject(contentDir, app, sources, deploymentTarget = '17.0', icon) {
const name = targetName(app.name);
const frameworkName = 'Estella.xcframework';
const projectDir = path.join(contentDir, `${name}.xcodeproj`);
const appDir = path.join(contentDir, 'App');
const frameworkDest = path.join(contentDir, frameworkName);
// Rewritten wholesale so a re-export never inherits the last one's stale
// slices, plist or object graph.
await rm(projectDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
await rm(appDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
await rm(frameworkDest, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
await rm(path.join(contentDir, ICON_CATALOG), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
await cp(sources.xcframework, frameworkDest, { recursive: true });
await mkdir(appDir, { recursive: true });
await cp(sources.mainM, path.join(appDir, 'main.m'));
// What the app's own Objective-C or Swift includes to answer the game by name.
if (sources.channelHeader && existsSync(sources.channelHeader)) {
await cp(sources.channelHeader, path.join(appDir, 'EstellaNativeChannel.h'));
}
await writeIconCatalog(contentDir, icon ?? await readFile(sources.icon));
// The SDK bytecode ships as a bundle resource, where the host's readAsset()
// finds it — so the first launch after an install is as fast as the rest,
// exactly as it is on Android. Absent when the template's build machine had no
// compiler for it; the host then parses and caches, as before.
if (sources.bytecode && existsSync(sources.bytecode)) {
await cp(sources.bytecode, path.join(contentDir, path.basename(sources.bytecode)));
}
const template = await readFile(sources.infoPlistIn, 'utf8');
const orientations = iosInterfaceOrientations(app.orientation)
.map((o) => `\t\t<string>${o}</string>`).join('\n');
await writeFile(path.join(appDir, 'Info.plist'), template
.replace(/@APP_NAME@/g, xmlText(app.name))
.replace(/@VERSION_NAME@/g, xmlText(app.version))
.replace(/@VERSION_CODE@/g, String(app.versionCode))
.replace(/@ORIENTATIONS@/g, orientations));
// Everything the export wrote, minus what this function just added. Dotfiles
// stay out: a .DS_Store in a resources phase is a code-signing failure.
const skip = new Set([`${name}.xcodeproj`, 'App', frameworkName]);
const resources = (await readdir(contentDir, { withFileTypes: true }))
.filter((e) => !skip.has(e.name) && !e.name.startsWith('.'))
.map((e) => ({ name: e.name, isDir: e.isDirectory() }))
.sort((a, b) => a.name.localeCompare(b.name));
await mkdir(path.join(projectDir, 'xcshareddata', 'xcschemes'), { recursive: true });
await writeFile(path.join(projectDir, 'project.pbxproj'), renderPbxproj({
name,
bundleId: app.id,
version: app.version,
versionCode: app.versionCode,
deploymentTarget,
frameworkName,
resources,
}));
await writeFile(
path.join(projectDir, 'xcshareddata', 'xcschemes', `${name}.xcscheme`),
renderScheme(name));
return projectDir;
}