Skip to content

03 05 Config display

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

03 05 Config display

This page introduces Sprint Boost display configuration at a practical level.

Because display config is large, layout definitions are documented on a separate page:

Why display config matters

Display config controls how the game is shown on screen, including:

  • Which layout starts by default
  • Background color
  • Font used for text/leaderboards
  • Optional screensaver behavior after inactivity
  • Whether you can switch layouts at runtime (through menus/hotkeys)

Where display can be used

Display settings are relevant for:

  • boost_mode = "enhanced"

In off and basic, Sprint Boost is not using the enhanced display compositor path.

Basic display section example

[display]
default_layout = "fullscreen"
background_color = "#313131"
font_path = "{gv.assets_fonts}/immortal.ttf"

[display.screensaver]
enabled = false

Core display settings

default_layout

Sets the layout name Sprint Boost tries first at startup.

default_layout = "fullscreen"

Helpful mental model:

  • Sprint Boost has a built-in fullscreen layout behavior that fills the screen with the game.
  • If you define your own layout named fullscreen, your definition becomes the active fullscreen layout.
  • You can set default_layout to any other layout name you define (for example old_tv, tot_layout, etc.).

background_color

Sets the display background/panel color behind layout content.

This is especially noticeable when the game does not fill the full screen.

Common example:

  • If your game view is 4:3, the left/right side areas use background_color.
  • Can choose this color to match their overlay/theme style.
background_color = "#313131"

Related layout-level option:

  • display.layouts.<layout>.enable_game_border_background_color = true
    • Uses current game border color as the active layout background when available.
    • Falls back to display.layouts.<layout>.background_color (if set) or global display.background_color.

font_path

Sets the font used for display text and leaderboard rendering.

font_path = "{gv.assets_fonts}/immortal.ttf"

If omitted, Sprint Boost tries built-in default font locations.

Screensaver

Sprint Boost can automatically switch to a screensaver layout after a period of inactivity.

This is useful when:

  • a cabinet sits idle between players
  • you want a cleaner attract-style idle state
  • you do not want a normal gameplay screen sitting unchanged for long periods

The screensaver is configured under display.screensaver.

Basic example:

[display.screensaver]
enabled = true
inactive_seconds = 30
layout = "screensaver_layout"

Practical example with more control:

[display.screensaver]
enabled = true
inactive_seconds = 45
layout = "screensaver_layout"
pause_emulation = false
drift_pixels_per_second = 24
background_color = "#000000"

enabled

Turns screensaver behavior on or off.

enabled = true

Default:

  • true

If enabled = false, the rest of the screensaver settings are ignored.

inactive_seconds

How long Sprint Boost waits with no activity before showing the screensaver.

inactive_seconds = 30

Default:

  • 0

Practical meaning:

  • 0 means the screensaver will not auto-start from inactivity
  • use a low number if you want a quick idle transition
  • use a higher number if you want the game view to stay visible longer between actions

layout

The layout Sprint Boost should show when the screensaver activates.

layout = "screensaver_layout"

This should be the name of a layout you define under display.layouts.

Common pattern:

  • define a simple layout with one game or image element
  • use that layout only for the screensaver

If layout is missing, Sprint Boost has no screensaver layout to switch to.

pause_emulation

Controls whether Sprint Boost pauses the emulator while the screensaver is active.

pause_emulation = false

Default:

  • true

How to think about this:

  • true: gameplay pauses while the screensaver is active
  • false: the game keeps running in the background while the screensaver is shown

Which to choose:

  • use true for games where you do not want time, danger, or audio continuing unattended
  • use false if you want a more attract-style feel where the game continues behind the scenes

drift_pixels_per_second

Controls how quickly the screensaver image drifts across the screen.

drift_pixels_per_second = 24

Default:

  • 30

Practical meaning:

  • lower values move more slowly
  • higher values move more noticeably
  • this is mainly useful for screensaver layouts that show a centered game or image instead of a full-screen static panel

background_color

Sets a background fill behind the screensaver layout.

background_color = "#000000"

Default:

  • unset

Why you might use it:

  • to fully black out the normal display behind the screensaver
  • to make the idle presentation feel cleaner
  • to avoid the base layout showing around a smaller drifting screensaver view

Screensaver layout example

The screensaver config above points to a normal layout definition.

Simple example:

[display.screensaver]
enabled = true
inactive_seconds = 30
layout = "screensaver_layout"
pause_emulation = false
background_color = "#000000"

[display.layouts.screensaver_layout]

[[display.layouts.screensaver_layout.elements]]
type = "game"
x = "center"
y = "center"
width = 640
height = 480
aspect = "force_4x3"

This gives you:

  • a black background
  • a centered 4:3 game view
  • a smaller presentation that can drift around the screen

For more detailed layout structure and element reference, continue to the layout page.

Layout switching concept

Display layouts are named presets (for example fullscreen, old_tv, or game-specific layouts).

You can:

  • start with one layout using default_layout
  • switch layouts at runtime with menu/hotkey actions like switch_layout

Runtime switching changes the current session view, but does not rewrite your config file.

Sprint window behavior

Sprint usage is effectively single-window.

In practice, most Sprint users can leave window-control settings at defaults and focus on layout configuration (default_layout and layout definitions).

About secondary layouts

A secondary layout is often used as a temporary overlay view.

A common pattern is:

  • Base layout includes type = "game"
  • Secondary layout may include only images/text (no game element)
  • Hotkeys show/hide or toggle that secondary layout for quick reference aids

This is how many field-guide and overlay patterns are built.

Overrides (folder-level vs game-level)

Display config follows normal config precedence:

  • Folder-level display settings provide shared defaults
  • Game-level display settings override for one title

Typical override examples:

  • Change default_layout for one game
  • Use a game-specific font_path
  • Define game-specific layouts while keeping shared defaults elsewhere

Next step

For layout structure, elements, and examples, continue to:

Clone this wiki locally