Game options, preferences & settings

A game declares three kinds of configurable fields on its game info (the admin panel's game form — see Adding a game). They share the same field shape, but serve different purposes:

All three are version-scoped: they live on the game info of a specific game version, so a new engine version can expose a different set.

Field shape

Every entry — option, preference or setting — is an object with:

{
	"name": "variableMap",
	"label": "Variable map",
	"type": "select",
	"default": "standard",
	"items": [
		{ "name": "standard", "label": "Standard map" },
		{ "name": "random", "label": "Random map" }
	]
}

• name — the key the value is stored and passed under (what your engine/viewer reads).
• label — what the UI shows next to the input.
• type — one of "checkbox", "select", "hidden", "category" (see below).
• default — optional default value: a boolean for checkboxes, an item name for selects.
• items — for "select" only: the list of choices, each with a name (the value) and a label (display).
• category — preferences only: the name of a "category" entry this preference is grouped under.

Types

• checkbox — a boolean flag. Values are true/false; the UI pre-checks it when default is true.

  { "name": "noAuction", "label": "Skip the auction phase", "type": "checkbox", "default": false }
  

• select — one choice out of items. When default is missing or not a valid item name, the first item is the effective default — order items accordingly.

  {
      "name": "map",
      "label": "Map",
      "type": "select",
      "default": "classic",
      "items": [
          { "name": "classic", "label": "Classic" },
          { "name": "lakes", "label": "Lakes" }
      ]
  }
  

• hidden — never rendered in the UI; the value is passed through as a JSON-stringified blob ({ stringified: true, value: string }). For advanced/machine-set preference values, not for regular options.

• category — a collapsible group heading in the preferences UI. Not a value itself: other preferences point at it with their category field.

  { "name": "display", "label": "Display", "type": "category" },
  { "name": "flatBuildings", "label": "Flat buildings", "type": "checkbox", "category": "display" }
  

Options (game creation)

The creation form renders one input per entry of options and sends the chosen values with the game. The server validates them (checkboxes must be boolean, selects must be one of their item names) and stores them on the game as game.game.options — the per-game record the engine later receives. (The top-level game.options is a different, platform-owned object holding setup/timing/meta — see Game clocks & timing; don't confuse the two.) When the game starts, the engine receives game.game.options as the third argument of init(players, expansions, options, seed, creator):

// admin panel: options = [{ name: "map", type: "select", items: [...] }, { name: "noAuction", type: "checkbox" }]
// creator picked map "lakes" and ticked "noAuction" → at game start:
init(4, [], { map: "lakes", noAuction: true }, "game-seed", 0);

Which keys are present depends on the field type: every select is always sent (the form initializes it to its default, or the first item when there's no default), and every checkbox whose default is true is always sent as true. Only unchecked checkboxes are omitted — so a checkbox key may be absent, while a select key is effectively always there. Still read options defensively (options.map ?? "classic"): an engine shouldn't break on a missing or unexpected key.

Player counts are not an option: the allowed player counts are the players array on the game itself (e.g. [2, 3, 4, 5]), set in the admin panel's main game form. The creator picks one of them at creation; the engine gets it as init's first argument.

Preferences (per-user viewer settings)

Preferences are UI concerns: each user sets them once per game (sidebar on the game page / account page), and the viewer receives them through the preferences event every time it launches and whenever they change. The engine never sees them.

[
	{ "name": "flatBuildings", "label": "Flat buildings", "type": "checkbox", "default": false },
	{ "name": "planetColors", "label": "Original planet colors", "type": "checkbox", "default": true }
]

The platform fills in default values for users who never saved preferences, so the viewer can rely on declared checkbox/select keys being present.

On top of the game's own preferences, the platform injects devMode: true when the user has developer settings enabled (see viewer-api), and an alternateUI checkbox is added automatically when the game info defines an alternate viewer.

Settings (per-player, in-game)

Settings are engine concerns a player can toggle while the game is running — e.g. Gaia Project's autocharge. The game UI renders inputs from the settings list; on change, the client posts the whole settings object (not just the changed key), and the game-server keeps the declared keys whose values pass validation (checkboxes must be boolean, selects one of their item names) and calls the engine's setPlayerSettings(data, player, settings) with that full validated set. So setPlayerSettings receives every declared setting each time — apply them wholesale rather than assuming only a diff arrives. The engine should expose the current values through playerSettings(data, player).

A setting can carry a faction field ("faction": "terrans") to only apply to players of that faction.

[
	{ "name": "autocharge", "label": "Auto-charge power", "type": "checkbox", "default": true },
	{
		"name": "autoLeech",
		"label": "Auto-leech",
		"type": "select",
		"items": [
			{ "name": "always", "label": "Always" },
			{ "name": "ask", "label": "Ask" },
			{ "name": "never", "label": "Never" }
		]
	}
]

Settings change game behavior, so they belong to the engine's state handling — don't confuse them with preferences, which are pure presentation and live entirely in the viewer.