03 06 Config menus

03 06 Config menus

This page explains how to configure Sprint Boost menus.

Menu launch is tied to game pause flow: when pause is triggered, Sprint Boost opens the configured pause menu.

Why menus are useful

Menus give players an in-game control panel for common actions, such as:

• resume/reset/quit
• switching layouts
• opening submenus
• triggering game-specific helpers

Pause-linked menu launch (important)

Menus are designed around pause behavior.

• You set which menu opens on pause using menu.on_pause.
• In most setups, this points to a menu named pause.
• When gameplay is paused, that menu opens.
• While paused, CLEAR can hide/show the root pause menu.

Where menus can be used

Menu settings are relevant for:

• boost_mode = "enhanced"

Menus require the enhanced display/runtime path and are not used in pure passthrough behavior.

Basic menu example

[menu]
on_pause = "pause"

[menu.menus.pause]
header = "Pause Menu"
footer = "Press 'clear' to hide/show menu"
allow_directional_nav = true

[menu.menus.pause.item1]
label = "Resume"
action = { command = "emulator_command", value = "PAUSE_OFF" }

[menu.menus.pause.item2]
label = "Reset"
action = { command = "emulator_command", value = "RESET" }

[menu.menus.pause.item3]
label = "Quit"
action = { command = "emulator_command", value = "QUIT" }

[menu.menus.pause.item9]
label = "Display"
action = { command = "show_menu", menu = "display" }

Core menu concepts

menu.on_pause

Controls which menu opens when the game pauses.

[menu]
on_pause = "pause"

Menu definitions

Each menu is defined under:

• menu.menus.<menu_name>

Menu items are named slots such as:

• item1, item2, item9, item0

Each item has:

• label
• action

Submenus

Use show_menu to open another menu.

[menu.menus.pause.item9]
label = "More"
action = { command = "show_menu", menu = "more" }

Header, footer, and fonts

Each menu can include a header and footer for user guidance.

[menu.menus.pause]
header = "Pause Menu"
footer = "Press 'clear' to go back or hide/show"

Recommended usage:

• header: short title (where the user is)
• footer: short hint (how to navigate/back)

Menu fonts are configured on [menu]:

[menu]
header_font_path = "{gv.assets_fonts}/menu_header.ttf"
item_font_path = "{gv.assets_fonts}/menu_item.ttf"
footer_font_path = "{gv.assets_fonts}/menu_footer.ttf"

If menu font paths are not set, Sprint Boost uses built-in default Sprint font paths.

You can also tune menu text size under [menu.style]:

• header_font_size
• item_font_size
• footer_font_size

Navigation behavior

Menu navigation supports both directional and numeric selection styles.

Directional style

• Use directional input (up/down) to move selection
• Press ENTER to activate selected item
• Requires allow_directional_nav = true on that menu

Number-key style

• Press number keys to select slot items directly (item1, item2, etc.)
• This is often the fastest way to trigger common actions

CLEAR behavior

• In a submenu: CLEAR goes back one menu level
• At root pause menu: CLEAR hides the menu while staying paused
• Press CLEAR again while still paused to show the pause menu again

Common commands (menus)

Common menu action commands:

• emulator_command → args: value (required)
• show_menu → args: menu (required)
• close_menu → args: none
• switch_layout → args: layout (required)
• toggle_layout → args: layout (required)
• show_layout → args: layout (required)
• hide_layout → args: none
• save_play_stats → args: none
• set_game_info → args: game_info (required), value (required), min_value (optional), max_value (optional)
• offset_game_info → args: game_info (required), value (required), min_value (optional), max_value (optional)

Example:

[menu.menus.pause.item4]
label = "Show Guide"
action = { command = "show_layout", layout = "secondary_layout_default" }

Menu style (optional)

Menu appearance can be customized under [menu.style].

Full example:

[menu.style]
x = "center"
y = { anchor = "top", offset = 16 }
width = 0
height = 0
padding = 8
line_gap = 20

header_font_size = 50
item_font_size = 36
footer_font_size = 22

show_panel = true
panel_color = "#3c70aa"
panel_alpha = 220
panel_border = true
panel_border_color = "#FFFFFF"
panel_border_alpha = 220

header_color = "#000000"
footer_color = "#000000"
item_color = "#ffffff"
selected_item_color = "#FFFF66"
slot_color = "#A0A0A0"

menu.style setting guide:

• x: horizontal menu panel position.

• y: vertical menu panel position.

• width: panel width (0 means auto-size to content).

• height: panel height (0 means auto-size to content).

• padding: inner spacing between panel edge and text.

• line_gap: vertical gap between text rows.

• header_font_size: header text size.

• item_font_size: item text size.

• footer_font_size: footer text size.

• show_panel: enable/disable menu background panel.

• panel_color: panel fill color.

• panel_alpha: panel fill opacity (0 transparent to 255 opaque).

• panel_border: enable/disable panel border.

• panel_border_color: panel border color.

• panel_border_alpha: panel border opacity (0 to 255).

• header_color: header text color.

• footer_color: footer text color.

• item_color: non-selected item text color.

• selected_item_color: highlighted item text color.

• slot_color: slot prefix color (for numbered slot indicator text).

If you are just starting, keep defaults first, then change style values one group at a time.

Override behavior

Menus follow normal precedence rules:

• Folder-level menus provide shared defaults
• Game-level menu config can override labels/actions for one title

Practical pattern:

• keep a shared pause menu at folder level
• extend per-game menu items (often starting at item9 downward)

Practical tips

• Keep top-level pause menu small and readable.
• Use submenus for advanced options.
• Prefer clear labels like Reset, Quit, Switch to 4:3.
• Add game-specific menu items only when needed.

Next step

Continue to:

• 03 07 Config maps