Skip to content

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.

7.7 KB
Raw Blame
// 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);
}