Skip to content

02 2 Quick Start Pitfall

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

Quick Start: Pitfall

This page shows two useful ways to use a game-level Pitfall override.

The short version:

  • basic mode is the simple option. It still honors jzintv settings in the file, such as palette changes.
  • enhanced mode turns on Sprint Boost features such as memory reading, expressions, play stats, and custom overlays.

Config file used

  • {usb_root}\boosted\Pitfall_boost.toml

Why Pitfall is a good example

Pitfall is a good teaching example because it can be used in two stages:

  1. As a simple per-game override that only changes emulator behavior.
  2. As an enhanced setup that builds a usable score, saves play stats, and shows a custom high-score screen.

That makes it a good model for people who want to start simple and then add more Sprint Boost features later.

Option 1: Basic mode

If you set Pitfall to basic, Sprint Boost will use a more standard emulator-style setup for that game.

In this mode, the file still honors jzintv settings such as flags, but it does not use enhanced Sprint Boost features like:

  • game_info
  • expression
  • play_stats
  • enhanced display overlays and leaderboards

Example:

boost_mode = "basic"

[jzintv.flags]
gfx-palette = "{gv.assets_palettes}/pf_palette.txt"

What this means in plain language:

  • Pitfall still gets its custom palette.
  • The game runs in the simpler, more traditional mode.
  • The rest of the advanced Pitfall-specific Sprint Boost features are ignored until you switch to enhanced.

This is useful when you want to keep a game close to stock behavior while still applying a few emulator options.

Option 2: Enhanced mode

If you change the file to boost_mode = "enhanced", the rest of the Pitfall setup becomes active.

That is what unlocks the more "boosted" experience:

  • Sprint Boost can read live memory values from the game.
  • It can build a proper score from raw bytes.
  • It can keep track of score for play stats.
  • It can save that score when a run ends.
  • It can show a custom high-score overlay.

At a high level, the file works like this:

Step 1: Read the raw score pieces

Pitfall does not store score in a directly usable way.

Instead, the config reads several memory values that represent the score digits:

  • ones
  • tens
  • hundreds
  • thousands
  • ten-thousands

These are defined under game_info.

You can think of game_info as: "read useful live values from the game so Sprint Boost can work with them."

Step 2: Turn those pieces into a real score

Once the raw digit values are available, the config uses expression entries to turn them into something normal.

This is the job of expression.int.derived_score.

You can think of expressions as little helper rules:

  • first clean up each raw digit
  • then add the digits together into one final score

That gives Sprint Boost a single score value it can actually use.

How play stats uses that score

After the score is turned into a normal value, play_stats can track it.

In this Pitfall example, the tracked score uses:

[play_stats.players.p1.tracked.score]
expression = { int = "derived_score" }
mode = "final"

At a high level, that means:

  • use the score built by the expression system
  • keep the score for the current run as Sprint Boost tracks it

In the current Pitfall setup, score preservation is handled mainly by the save and reset behavior rather than by a special score-update rule.

How the run gets saved

Pitfall also defines a session trigger:

[play_stats.session_triggers.game_over]
game_info = "game_state"
trigger = { mode = "changes_to", value = 0 }

In plain language, that means:

  • watch the Pitfall game state
  • when it changes to the value used for the start screen / game over transition
  • treat that as the end of the current play session

Because play_stats.session_triggers.auto_save = true, Sprint Boost can save the current run automatically when that transition happens.

The setting below is also important:

clear_stats_on_reset = false

This tells Sprint Boost not to wipe the current tracked stats just because the emulator reset action happened. That is useful when you want Pitfall's own in-game transition to control when the score gets saved.

The Pitfall example also uses a save condition:

[[play_stats.players.p1.save_conditions]]
play_stat = "score"
op = "gt"
value = 1000

In plain language, that means:

  • only save runs where the tracked score is above 1000
  • ignore tiny or accidental runs

Together, these settings give Pitfall a practical flow:

  • keep the tracked score in memory even if the emulator reset happens
  • wait for the game's own end-of-run transition
  • save only runs that reached a meaningful score

Custom leaderboard display

The Pitfall example also includes a simple custom overlay with:

  • a background image
  • a leaderboard that reads from the saved score play stat

This makes Pitfall a nice example of how enhanced mode can connect three pieces together:

  • live game data
  • score building through expressions
  • saved history shown back to the player

Recommended way to read this example

If you are new to Sprint Boost, read the Pitfall file in this order:

  1. boost_mode
  2. jzintv.flags
  3. game_info
  4. expression
  5. play_stats
  6. display

That gives a simple mental model:

  • basic mode = use only the emulator-related settings in the file
  • enhanced mode = let Sprint Boost read game state, build helpful values, track stats, and show them

Next step

Continue to another game example:

Clone this wiki locally