Modes and Targets¶

Game modes and targets help track the game state, from simple switch closures to complex wizard modes. The SDK provides a flexible system for managing these states.

Starting a Mode¶

CC++Python

void start_game_mode(sb_game_handle_t state, const char* mode) {
    // Add the mode
    sb_add_mode(state, mode);

    // Commit the change
    sb_commit(state);
}

void start_game_mode(scorbit::GameState& gs, const std::string& mode) {
    // Add the mode
    gs.addMode(mode);

    // Commit the change
    gs.commit();
}

def start_game_mode(gs, mode):
    # Add the mode
    gs.add_mode(mode)

    # Commit the change
    gs.commit()

Ending a Mode¶

CC++Python

void end_game_mode(sb_game_handle_t state, const char* mode) {
    // Remove the mode
    sb_remove_mode(state, mode);

    // Commit the change
    sb_commit(state);
}

void end_game_mode(scorbit::GameState& gs, const std::string& mode) {
    // Remove the mode
    gs.removeMode(mode);

    // Commit the change
    gs.commit();
}

def end_game_mode(gs, mode):
    # Remove the mode
    gs.remove_mode(mode)

    # Commit the change
    gs.commit()

Mode Naming¶

Modes follow a specific format: <CA><n>{<color>}:<Display text>

Categories¶

Prefix	Description	Default Color	Example
`MB:`	Multiball	green	`MB:Multiball`
`BL<n>:`	Ball Locked	green	`BL2:Ball 2 Locked`
`WM:`	Wizard Mode	orange	`WM:Grand Illusion`
`EB<n>:`	Extra Ball	red	`EB1:Extra Ball`
`BX<n>:`	Bonus Multiplier	blue	`BX2:Bonus 2X`
`NA:`	Not Applicable - Used for either targets or modes that aren't easily categorized. This is the most common mode.	yellow	`NA:King Tut x2 bonus`
`CP:`	Completed - Tracks achievements or completed objectives throughout the game. Used for tracking wizard mode requirements or long-term progress. These states persist in session data but don't display on the scoreboard.	green	`CP:Spirit Cards`
`XX:`	Hide From Session Log - Shows on live displays but won't be recorded in CSV session logs. Useful for temporary or rapidly changing states that would clutter the session history.	-	`XX:Spin#`
`ZZ:`	Hide From Clients - Records in CSV session logs but won't display on scoreboards or client apps. Useful for tracking behind-the-scenes achievements or debug states.	-	`ZZ:Special Achievement`
`XY:`	Game Status Override - Replaces the default "Game On" message when no other modes are active. Useful for indicating special game states like simulations or diagnostic modes.	-	`XY:Simulation Active`

Available Colors¶

Color	Usage Example	Common Use Case
red	`MB{red}:Danger Multiball`	Urgent or dangerous modes
orange	`MB{orange}:Dinosaur Multiball`	High-energy or exciting modes
yellow	`WM{yellow}:Light Show`	Warning or special attention modes
green	`CP{green}:Mission Complete`	Success or completion states
blue	`MB{blue}:Ocean Multiball`	Cool or calm modes
purple	`WM{purple}:Mystery Mode`	Special or rare modes
pink	`EB{pink}:Extra Ball`	Bonus or reward modes

Display Text¶

Keep text concise as multiple modes may display simultaneously.

Targets¶

Targets are momentary states sent in a single update:

CC++Python

void handle_target(sb_game_handle_t state, const char* target) {
    // Add the target as a mode
    sb_add_mode(state, target);
    sb_commit(state);

    // Clear the target
    sb_clear_modes(state);
    sb_commit(state);
}

void handle_target(scorbit::GameState& gs, const std::string& target) {
    // Add the target as a mode
    gs.addMode(target);
    gs.commit();

    // Clear the target
    gs.clearModes();
    gs.commit();
}

def handle_target(gs, target):
    # Add the target as a mode
    gs.add_mode(target)
    gs.commit()

    # Clear the target
    gs.clear_modes()
    gs.commit()

Completion Tracking¶

Use the CP: prefix to track completed objectives:

CC++Python

void handle_completion(sb_game_handle_t state, const char* mode) {
    // Add the completion mode
    sb_add_mode(state, mode);  // e.g., "CP:Spirit Cards"
    sb_commit(state);
}

void handle_completion(scorbit::GameState& gs, const std::string& mode) {
    // Add the completion mode
    gs.addMode(mode);  // e.g., "CP:Spirit Cards"
    gs.commit();
}

def handle_completion(gs, mode):
    # Add the completion mode
    gs.add_mode(mode)  # e.g., "CP:Spirit Cards"
    gs.commit()

Modes, Completions and Events for Achievements¶

Achievements are matched against the exact mode names your game reports. Keep names stable where you can: a renamed mode stops matching every published achievement that refers to the old name. Two further calls exist mainly for achievements:

set_mode_completed reports that the player beat a mode, as opposed to merely being in it.
add_event adds to a named counter, such as spinner spins or ramp shots.

See Feeding Achievements for how to report modes, completions and events so that achievements can use them.

Mode Duration

Modes that persist across multiple updates are considered active modes. Single-update modes are treated as targets.

Mode Names

Always use the correct category prefix for proper tracking and visualization.

Mode Stacking

Multiple modes can be active simultaneously. They will be displayed in the order they were activated.