Skip to main content

Game config

Game configuration turns authoring options into a resolved GameConfig: DOM container, aspect ratio, internal render resolution, merged input (including optional touch controls), and the stage list. Pass a gameConfig({ ... }) object as the first argument to createGame, or merge fields into a plain object in the options array.

Minimal example​

import { createGame, createStage, gameConfig } from '@zylem/game-lib/core';
import { useArrowsForAxes } from '@zylem/game-lib/input';

void createGame(
  gameConfig({
    id: 'retro-demo',
    preset: 'NES',
    resolution: '256x240',
    input: useArrowsForAxes('p1'),
    mobile: { controls: true, resolution: 'native' },
  }),
  createStage(),
).start();

Full sample: website/snippets/game-and-stages/game-config.ts.

gameConfig fields​

gameConfig returns a plain GameConfigLike object; resolveGameConfig applies defaults when the game starts.

FieldDescription
idGame id; also used as default containerId ('zylem')
globalsInitial game-global key/value tree (see Globals and variables)
stagesStage instances (usually you pass stages as separate createGame arguments instead)
debugEnables debug tooling on the runtime game
timeInitial elapsed time seed
inputBase GameInputConfig; merged with touch controls when mobile.controls is set
aspectRatioNumeric ratio or AspectRatio key (for example 'SixteenByNine')
presetRetro display preset ('NES', 'SNES', …) used to derive aspect and resolution
resolutionInternal buffer: 'WxH', { width, height }, retro preset name, or 'native' for CSS size × DPR
mobileOverrides for mobile profile: aspectRatio, preset, resolution, and controls
mobile.controlstrue or DefaultTouchControlsOptions — auto-injects virtual controls on mobile (enabled: 'auto')
fullscreenWhether the canvas layout uses fullscreen styling (default true)
bodyBackgroundCSS background on document.body (default '#000000')
container / containerId / canvasMount target; a <main> is created if none exists

Device profile resolution​

At start(), the engine chooses desktop vs mobile settings using:

  1. setDeviceProfile / setDisplayRuntime on the Game instance, if set
  2. Otherwise deviceProfile: 'auto' heuristics (isMobile, optional viewport size)

Mobile picks mobile.* overrides when present, then falls back to top-level preset, resolution, and aspectRatio.

Retro resolution helpers​

From @zylem/game-lib/core:

  • getPresetResolution(preset, key?) — pixel size for a named console preset
  • getDisplayAspect(preset) — display aspect for a preset
  • parseResolution(string) — parse '256x240' literals

Use these when building custom UI that lists supported resolutions.

Pitfalls​

  • Multiple config objects in one createGame(...) call are merged; later keys win, but only the first config’s input is kept today—prefer a single gameConfig blob.
  • 'native' resolution skips internal scaling; omitting resolution on desktop leaves the buffer undefined so the renderer follows the viewport.
  • Touch control injection only runs when mobile.controls is set; desktop runtimes stay dormant even if you pass enabled: 'auto' manually elsewhere.

API reference​