Updating Scores¶

Proper score tracking is essential for accurate game state management. This includes initializing scores, updating them during gameplay, and optionally tracking score sources.

Add Player¶

When new player added to the game, set the score to zero. After commit() the player(s) will be added to the game and will be shown in the mobile app and scoreboard.

void add_player(sb_game_handle_t state, sb_player_t player) {
    sb_set_score(gs, player, 0, 0);
    sb_commit(gs);
}

void addPlayer(scorbit::GameState& gs, int player) {
    gs.setScore(player, 0);
    gs.commit();
}

def add_player(gs, player):
    gs.set_score(player, 0)
    gs.commit()

Score Updates¶

You can update scores for a single or multiple players simultaneously during gameplay.

When new score generated, call set_score function. The score will be added to the current score of the player.

// Update scores for all active players
sb_set_score(gs, 1, p1_score, 0);
sb_set_score(gs, 2, p2_score, 0);

...

// Always call commit at the end of cycle
sb_commit(gs);

// Update scores for all active players
gs.setScore(1, p1_score);
gs.setScore(2, p2_score);

... 

// Always call commit at the end of cycle
gs.commit();

# Update scores for all active players
gs.set_score(1, p1_score)
gs.set_score(2, p2_score)

...

# Always call commit at the end of cycle
gs.commit()

Score Features¶

Each game provider can define specific score features for a specific game to track the source of score updates. This allows for better analytics and understanding of gameplay dynamics.

Setting Score Features Table¶

In the game setup, you may define the score features that your game will use. This is done by providing a list of feature identifiers and their descriptions.

The features table is a table of strings that describe the score features available in the game. Its index is used in set_score function to specify the feature type.

Versioning is important to ensure compatibility with the Scorbit platform. The features table should be defined in the game setup and can be updated as needed.

If in the future you wish to add new features, place them at the end of the list and increment the version number. This way, existing features will not change their index.

It is recommended to define the first feature as "none", so that it is assigned index 0. This allows you to use 0 as the default feature type when no specific feature is applicable or when the game does not utilize any features.

// Define score features for the game
const char * G_SCORE_FEATURES[] = {
    "none",
    "Ramp shots",
    "Spinner hits",
    "Target hits",
    "Switch hits",
    "Jackpot awards",
    "Super jackpot awards",
    "Mode completion bonuses",
    "Multiplier-based points",
    "Skill shot awards",
    "Combo shot awards",
    "Mode start awards",
    "Wizard mode points"
};
const size_t G_SCORE_FEATURES_COUNT = sizeof(G_SCORE_FEATURES) / sizeof(G_SCORE_FEATURES[0]);
const int G_SCORE_FEATURES_VERSION = 1; // Should be incremented if new features are added in the future

...

// Set the score features in the game setup (device info) which will be used to initialize game state
sb_device_info_t device_info = {
    ...
    .score_features = G_SCORE_FEATURES,
    .score_features_count = G_SCORE_FEATURES_COUNT,
    .score_features_version = G_SCORE_FEATURES_VERSION,
};
sb_game_handle_t gs = sb_create_game_state2(encrypted_key, &device_info);

// Define score features for the game
std::vector<std::string> G_SCORE_FEATURES = {
    "none",
    "Ramp shots",
    "Spinner hits",
    "Target hits",
    "Switch hits",
    "Jackpot awards",
    "Super jackpot awards",
    "Mode completion bonuses",
    "Multiplier-based points",
    "Skill shot awards",
    "Combo shot awards",
    "Mode start awards",
    "Wizard mode points"
};
const int G_SCORE_FEATURES_VERSION = 1; // Will be incremented if new features are added in the future

...

// Set the score features in the game setup (device info) which will be used to initialize game state
scorbit::DeviceInfo device_info;
...
device_info.scoreFeatures = G_SCORE_FEATURES;
device_info.scoreFeaturesVersion = G_SCORE_FEATURES_VERSION;
auto gs = scorbit::createGameState(encrypted_key, device_info);

# Define score features for the game
G_SCORE_FEATURES = [
    "none",
    "Ramp shots",
    "Spinner hits",
    "Target hits",
    "Switch hits",
    "Jackpot awards",
    "Super jackpot awards",
    "Mode completion bonuses",
    "Multiplier-based points",
    "Skill shot awards",
    "Combo shot awards",
    "Mode start awards",
    "Wizard mode points"
]
G_SCORE_FEATURES_VERSION = 1  # Will be incremented if new features are added in the future

...

# Set the score features in the game setup (device info) which will be used to initialize game state
info = scorbit.DeviceInfo()
...
info.score_features = G_SCORE_FEATURES
info.score_features_version = G_SCORE_FEATURES_VERSION
gs = scorbit.create_game_state(encrypted_key, info)

Example Usage¶

When the score increases, use the set_score() function to update the score and associate it with a feature by specifying the corresponding index from the features table. This enables tracking the source of each score update.

// Example using feature types
sb_set_score(state, player, 1000000, 5);  // Jackpot awards
sb_set_score(state, player, 500, 0);      // Regular points, no feature

// Example using feature types
gs.setScore(player, 1000000, 5);  // Jackpot awards
gs.setScore(player, 500, 0);      // Regular points

# Example using feature types
gs.set_score(player, 1000000, 5)  # Jackpot awards
gs.set_score(player, 500, 0)      # Regular points

Difference between Features and Modes¶

While both features and modes can affect scores, they serve different purposes:

• Features: Track specific score sources, like ramps or jackpots. They are used to provide context for individual score increases.
• Modes: Represent larger gameplay states, like multiballs or wizard modes. They can affect overall gameplay but are not tied to individual score increases and they have lifetime that can be started and ended.

Ball Updates¶

You can update the current ball number during gameplay:

void update_ball(sb_game_handle_t state, int ball) {
    // Update current ball number
    sb_set_current_ball(state, ball);

    // Commit the update
    sb_commit(state);
}

void updateBall(scorbit::GameState& gs, int ball) {
    // Update current ball number
    gs.setCurrentBall(ball);

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

def update_ball(gs, ball):
    # Update current ball number
    gs.set_current_ball(ball)

    # Commit the update
    gs.commit()

Combined Score and Ball Updates¶

Often you'll want to update both scores and the current ball in the same cycle:

void update_game_state(sb_game_handle_t state, int ball, sb_player_t player, sb_score_t score) {
    // Update current ball
    sb_set_current_ball(state, ball);

    // Update player score
    sb_set_score(state, player, score, 0);

    // Single commit for all updates
    sb_commit(state);
}

void updateGameState(scorbit::GameState& gs, int ball, int player, sb_score_t score) {
    // Update current ball
    gs.setCurrentBall(ball);

    // Update player score
    gs.setScore(player, score);

    // Single commit for all updates
    gs.commit();
}

def update_game_state(gs, ball, player, score):
    # Update current ball
    gs.set_current_ball(ball)

    # Update player score
    gs.set_score(player, score)

    # Single commit for all updates
    gs.commit()

Best Practices¶

1. Score Initialization¶

• Always start with zero scores as soon as player added
• Commit initial scores immediately

2. Score Updates¶

• Update scores promptly
• Use appropriate feature tags