Skip to content

Mission settings (settings.yaml)

settings.yaml (optional) provides default values the mission reads via settings_get_defaults(). Its keys become variables available to your MAST — and the setup screen's Properties can override them per game.

Common keys

AUTO_START: false            # start the mission the moment it's selected
DIFFICULTY: 5
GAME_TIME_LIMIT: 20          # minutes - your mission decides what this means

# Player ships
PLAYER_CREATE_DEFAULT: true  # let the fleets add-on pre-create ships from PLAYER_LIST
PLAYER_COUNT: 1              # how many are active
PLAYER_SHIP_RESPAWN: false
PLAYER_LIST:
    -   name: "Artemis"
        side: "tsn"
        ship: "tsn_light_cruiser"
        face: "terran"
    -   name: "Intrepid"
        side: "tsn"
        ship: "tsn_battle_cruiser"
        face: "terran"

# Standard docking behavior (LegendaryMissions docking add-on)
DOCKING:
    refuel_amount: 20
    refuel_delay: 2
    shield_delay: 2
    shield_coeff: 2
    torps_delay: 6
    interior_delay: 2
    interior_count: 2

GAMEMASTER:
    enable: true

How they're used

  • Reading: settings_get_defaults() returns them; the standard consoles/fleets add-ons read PLAYER_LIST, PLAYER_COUNT, DIFFICULTY, DOCKING, etc. for you.
  • Overriding per game: a @map/ metadata Properties block puts widgets on the setup screen bound to these variables — e.g. a Difficulty slider var="DIFFICULTY". See Anatomy of a mission.
  • Testing: the sbs tool can override settings without editing this file (--auto-start, --players N, --set KEY=VALUE). See the CLI.
  • Swapping a whole set at once: a profile is a named file of settings — and of add-ons and art packs — selected with profile=<name>.

Everything here is optional — the keys are just defaults your mission (and the add-ons) may read. See the settings API.

Music

MUSIC_SELECT names the music bank: a folder name under data/audio/music, the display name of an @media/music label, or "random" to pick from every bank that is loaded. The library default is "random".

MUSIC_SELECT: "Artemis2"     # or "random", or a mod's bank

Leaving it out is a choice, not an oversight. A key present in a mission's settings.yaml is explicit, so it outranks any add-on's settings_set_mod_default() — pinning it here stops every mod built on that mission from supplying its own soundtrack. LegendaryMissions deliberately ships the line commented out. Set it when you mean this mission to sound a particular way; leave it alone otherwise.

Skyboxes no longer choose the music. See the media system for the full precedence, the console's Music dropdown, and music_play_sting() for end-of-game stingers that follow whichever bank is playing.