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
/**
* @file projectExportOptions.ts — what a project's own settings say an export of
* it is, for one target.
*
* The Build dialog and the command line each assembled this by hand, and the two
* lists drifted: a headless package carried no app id, ignored a project's script
* entry and scenes folder and its ad network, while the dialog dropped the
* project's engine module choices. Both now start from this one answer and lay
* only what the person chose for this build on top.
*/
import path from 'node:path';
import { homedir } from 'node:os';
import type { ExportGameOptions } from './exportGame';
import { readReleaseKey } from './rpk';
import { signingKeyFromPem, type SigningKey } from '../../../build-tools/utils/androidKeystore.js';
import { loadPlayableProfile } from './platformCatalog';
import {
EXPORT_PROFILE_FIELDS, resolveAppId, resolveLayout, resolveOrientation, resolveScripts,
type ExportPlatform, type ProjectManifest, type ProjectPackaging,
} from '../project/format';
import { BUILTIN_PLATFORMS, isMiniGamePlatform } from '../project/platforms';
import { cookOptionsOf, packagingOptionsOf, runtimeConfigOf } from '../project/runtimeConfig';
/** The part of an export a project's manifest decides; the caller adds where the
* engine, templates and output live, and the choices made for this one build. */
export type ProjectExportOptions = Omit<ExportGameOptions,
'hostsDir' | 'packagesDir' | 'sdkDistDir' | 'wasmDir' | 'outDir'>;
const NATIVE_IDENTITY: Partial<Record<ExportPlatform, 'android' | 'ios' | 'desktop'>> = {
android: 'android', ios: 'ios', desktop: 'desktop',
};
/**
* The project as one of its export profiles describes it: the profile's settings
* laid over the project's, its target's slice merged field by field so a profile
* that names only a test appid keeps the project's version code.
*/
export function withExportProfile(manifest: ProjectManifest, name: string): ProjectManifest {
const profiles = manifest.packaging?.profiles ?? {};
const profile = profiles[name];
if (!profile) {
const known = Object.keys(profiles);
throw new Error(`no export profile "${name}" — ${known.length ? `this project has ${known.join(', ')}` : 'this project defines none'}`);
}
const packaging = manifest.packaging ?? {};
const target = profile.platform as keyof NonNullable<ProjectPackaging['platforms']>;
const slice = { ...packaging.platforms?.[target], ...profile.platforms?.[target] };
const overrides = Object.fromEntries(EXPORT_PROFILE_FIELDS
.filter((key) => profile[key] !== undefined).map((key) => [key, profile[key]]));
return {
...manifest,
packaging: {
...packaging,
...overrides,
platform: profile.platform,
platforms: { ...packaging.platforms, ...(Object.keys(slice).length > 0 ? { [target]: slice } : {}) },
},
};
}
/** What a project may not hold, handed in by whoever keeps it on this machine. */
export interface ExportSecrets {
androidKeyPassphrase?: string;
}
export async function projectExportOptions(
root: string, source: ProjectManifest, platform: ExportPlatform, profileName?: string, secrets: ExportSecrets = {},
): Promise<ProjectExportOptions> {
const profile = profileName ? source.packaging?.profiles?.[profileName] : undefined;
const manifest = profileName ? withExportProfile(source, profileName) : source;
if (profile && profile.platform !== platform) {
throw new Error(`export profile "${profileName}" is for ${profile.platform}, not ${platform}`);
}
const packaging = manifest.packaging;
const plat = packaging?.platforms;
const vendor = (plat as Record<string, { appid?: string } | undefined> | undefined)?.[platform];
const quickGame = platform === 'quickgame' ? plat?.quickgame : platform === 'huawei' ? plat?.huawei : undefined;
const identity = NATIVE_IDENTITY[platform];
return {
root,
platform,
entryScene: manifest.defaultScene ?? '',
scenesDir: resolveLayout(manifest).scenes,
scriptsEntry: resolveScripts(manifest).main,
title: manifest.name || path.basename(root),
orientation: resolveOrientation(manifest),
runtime: runtimeConfigOf(manifest),
...cookOptionsOf(manifest),
...packagingOptionsOf(manifest),
// A project-defined target is a mini-game variant built on WeChat's, so it
// ships WeChat's id; a built-in vendor ships only its own.
miniGameAppid: isMiniGamePlatform(platform) ? vendor?.appid
: (BUILTIN_PLATFORMS as readonly string[]).includes(platform) ? undefined : plat?.wechat?.appid,
...(identity ? { appId: resolveAppId(manifest, identity) } : {}),
appVersion: manifest.version,
...(quickGame ? {
miniGameVersionCode: quickGame.versionCode,
miniGameReleaseKey: (await readReleaseKey(root, quickGame.releaseKey)) ?? undefined,
} : {}),
...(platform === 'wechat' && plat?.wechat?.emscriptenGLX ? { miniGameGlx: true } : {}),
androidVersionCode: plat?.android?.versionCode,
androidAppBundle: plat?.android?.appBundle,
androidEmulatorAbi: plat?.android?.emulatorAbi,
androidCompressNativeLibs: plat?.android?.compressNativeLibs,
androidOutput: plat?.android?.output,
...(platform === 'android' && plat?.android?.releaseKey
? { androidKey: () => androidReleaseKey(root, plat.android!.releaseKey!, secrets.androidKeyPassphrase) }
: {}),
...(platform === 'web' && (plat?.web?.channel === 'poki' || plat?.web?.channel === 'crazygames' || plat?.web?.channel === 'youtube') ? { webChannel: plat.web.channel } : {}),
...(platform === 'web' && plat?.web?.connect?.length ? { webConnect: plat.web.connect } : {}),
...(platform === 'web' && plat?.web?.engineJs === true ? { webEngineJs: true } : {}),
...(platform === 'web' && plat?.web?.channel === 'crazygames' && plat.web.leaderboardEncryptionKey
? { leaderboardEncryptionKey: plat.web.leaderboardEncryptionKey } : {}),
desktopProductName: plat?.desktop?.productName,
desktopChannel: plat?.desktop?.channel,
steam: plat?.desktop?.steam,
...(platform === 'playable'
? { playableAdProfile: (await loadPlayableProfile(root, plat?.playable?.network)) ?? undefined }
: {}),
sizeBudgetBytes: packaging?.sizeBudget?.[platform],
// Unset leaves the hot-update config to fall back to asset-groups.json's
// active profile, where projects kept their CDN root before this setting.
...(packaging?.remoteRoot !== undefined ? { hotUpdate: { remoteRoot: packaging.remoteRoot } } : {}),
secretFiles: [quickGame?.releaseKey, platform === 'android' ? plat?.android?.releaseKey : undefined]
.flatMap((k) => (k ? [k.privateKey, k.certificate] : [])).filter((f) => f !== ''),
...(profile ? {
profile: profileName,
...(profile.config ? { minify: profile.config === 'shipping' } : {}),
} : {}),
};
}
/** A named key that cannot be read is an error, not a quiet fall back to the
* development key: that package would be refused at upload. */
function androidReleaseKey(
root: string, paths: { privateKey: string; certificate: string }, passphrase: string | undefined,
): SigningKey {
try {
return signingKeyFromPem({
key: keyPath(root, paths.privateKey),
cert: keyPath(root, paths.certificate),
...(passphrase ? { passphrase } : {}),
});
} catch (e) {
throw new Error(`the Android release key could not be read (${paths.privateKey}, ${paths.certificate}): ${(e as Error).message}`);
}
}
/** A key path as the settings page invites it: relative to the project, absolute,
* or under the home directory (`~/…`). */
function keyPath(root: string, file: string): string {
return /^~[/\\]/.test(file) ? path.join(homedir(), file.slice(2)) : path.resolve(root, file);
}