Skip to content

02 3 Quick Start Utopia

Jump to bottom
evets17 edited this page Mar 13, 2026 · 4 revisions

Quick Start: Utopia

This page explains the game-level override used for Utopia.

Config file used

  • {usb_root}\boosted\Utopia_boost.toml

What this example demonstrates

Utopia introduces four key Sprint Boost concepts:

  • Using game_info values in real time (p1_money, p2_money)
  • Creating a better 2-player aid experience with player-specific overlay hotkeys
  • Using {gi.*} substitutions with image fallback to change helper visuals between title/terms and in-game states
  • Overriding folder level settings by setting default display to 16:9

Utopia game-level config

# -------------GAME INFO-------------
[game_info.values.p1_money]
address = "0x016B"
decode = "u16"

[game_info.values.p2_money]
address = "0x016D"
decode = "u16"

# -------------DISPLAY SETTINGS--------
[display]
default_layout = "fullscreen16x9"

[[display.layouts.secondary_player1.elements]]
type = "image"
source = "{gv.assets_images}/Utopia_Aid_Terms_{gi.p1_money}.png" # if score is 0 then show terms image else show costs image
fallback =  "{gv.assets_images}/Utopia_Aid_Costs.png"
x = 100
y = { anchor = "center" }
width = "100%"
height = "100%"
scaling = "none"
alpha = 1.0

[[display.layouts.secondary_player2.elements]]
type = "image"
source = "{gv.assets_images}/Utopia_Aid_Terms_{gi.p2_money}.png"  # if score is 0 then show terms image else show costs image
fallback =  "{gv.assets_images}/Utopia_Aid_Costs.png"
x = { anchor = "right", offset = -100 }
y = { anchor = "center" }
width = "100%"
height = "100%"
scaling = "none"
alpha = 1.0

# -------------- INPUTS: HOTKEYS -------------
# show secondary layout while pressing both bottom action buttons
# Override hotkey so player 1 shows on their side and player 2 on their side
[[input.hotkeys.binding]]
keys = ["C1_ACTION_LEFT", "C1_ACTION_RIGHT" ]
on_press = { command = "show_layout", layout = "secondary_player1" }
on_release = { command = "hide_layout" }
menu_enabled = true
duration_ms = 0

[[input.hotkeys.binding]]
keys = ["C2_ACTION_LEFT", "C2_ACTION_RIGHT" ]
on_press = { command = "show_layout", layout = "secondary_player2" }
on_release = { command = "hide_layout" }
menu_enabled = true
duration_ms = 0

How the 2-player overlay behavior works

Quick Start: Base defines a shared overlay hotkey that shows one common layout by pressing both bottom action buttons.

Utopia overrides that behavior at the game level:

  • Player 1 hold combo shows secondary_player1 (left-side aid near Player 1)
  • Player 2 hold combo shows secondary_player2 (right-side aid near Player 2)

This avoids covering the opponent’s side and creates a cleaner 2-player experience.

How game_info substitution + fallback works here

Each player layout uses a dynamic source image:

  • Utopia_Aid_Terms_{gi.p1_money}.png
  • Utopia_Aid_Terms_{gi.p2_money}.png

Because {gi.*} is substituted from live memory:

  • On title/terms screens, each player’s money value is 0.
  • That 0 value makes Sprint Boost look for the ..._0.png terms-aid image, so the terms image is shown.
  • After the game starts, money is no longer 0, so that exact terms-image filename usually does not exist.
  • When that file is missing, Sprint Boost uses fallback:
    • Utopia_Aid_Costs.png (gameplay aid image)

Quirk of this approach:

  • If a player ever drops to 0 money during gameplay, the terms image will appear again for that player.
  • (The player can’t afford to show the gameplay aid 😄.)

This gives a practical “state-sensitive” visual effect without requiring menu interaction.

Why this is useful

This pattern is useful for games where players need quick reference aids but should only see aids on their own side.

It also shows a simple way to drive visual changes from game memory values.

Next step

Continue to another game example:

Clone this wiki locally