03 09 Config play_stats

03 09 Config play_stats

This page explains play_stats in Sprint Boost.

What play_stats is

play_stats tracks selected values during play and can persist those values between sessions.

A common first use is high scores, but play_stats is not limited to high scores.

More than high scores

play_stats can track any value sourced from game_info, including:

• score
• lives-related counters
• items collected/used
• custom game-specific counters

If it can be represented through game_info, it can usually be tracked by play_stats.

Why play_stats matters

Key benefits:

• Persistence: keep tracked records between sessions
• Leaderboards: display ranked historical values. play_stats is a pre-requisite for the leaderboards layout element.
• Dynamic display layouts: show tracked values in custom overlays/screens
• Realtime display values: show current tracked session values live

Where play_stats can be used

play_stats is relevant for:

• boost_mode = "enhanced"

In current Sprint Boost behavior, play-stats runtime flow is used with enhanced display/runtime paths.

Basic play_stats example (high score)

[play_stats]
enabled = true
stats_file = "{gv.game_play_stats_path}"
auto_save_quit = true
auto_save_reset = true

[play_stats.players.p1]
label = "P1"

[play_stats.players.p1.tracked.score]
game_info = "p1_score"
mode = "final"

What this does:

• Enables play-stats tracking
• Saves to a persistent stats file
• Tracks P1 score using game_info = "p1_score"

Players and labels

play_stats supports tracking for one or more players.

You can track the same stat pattern for multiple players, each under its own key:

• play_stats.players.p1
• play_stats.players.p2
• or any player key name you choose

For single-player games, a simple key like player is perfectly fine:

[play_stats.players.player]
label = "Player"

players.<player>.label is used as the player name shown in leaderboards.

Practical tip:

• Short labels like P1 / P2 are usually best, especially when leaderboard width is limited.

Save behavior

You can persist stats with:

• auto_save_quit = true (save on quit)
• auto_save_reset = true (save on reset)
• manual save command (save_play_stats) from menu/hotkey

This gives you flexible control over when data is written.

Sessions and reset behavior

play_stats tracks values within a play-stats session.

Important reset setting:

• clear_stats_on_reset controls whether tracked session values are cleared when reset is triggered through Sprint Boost reset flow.
• In most cases, keeping this true (default) is best.

Reset caveat:

• If a reset happens outside Sprint Boost control flow (for example through an emulator-side kbdhackfile reset hotkey), Sprint Boost does not reliably know a reset occurred.
• In that case, play-stats session values may not be cleared at that moment.

Tracked modes (full supported list)

play_stats.players.<player>.tracked.<stat>.mode supports:

• final: save the most recent value.
• peak: save the highest value seen.
• lowest: save the lowest value seen.
• count_change: count every value change.
• count_increase: count how many times value increased.
• count_increase_reset_aware: count increases and reset-boundary carry-ins.
• count_decrease: count how many times value decreased.
• amount_increased: accumulate total increase amount.
• amount_increased_reset_aware: accumulate increases with reset-boundary carry-in handling.
• amount_decreased: accumulate total decrease amount.

Example beyond high score

[play_stats.players.p1.tracked.food_bags_collected]
game_info = "food_count"
mode = "count_increase"

[play_stats.players.p1.tracked.food_consumed]
game_info = "food_count"
mode = "amount_decreased"

This tracks two behavior stats from the same underlying value:

• how many collection events occurred
• how much total resource was consumed

Save conditions (optional)

Use save_conditions to skip trivial runs.

You can define more than one save condition for a player.

When multiple conditions are defined, all conditions must pass for that player record to be saved.

[[play_stats.players.p1.save_conditions]]
game_info = "p1_score"
op = "gt"
value = 0

Meaning: only save when score is greater than 0.

Update conditions (optional)

Use update_conditions to update a stat only when a condition is true (for example active player checks in 2-player games).

[play_stats.players.p1.tracked.score]
game_info = "active_score"
mode = "amount_increased"

[[play_stats.players.p1.tracked.score.update_conditions]]
game_info = "active_player"
op = "eq"
value = 1

Realtime display usage

Live tracked values can be shown in display substitutions:

• {ps.<player>.<stat_key>}
• shorthand {ps.<stat_key>}

Example:

[[display.layouts.hud.elements]]
type = "text"
text = "P1 Total: {ps.p1.score}"
x = 20
y = 30
width = 300
height = 40
color = "#FFFFFF"
align = "left"
size = 26

Override behavior

play_stats follows normal config precedence:

• folder-level can define shared tracking patterns
• game-level can override tracked stats and save behavior

In practice, most tracked keys are game-specific because they depend on each game’s game_info setup.

Practical tips

• Start with one tracked stat and confirm it saves correctly.
• Add additional stats one at a time.
• Use high score as a starter pattern, then expand into game-specific metrics.
• Use manual save for intentional persistence workflows.
• You can manually edit the play_stats save file's player_label attribute if wanting to put a person's identifier on a particular stat, then that name will display in leaderboard if not too long.

Next step

Continue to:

• 03 10 Config cheats