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.

16.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  runtimeConfig.ts — what a RUNTIME has to be told about the project, once.
 *
 * A project setting is never one fact in one file. "This layer resolves by depth"
 * is a manifest field, a parse branch, something the edit viewport applies, a
 * field in the play payload, and a field a shipped build is written with. Each of
 * those used to be spelled out by hand at its own site, and a setting is only as
 * real as its least-remembered site: the 2.5D depth mask reached the play realm
 * and NEITHER the editor nor any exported build, because the export re-derives
 * the settings from the manifest in the main process and simply never mentioned
 * it. It looked right in Play and shipped wrong — the worst shape a bug can take.
 *
 * So the derivation happens once, as a pure function over a parsed manifest, and
 * both processes call it: the renderer to build the play payload, the main
 * process to build an export (it cannot import ProjectStore — that lives in the
 * window — but it can import this).
 *
 * The values are EFFECTIVE ones, defaults folded in, because "what will the game
 * run with" is the question every caller is asking. Each consumer still decides
 * what to omit from its own wire format (absence = default is how the manifest,
 * the play payload and game.config.json all express a default).
 *
 * Adding a setting means adding it here. `tools/check-project-settings.mjs`
 * fails the build when a field in this shape is not carried by every consumer —
 * or is not listed there as a declared, reasoned gap.
 */
import { DEFAULT_PHYSICS3D_WORLD, parseQualityConfig, parseRuntimeBuildConfig } from 'esengine';
import type {
  AudioProjectConfig, PackagedGameConfig, Physics2DPluginConfig, Physics3DWorldConfig, QualityConfig, RuntimeBuildConfig,
} from 'esengine';
import { resolveScreenFit, SORTING_LAYER_COUNT, type ProjectFeatures, type ProjectManifest, type ProjectPackaging } from './format';

/** The project's camera fit as a runtime takes it (`scaleMode < 0` ⇒ off). */
export interface RuntimeScreenFit {
  designWidth: number;
  designHeight: number;
  scaleMode: number;
  matchWidthOrHeight: number;
  /** The engine's RenderResolution; 0 = straight to the surface. */
  renderPolicy: number;
}

/**
 * Every project setting a runtime is told about, with defaults applied.
 *
 * One shape for the play realm and for a shipped build, because the whole point
 * is that Play is a rehearsal of shipping: a field only one of them carries is a
 * field that makes the rehearsal lie.
 */
export interface RuntimeProjectConfig {
  /** The achievement ids the project declares — the set the runtime refuses an
   *  unlock outside of. Empty ⇒ nothing is checked. */
  achievements: string[];
  /** The Steam application id, when the desktop build ships to Steam. 0 ⇒ it does
   *  not, and no runtime tries to bring a client up. */
  steamAppId: number;
  /** Install physics even when the static scene shows no bodies (runtime-spawned). */
  physicsEnabled: boolean;
  /** World solver + collision matrix (Project Settings → Physics). */
  physicsConfig: Physics2DPluginConfig;
  /** The 3D physics backend; 'jolt' is the default. */
  physics3dBackend: 'jolt' | 'physx';
  /** The 3D world: scene units per metre and gravity, defaults folded in. */
  physics3dWorld: Physics3DWorldConfig;
  /** Mixer state: bus volumes, custom buses, effects, duck rules. */
  audioConfig: AudioProjectConfig;
  /** Runtime tuning the project declared — only what differs from the engine's own values, so `{}` is the default. */
  runtime: RuntimeBuildConfig;
  /** Built-in widget theme; 'dark' is the default. */
  uiTheme: 'dark' | 'light';
  /** Theme colour overrides (role → #rrggbbaa), possibly empty. */
  uiThemeColors: Record<string, string>;
  /** Bitmask of sorting layers (0..31) that y-sort within the layer. */
  ySortLayers: number;
  /** Bitmask of sorting layers (0..31) that resolve by depth — the 2.5D opt-in. */
  depthLayers: number;
  /** Render colour space; 'gamma' is the default. Boot-fixed (shaders compile against it). */
  colorSpace: 'gamma' | 'linear';
  /** The curve on the way to the display; 'none' is the default. */
  outputTransform: 'none' | 'aces' | 'neutral';
  /** Scene-target multisampling the project asks for; 4 is the default. The
   *  device clamps it — this is the policy half, never the capability. */
  msaaSamples: number;
  quality: QualityConfig;
  /** Whether the project names a level, `off` among them. One that names none takes the device's default (see `defaultQualityMode`). */
  qualityModeNamed: boolean;
  /** GPU backend the build asks for; 'webgl2' is the default. Boot-fixed, and a
   *  request for 'webgpu' still falls back where the machine has none. */
  renderBackend: 'webgl2' | 'webgpu';
  /** Main-camera fit of the design resolution; `scaleMode < 0` = off. */
  screenFit: RuntimeScreenFit;
}

/** Only the counts a target can actually be created with; anything else is 4. */
function msaaOf(v: unknown): number {
  return v === 1 || v === 2 || v === 8 ? v : 4;
}

/** Bit i set ⇒ sorting layer i is in `list`. Layers outside 0..31 have no bit. */
function layerMask(list: readonly number[] | undefined): number {
  let mask = 0;
  for (const i of list ?? []) {
    if (Number.isInteger(i) && i >= 0 && i < SORTING_LAYER_COUNT) mask |= 1 << i;
  }
  return mask >>> 0;
}

/** Pad/truncate collision-layer names to the 16 Box2D filter bits (layer 0 = Default). */
export function normalizeCollisionLayers(layers?: string[]): string[] {
  return Array.from({ length: 16 }, (_, i) => layers?.[i] ?? (i === 0 ? 'Default' : ''));
}

/** Pad/truncate the collision matrix to 16 rows; absent rows default to all-collide. */
export function normalizeCollisionLayerMasks(masks?: number[]): number[] {
  return Array.from({ length: 16 }, (_, i) => (typeof masks?.[i] === 'number' ? masks[i] & 0xffff : 0xffff));
}

/**
 * The physics world config a runtime installs, defaults folded in. The solver
 * defaults mirror the engine's own fallbacks, so Project Settings shows the
 * effective values rather than blanks.
 *
 * The collision matrix rides along ONLY when it actually restricts a pair: an
 * all-collide matrix would otherwise override each single-layer collider's own
 * maskBits for nothing.
 */
function physicsConfigOf(features: ProjectManifest['features']): Physics2DPluginConfig {
  const p = features?.physics;
  const config: Physics2DPluginConfig = {
    gravity: p?.gravity ?? { x: 0, y: -9.81 },
    fixedTimestep: p?.fixedTimestep ?? 1 / 60,
    subStepCount: p?.subStepCount ?? 4,
    contactHertz: p?.contactHertz ?? 120,
    contactDampingRatio: p?.contactDampingRatio ?? 10,
    contactSpeed: p?.contactSpeed ?? 10,
    enableSleep: p?.enableSleep ?? true,
    enableContinuous: p?.enableContinuous ?? true,
  };
  const masks = normalizeCollisionLayerMasks(p?.collisionLayerMasks);
  if (masks.some((m) => (m & 0xffff) !== 0xffff)) config.collisionLayerMasks = masks;
  return config;
}

/**
 * The project's effective runtime settings. Takes the parsed manifest shape both
 * processes have — the editor's live project state satisfies it structurally.
 */
export function runtimeConfigOf(
  manifest: Pick<ProjectManifest, 'designResolution' | 'features' | 'packaging'>,
): RuntimeProjectConfig {
  const f = manifest.features;
  return {
    achievements: manifest.packaging?.achievements ?? [],
    // Only when the channel is actually Steam: an app id left behind by a project
    // that has since gone back to a standalone build must not make the runtime
    // hunt for a client.
    steamAppId: manifest.packaging?.platforms?.desktop?.channel === 'steam'
      ? (manifest.packaging?.platforms?.desktop?.steam?.appId ?? 0) : 0,
    physicsEnabled: f?.physics?.enabled ?? false,
    physicsConfig: physicsConfigOf(f),
    physics3dBackend: f?.physics?.backend3d === 'physx' ? 'physx' : 'jolt',
    physics3dWorld: { ...DEFAULT_PHYSICS3D_WORLD, ...f?.physics?.world3d },
    audioConfig: f?.audio ?? {},
    runtime: parseRuntimeBuildConfig(f?.runtime),
    uiTheme: f?.ui?.theme === 'light' ? 'light' : 'dark',
    uiThemeColors: f?.ui?.colors ?? {},
    ySortLayers: layerMask(f?.rendering?.ySortLayers),
    depthLayers: layerMask(f?.rendering?.depthLayers),
    colorSpace: f?.rendering?.colorSpace === 'linear' ? 'linear' : 'gamma',
    outputTransform: f?.rendering?.outputTransform === 'aces' ? 'aces'
      : f?.rendering?.outputTransform === 'neutral' ? 'neutral' : 'none',
    msaaSamples: msaaOf(f?.rendering?.msaa),
    quality: parseQualityConfig(f?.rendering?.quality),
    qualityModeNamed: parseQualityConfig(f?.rendering?.quality).mode === (f?.rendering?.quality as { mode?: unknown } | undefined)?.mode,
    renderBackend: f?.rendering?.backend === 'webgpu' ? 'webgpu' : 'webgl2',
    screenFit: resolveScreenFit(manifest),
  };
}

/**
 * The runtime settings with the clips whose import settings choose how they load. Those live in the
 * assets' own `.meta`, not in the project manifest, so whoever has the asset index adds them here.
 */
export function withAudioLoadTypes(
  rc: RuntimeProjectConfig, loadTypes: Readonly<Record<string, 'streaming' | 'decompress'>> | undefined,
  encoded?: Readonly<Record<string, { seconds: number; lead: number }>>,
): RuntimeProjectConfig {
  const [types, trims] = [Object.keys(loadTypes ?? {}).length > 0, Object.keys(encoded ?? {}).length > 0];
  if (!types && !trims) return rc;
  // What the cook did to each clip it re-encoded rides beside how each is loaded: both are the cook's to know.
  return { ...rc, audioConfig: { ...rc.audioConfig, ...(types ? { loadTypes: { ...loadTypes } } : {}), ...(trims ? { encoded: { ...encoded } } : {}) } };
}

/** The settings a shipped build carries, as `game.config.json` spells them. */
export type PackagedRuntimeFields = Pick<
  PackagedGameConfig,
  'ySortLayers' | 'depthLayers' | 'colorSpace' | 'outputTransform' | 'renderBackend' | 'screenFit'
  | 'msaaSamples' | 'quality'
  | 'uiTheme' | 'uiThemeColors'
  | 'physicsEnabled' | 'physicsConfig' | 'physics3dBackend' | 'physics3dWorld' | 'audioConfig' | 'achievements' | 'steamAppId' | 'runtime'
>;

/**
 * The shipped-build slice of the config, with defaults OMITTED — absence is how
 * `game.config.json` and the generated mini-game / playable boots all express a
 * default, so an untouched project ships the same bytes it always did.
 *
 * Every packaged target goes through this one function rather than restating the
 * list, which is what makes "the export forgot a setting" impossible to write
 * rather than merely unlikely.
 */
export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntimeFields {
  return {
    ...(rc.ySortLayers ? { ySortLayers: rc.ySortLayers } : {}),
    ...(rc.depthLayers ? { depthLayers: rc.depthLayers } : {}),
    ...(rc.colorSpace === 'linear' ? { colorSpace: rc.colorSpace } : {}),
    ...(rc.outputTransform !== 'none' ? { outputTransform: rc.outputTransform } : {}),
    ...(rc.msaaSamples !== 4 ? { msaaSamples: rc.msaaSamples } : {}),
    // The block also carries three delivery choices that have nothing to do with a quality level (compile shaders in the background, warm them up
    // behind the splash, draw only changing frames); with the level off they must still ship, or the switch is read from a project and never reaches a game.
    // A named level ships, `off` too: left out, it would read as no level and a phone would take medium over the author's word.
    ...(rc.qualityModeNamed ? { quality: rc.quality } : qualityShips(rc.quality) ? { quality: withoutMode(rc.quality) } : {}),
    ...(rc.renderBackend === 'webgpu' ? { renderBackend: rc.renderBackend } : {}),
    // ALWAYS, even with the fit off (`scaleMode < 0`): it carries the design
    // resolution, which is what a desktop window opens at. One representation, or
    // the window grows a second one that drifts.
    screenFit: rc.screenFit,
    ...(rc.uiTheme === 'light' ? { uiTheme: rc.uiTheme } : {}),
    ...(Object.keys(rc.uiThemeColors).length > 0 ? { uiThemeColors: rc.uiThemeColors } : {}),
    // Physics and the mixer ride along only when the project actually declared
    // something: a build whose settings are all defaults keeps the config it has
    // always had, byte for byte, and the runtime falls back to the same values
    // this would have spelled out.
    ...(rc.physicsEnabled ? { physicsEnabled: true } : {}),
    ...(isDefaultPhysics(rc.physicsConfig) ? {} : { physicsConfig: rc.physicsConfig }),
    ...(rc.physics3dBackend === 'physx' ? { physics3dBackend: rc.physics3dBackend } : {}),
    ...(isDefaultPhysics3dWorld(rc.physics3dWorld) ? {} : { physics3dWorld: rc.physics3dWorld }),
    ...(rc.audioConfig.buses?.length || rc.audioConfig.maxVoices !== undefined
      || Object.keys(rc.audioConfig.loadTypes ?? {}).length > 0 || Object.keys(rc.audioConfig.encoded ?? {}).length > 0
      ? { audioConfig: rc.audioConfig } : {}),
    ...(Object.keys(rc.runtime).length > 0 ? { runtime: rc.runtime } : {}),
    ...(rc.achievements.length ? { achievements: rc.achievements } : {}),
    ...(rc.steamAppId > 0 ? { steamAppId: rc.steamAppId } : {}),
  };
}

function withoutMode(quality: QualityConfig): QualityConfig {
  const { mode: _unnamed, ...rest } = quality;
  return rest;
}

/** Whether a build has anything to be told about quality: a level, or one of the delivery choices that hold whatever the level. */
export function qualityShips(quality: QualityConfig): boolean {
  return quality.mode !== 'off' || quality.asyncShaderCompile === true
    || quality.prewarmShaders === true || quality.renderOnDemand === true;
}

/** Whether the world config is exactly what a runtime would default to anyway. */
function isDefaultPhysics3dWorld(world: Physics3DWorldConfig): boolean {
  return JSON.stringify(world) === JSON.stringify(DEFAULT_PHYSICS3D_WORLD);
}

function isDefaultPhysics(config: Physics2DPluginConfig): boolean {
  return JSON.stringify(config) === JSON.stringify(DEFAULT_PHYSICS_CONFIG);
}

/** What the cook does to a project's assets, as three flags it takes. */
export interface CookOptions {
  compressTextures: boolean;
  compressAudio: boolean;
  atlasTextures: boolean;
}

/**
 * The cook flags a project's `assetCompression` means. One derivation for the
 * same reason {@link runtimeConfigOf} is one: the Build dialog derived these
 * itself and the headless export passed none of them, so every automated
 * package shipped raw — verifying a build configuration no user ships.
 */
export function cookOptionsOf(manifest: Pick<ProjectManifest, 'packaging'>): CookOptions {
  const on = (manifest.packaging?.assetCompression ?? 'auto') === 'auto';
  return { compressTextures: on, compressAudio: on, atlasTextures: on };
}

/**
 * The packaging POLICY a headless export must carry, beyond the cook's.
 *
 * Third derivation of this shape and the third time for one reason: the Build
 * dialog reads these settings and the command line did not, so an automated
 * package silently differed from the one a person makes.
 */
export interface PackagingOptions {
  /** What the project says about its engine modules; see ProjectFeatures.modules. */
  features: ProjectFeatures | undefined;
  /** Per-target overrides laid over those. */
  modulesByPlatform: ProjectPackaging['modulesByPlatform'];
  compressWasm: boolean;
  engineSubpackage: boolean;
  excludeScenes: string[];
  sourcemap: boolean;
  minifyScripts: boolean;
  appIcon: string | undefined;
  /** How the page's start screen should look; see SplashPackaging. */
  splash: ProjectPackaging['splash'];
}

export function packagingOptionsOf(manifest: Pick<ProjectManifest, 'packaging' | 'features'>): PackagingOptions {
  const p = manifest.packaging;
  return {
    // What the project says about its engine modules rides with the packaging
    // options because every caller already spreads those — a second place to
    // remember is a place one caller forgets.
    features: manifest.features,
    modulesByPlatform: p?.modulesByPlatform,
    compressWasm: p?.compressWasm ?? false,
    engineSubpackage: p?.engineSubpackage ?? false,
    excludeScenes: p?.excludeScenes ?? [],
    // A shipping build carries no maps unless the project asked; `config` is the
    // word the dialog uses for the same choice.
    sourcemap: p?.sourceMaps ?? (p?.config === 'development'),
    minifyScripts: p?.minifyScripts ?? true,
    appIcon: p?.icon,
    splash: p?.splash,
  };
}

/** The effective settings of a project with nothing declared — every default. */
export const DEFAULT_RUNTIME_CONFIG: RuntimeProjectConfig = runtimeConfigOf({});

/** The physics world an undeclared project runs, for "is this worth shipping". */
const DEFAULT_PHYSICS_CONFIG: Physics2DPluginConfig = DEFAULT_RUNTIME_CONFIG.physicsConfig;