Mod Game Parameters (defines.yaml)

Babylon exposes every tunable game coefficient in a single, documented, player-editable file — the way Paradox grand-strategy games expose their rules, but in YAML rather than INI. This guide shows how to change the game’s balance without touching any code.

The canonical file

All coefficients live in:

src/babylon/data/defines.yaml

Each value carries an inline comment giving its meaning and valid range, for example:

economy:
  extraction_efficiency: 0.8  # α: imperial extraction capacity (>= 0.0, <= 1.0)
  comprador_cut: 0.9          # fraction kept by the comprador class (>= 0.0, <= 1.0)

The file is grouped into categories (economy, survival, territory, consciousness, …) that mirror the GameDefines schema.

How the game loads it

GameDefines.load_default() reads defines.yaml when it is present and applies your values; if the file is absent it falls back to the compiled schema defaults. The shipped defines.yaml is generated from those defaults, so a fresh checkout plays identically whether or not the file exists.

Change a parameter

  1. Open src/babylon/data/defines.yaml.

  2. Edit any value. Keep the key names, structure, and value types intact — the inline comment tells you the valid range. A value outside its range is rejected by validation at load time.

  3. Restart the simulation. Your values take effect on the next run.

Partial overrides are allowed: a category you omit falls back to its schema defaults, and a field you omit within a present category falls back to that field’s default.

Revert to the shipped defaults

Either delete the file, or regenerate it from the schema:

poetry run python tools/generate_defines_config.py

Regeneration is also required (and enforced in CI) whenever the schema itself changes — a new coefficient, a changed default, or an updated description. To check whether the committed file is in sync:

poetry run python tools/generate_defines_config.py --check

Why not edit the schema directly?

The Python schema in babylon.config.defines defines what parameters exist, their types, and their valid ranges. defines.yaml holds the values. Editing the YAML is the supported, code-free way to rebalance the game; editing the schema is a development change that requires regenerating the YAML and re-running the regression suite.

See Also