Player Information¶
During a game session the Scorbit SDK provides access to player information, including the player's name, avatar (profile photo), and other relevant details. This information can be used to personalize the gaming experience and enhance player engagement.
Checking if player information has any changes¶
Due to the asynchronous nature of the Scorbit SDK, player information may change in the background during a game session. To detect these changes, call the is_players_info_updated function on every cycle while a game session is active.
This function checks whether any player information has been updated since the last call. If an update is detected, it copies the latest data to accessible memory that can be safely retrieved by the client application, and returns a boolean value indicating whether an update occurred.
Using player information functions
The following functions should only be called after is_players_info_updated returns true.
Checking if specific player has information¶
If a player claims a slot during the game session, their information becomes available for retrieval; otherwise, it remains empty. To check whether information is available for a specific player, use the has_player_info function.
Retrieving player information¶
Player information includes the following attributes:
id:int— The player's unique identifier in Scorbit's system. Typically, game clients do not need to use this.name:string— The player's display name (e.g.,John Doe).initials:string— The player's initials (e.g.,JMD).preferred_name:string— The player's preferred name, which is either the display name or initials, depending on the player's settings.picture_url:string— The URL of the player's avatar (profile photo). It can be used to display the avatar in the game client. NOTE: Game clients do not need to use this directly, as the SDK provides a function to retrieve the avatar image.picture:bytes— The player's avatar image in JPG format, suitable for display in the game client. However, to enable automatic downloading of avatar images, the game client must setauto_download_player_picstotruein the game state setup options.
In C, each attribute has its own function for retrieval. In C++ and Python, player information is represented as a struct with the same attributes.
Retrieving information in C
All functions that return a string as a const char * pointer guarantee that the pointer remains valid only until the next call to is_players_info_updated. If you need to retain the string longer, copy it to a local buffer.
The following code snippets demonstrate how to retrieve player information:
/*
The following functions are used to retrieve player information in C:
int64_t sb_get_player_id(sb_game_handle_t handle, sb_player_t player);
const char *sb_get_player_preferred_name(sb_game_handle_t handle, sb_player_t player);
const char *sb_get_player_name(sb_game_handle_t handle, sb_player_t player);
const char *sb_get_player_initials(sb_game_handle_t handle, sb_player_t player);
const char *sb_get_player_picture_url(sb_game_handle_t handle, sb_player_t player);
const uint8_t *sb_get_player_picture(sb_game_handle_t handle, sb_player_t player, size_t *size);
*/
// Check if players info was updated
if (sb_is_players_info_updated(gs)) {
// Get player info for each player
for (int j = 1; j <= players_num; ++j) {
// First check if player's info is available
if (sb_has_player_info(gs, j)) {
// Get player's name
const char *name = sb_get_player_preferred_name(gs, j);
// we use it as preferred name, also there are functions
// for initials and name. Preferred name is either initials or name chosen
// by the player.
snprintf(player_names[j], sizeof(player_names[j]), "%s", name);
// Get player's picture if available
size_t pic_size;
const uint8_t *picture_data = sb_get_player_picture(gs, j, &pic_size);
// Here using pic_size and picture pointer, copy it to the allocated memory.
// This is jpg image, can be displayed on the screen or saved to file.
(void)picture_data;
} else {
// Name is not available, let's clear the name
player_names[j][0] = 0;
// And clear allocated picture ...
}
}
}
/*
The following functions is used to retrieve player information in C++:
PlayerInfo getPlayerInfo(sb_player_t player);
struct PlayerInfo {
int64_t id; /// The player's ID
std::string preferredName; /// Either name or initials
std::string name; /// The player's name to display
std::string initials; /// The player's initials, e.g. "DTM"
std::string pictureUrl; /// The URL of the profile picture
std::vector<uint8_t> picture; /// The profile picture binary (jpg), can be empty
};
*/
std::map<sb_player_t, scorbit::PlayerInfo> players;
...
// Check if players info was updated and if yes, they will be prepared for retrieval
if (gs.isPlayersInfoUpdated()) {
// Get players infos
for (int j = 1; j <= playersNum; ++j) {
if (gs.hasPlayerInfo(j)) {
players[j] = gs.getPlayerInfo(j);
} else {
players.erase(j);
}
}
}
"""
The following function is used to retrieve player information in Python:
PlayerInfo get_player_info(player: int) -> PlayerInfo
class PlayerInfo:
Read-only attributes:
id (int): Unique player identifier.
preferred_name (str): Player's preferred display name.
name (str): Player's full name.
initials (str): Player's initials.
picture_url (str): URL of the player's profile picture.
picture (bytes): Raw JPEG image bytes of the player's picture.
"""
players = {}
...
# Check if players info was updated and if yes, they will be prepared for retrieval
if gs.is_players_info_updated():
for j in range(1, players_num + 1):
if gs.has_player_info(j):
players[j] = gs.get_player_info(j)
else:
players.pop(j, None) # Erase player info if it was removed or not found
Example Usage¶
For complete examples, refer to the Scorbit SDK examples which demonstrate a full game loop implementation in C, C++, and Python.