Skip to content

03 00 Configuration Overview

Jump to bottom
evets17 edited this page Apr 2, 2026 · 5 revisions

Configuration Overview

Sprint Boost is configured with simple text files named boost.toml.

If you are new to configuration files, that is okay. You do not need to be a programmer to use Sprint Boost.

Sprint Boost uses TOML format because it is readable and easy to organize.

The big idea: two config levels

Sprint Boost reads configuration from two places:

  • Folder-level config: a boost.toml in a folder (for shared defaults)
  • Game-level config: a Game Name_boost.toml file (for one specific game)

Think of it like this:

  • Folder-level config sets the starting rules for many games
  • Game-level config applies game-specific changes on top

This lets you set common behavior once, then customize only what each game needs.

Order of precedence (who wins)

When both levels define the same setting, the game-level value wins.

  • Folder-level = base/default behavior
  • Game-level = override behavior for that game

This is why Quick Start can have shared controls, shared menus, and shared paths, while specific games still change layouts, hotkeys, or stats.

Sprint Boost "fail quietly" behavior

Sprint Boost is designed to keep running even when some optional config pieces are missing or not usable.

In practice, this means:

  • If an optional image or layout detail is missing, Sprint Boost tries fallback behavior
  • If a game-level file only overrides a few settings, everything else keeps using folder-level defaults
  • If something in config is not applied, Sprint Boost generally continues instead of hard-failing the full game launch

This approach helps avoid "all-or-nothing" setups and makes iteration safer.

Quick TOML concepts (plain language)

You will see a few patterns repeatedly:

  • Key/value: enabled = true (a setting with one value)
  • True/false value: true means on, false means off
  • Table/block: [display] groups related settings
  • List/array: keys = ["C1_ACTION_LEFT", "C1_ACTION_RIGHT"] stores multiple values

You do not need to memorize this all at once. The subpages below explain each system with examples.

How overrides work in practice

At a high level, Sprint Boost merges folder-level and game-level configs.

Table-style override (replace one property)

When you override one setting inside a table, you usually only replace that one property.

Example idea:

  • Folder-level default: [display] default_layout = "fullscreen"
  • Game-level change: [display] default_layout = "tot_layout"

Result:

  • default_layout changes for that game
  • Other display settings from folder-level remain in effect unless also overridden

Array/list override (replace the full list)

For list-style settings (especially ordered items), an override usually replaces that whole list section you define.

Example idea:

  • Folder-level config defines a layout with multiple elements
  • Game-level config wants a different image in that layout

Result:

  • The game-level elements list becomes the active list for that layout
  • In practice, this means you usually redefine that layout’s full elements list for the game

Important practical note:

  • For layout elements, there is generally not an in-place "change just one property on existing element #N" behavior.
  • Example: if you want to change only one image source in an inherited layout, you typically provide the game-level layout elements list you want Sprint Boost to use.
  • If you want to avoid replacing a shared layout, another approach is to define a game-specific layout name and switch to it.

Tip

If you only need small game-specific additions, prefer extending known menu/item slots or adding targeted overrides. If you need a very different behavior, replace the game-level list/table section directly.

Recommended workflow

A simple, reliable way to work:

  1. Start with folder-level defaults in boost.toml
  2. Launch and confirm shared behavior works
  3. Add game-level *_boost.toml only where needed
  4. Override only the sections that must be different
  5. Test on Sprint, then refine

Troubleshooting common config mistakes

1) Wrong letter case in string values

Many string settings are case-sensitive and must use documented lowercase values.

Example (fails):

[[display.layouts.fullscreen.elements]]
type = "game"
x = "center"
y = "center"
width = 960
height = 720
aspect = "Force_4x3"

Why it fails:

  • aspect expects lowercase values like force_4x3, force_16x9, maintain, etc.
  • "Force_4x3" has an uppercase F, so it is not a valid value.

Correct:

aspect = "force_4x3"

2) Invalid boolean style

TOML booleans must be lowercase:

  • valid: true, false
  • invalid: True, False, TRUE, FALSE

3) Token typo in substitutions

Token names are exact. A small typo leaves the value unresolved.

  • valid example: {gv.assets_images}
  • common typo: {gv.asset_images}

If a path/text value does not resolve as expected, double-check token spelling first.

4) Top-level setting accidentally placed inside a table

In TOML, after you open a table (for example [global_variables]), following keys are treated as part of that table until another table header is declared.

Example (problem):

[global_variables]
assets_path = "{usb_mount}/boosted/.boost_assets"
assets_fonts = "{assets_path}/fonts"
assets_images = "{assets_path}/images"
assets_palettes = "{assets_path}/palettes"
game_play_stats_path = "{usb_mount}/boosted/.play_stats/{game_file}.boostats.jsonl"
game_log_path = "{usb_mount}/boosted/.logs/{game_file}.log"

boost_mode = "enhanced"

Why this is a problem:

  • boost_mode is a top-level setting, not a global_variables entry.
  • In this position, TOML treats it as global_variables.boost_mode.

Correct approach:

  • Put top-level settings (like boost_mode) before table blocks.
boost_mode = "enhanced"

[global_variables]
assets_path = "{usb_mount}/boosted/.boost_assets"
assets_fonts = "{assets_path}/fonts"
assets_images = "{assets_path}/images"
assets_palettes = "{assets_path}/palettes"
game_play_stats_path = "{usb_mount}/boosted/.play_stats/{game_file}.boostats.jsonl"
game_log_path = "{usb_mount}/boosted/.logs/{game_file}.log"

5) Repeating table qualifier inside an already-open table

After you declare a table like [display], keys in that block should use local names (for example default_layout), not fully qualified names.

Example (problem):

[display]
display.default_layout = "tc_layout"

Why this is a problem:

  • Inside [display], the key should be default_layout.
  • Writing display.default_layout inside that same block creates the wrong nested path.

Correct:

[display]
default_layout = "tc_layout"

Configuration system pages

Use these pages for each config system:

Next step

If you are unsure where to begin, start with:

Then continue through the pages in order.

Clone this wiki locally