The settings system

Mission configuration defaults loaded from settings.yaml (or legacy setup.json).

Overview

settings_get_defaults() returns a dict of built-in defaults merged with mission-specific overrides from settings.yaml in the mission directory. The result is cached after the first call, so all modules that read settings see a consistent snapshot.

Common use-cases:

Reading built-in settings like DIFFICULTY, PLAYER_COUNT, WORLD_SELECT, or operator-mode config.
Adding module-specific defaults with settings_add_defaults so that a module's settings are visible in settings_get_defaults() even when the author hasn't created a settings.yaml.

Quick example

MAST pyMAST

== setup ==
    settings = settings_get_defaults()
    difficulty = settings.get("DIFFICULTY", 5)
    log(f"Difficulty is {difficulty}")

from sbs_utils.procedural.settings import settings_get_defaults, settings_add_defaults

# Read built-in settings
settings = settings_get_defaults()
difficulty = settings.get("DIFFICULTY", 5)
player_count = settings.get("PLAYER_COUNT", 1)

# Register module-specific defaults (won't override settings.yaml values)
settings_add_defaults({
    "ENEMY_COUNT": 10,
    "BOSS_ENABLED": False,
})

Built-in settings keys

Key	Default	Notes
`DIFFICULTY`	5	Mission difficulty 1–10
`PLAYER_COUNT`	1	Expected number of player ships
`WORLD_SELECT`	`"siege"`	World generation preset
`TERRAIN_SELECT`	`"some"`	Terrain density
`LETHAL_SELECT`	`"none"`	Lethal NPC density
`FRIENDLY_SELECT`	`"few"`	Friendly NPC density
`UPGRADE_SELECT`	`"max"`	Available upgrades
`AUTO_START`	`False`	Skip lobby and start immediately
`GAME_STARTED`	`False`	Set by the game engine at start
`GAME_ENDED`	`False`	Set by mission when over
`GRID_THEME`	0	Engineering grid color theme index
`PLAYER_LIST`	list of 8 ships	Player ship definitions

API

`settings_add_defaults(additions)`

Merge additional keys into the global settings defaults.

additions acts as a fallback — existing values from settings.yaml or setup.json take precedence, so this only fills gaps.

Parameters:

Name	Type	Description	Default
`additions`	`dict`	Default key-value pairs to add if not already present.	required

`settings_get_defaults()`

Return the merged default settings dict, loading settings.yaml or setup.json if present.

Results are cached after the first call. Mission-specific values from the YAML/JSON file override the built-in defaults.

Returns:

Name	Type	Description
`dict`		The default settings mapping.