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.
Zero Score Importance
Always initialize players with zero scores, even if they haven't played yet. This establishes the player count and order for the session.
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.
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.
Default Feature
In C++ and Python it's possible to call set_score()
with only two arguments (player and score). In this case feature is assigned to the default value 0.
Feature Selection
Choose the most specific feature type that applies to help with score analysis.
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.
Feature Usage
Using score features consistently can enable better gameplay analysis and player statistics.
Ball Updates¶
You can update the current ball number during gameplay:
Ball Numbers
- Ball numbers typically start at 1
- Update the ball number before scoring begins for that ball
- Extra balls should still increment the ball number
Combined Score and Ball Updates¶
Often you'll want to update both scores and the current ball in the same cycle:
Commit Frequency
Group related updates (like ball and score changes) into a single commit when possible.
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