Events¶

The Scorbit SDK includes an event system that enables bidirectional communication between the Scorbit platform and your game. Events are delivered from the server to your device, allowing the mobile app and backend to request actions such as starting a game or adding credits.

Event Types¶

The SDK supports the following event types:

Event Type	Description
`GameStartRequested`	A player has requested to start a game from the Scorbit mobile app
`CreditsAddRequested`	A request to add credits to the machine (e.g., via mobile payment)
`CreditsStatusRequested`	The backend is requesting the current credit status of the machine
`ConfigReceived`	Configuration data has been received from the backend

Registering an Event Callback¶

Event callbacks are registered on the Config object before creating the game state. The callback is invoked whenever the SDK receives an event from the server.

CC++Python

void events_callback(const sb_event_t *event, void *user_data)
{
    sb_event_type_t event_type = sb_event_type(event);

    switch (event_type) {
    case SB_EVT_GAME_START_REQUESTED:
        // Handle game start request
        break;
    case SB_EVT_CREDITS_ADD_REQUESTED:
        // Handle credits add request
        break;
    case SB_EVT_CREDITS_STATUS_REQUESTED:
        // Handle credits status request
        break;
    case SB_EVT_CONFIG_RECEIVED:
        // Handle config received
        break;
    default:
        break;
    }
}

// Register on config before creating game state
sb_config_set_event_callback(config, events_callback, NULL);

void eventsCallback(const scorbit::Event &event)
{
    switch (event.type()) {
    case scorbit::EventType::GameStartRequested:
        // Handle game start request
        break;
    case scorbit::EventType::CreditsAddRequested:
        // Handle credits add request
        break;
    case scorbit::EventType::CreditsStatusRequested:
        // Handle credits status request
        break;
    case scorbit::EventType::ConfigReceived:
        // Handle config received
        break;
    default:
        break;
    }
}

// Register on config before creating game state
config.setEventCallback(eventsCallback);

def events_callback(gs, event):
    if event.type() == scorbit.EventType.GameStartRequested:
        # Handle game start request
        pass
    elif event.type() == scorbit.EventType.CreditsAddRequested:
        # Handle credits add request
        pass
    elif event.type() == scorbit.EventType.CreditsStatusRequested:
        # Handle credits status request
        pass
    elif event.type() == scorbit.EventType.ConfigReceived:
        # Handle config received
        pass

# Register after creating game state
gs.set_event_callback(lambda event: events_callback(gs, event))

Registration Timing

In C and C++, the event callback must be set on the Config object before creating the game state. In Python, it is set on the game state object after creation.

Handling Events¶

GameStartRequested¶

This event is received when a player requests to start a game from the Scorbit mobile app. The event includes the number of players requested.

When handling this event, your game should initiate a new game and call setGameStarted with FromLobby as the origin to indicate the game was started remotely.

CC++Python

case SB_EVT_GAME_START_REQUESTED: {
    int players_count = 0;
    if (sb_event_game_start_requested(event, &players_count)) {
        printf("Game start requested with %d player(s)\n", players_count);
        // Start the game on the machine with the requested number of players
        // Then call:
        sb_set_game_started(gs, SB_GAME_STARTED_FROM_LOBBY);
        for (int i = 1; i <= players_count; i++) {
            sb_set_score(gs, i, 0, 0);
        }
    }
} break;

case scorbit::EventType::GameStartRequested: {
    int playersCount = 0;
    if (event.getGameStartRequested(playersCount)) {
        std::cout << "Game start requested with " << playersCount << " player(s)" << std::endl;
        // Start the game on the machine with the requested number of players
        // Then call:
        gs.setGameStarted(scorbit::GameStartOrigin::FromLobby);
        for (int i = 1; i <= playersCount; i++) {
            gs.setScore(i, 0);
        }
    }
} break;

if event.type() == scorbit.EventType.GameStartRequested:
    success, players_count = event.get_game_start_requested()
    if success:
        print(f"Game start requested with {players_count} player(s)")
        # Start the game on the machine with the requested number of players
        # Then call:
        gs.set_game_started(scorbit.GameStartOrigin.FromLobby)
        for i in range(1, players_count + 1):
            gs.set_score(i, 0)

GameStartOrigin

Use FromLobby when the game is started in response to a GameStartRequested event. Use StartButton when the game is started by a physical button press on the machine. See Opening a Game Session for more details.

CreditsAddRequested¶

This event is received when the backend requests that credits be added to the machine, typically from a mobile payment. After adding the credits, confirm the transaction by calling setCreditsDropped.

CC++Python

case SB_EVT_CREDITS_ADD_REQUESTED: {
    int credits_to_add;
    const char *transaction;
    if (sb_event_credits_add_requested(event, &credits_to_add, &transaction)) {
        printf("Credits add requested: %d\n", credits_to_add);
        // Add credits to the machine, then confirm:
        sb_set_credits_dropped(gs, credits_to_add, transaction, true);
    }
} break;

case scorbit::EventType::CreditsAddRequested: {
    int creditsToAdd = 0;
    std::string transaction;
    if (event.getCreditsAddRequested(creditsToAdd, transaction)) {
        std::cout << "Credits add requested: " << creditsToAdd << std::endl;
        // Add credits to the machine, then confirm:
        gs.setCreditsDropped(creditsToAdd, transaction, true);
    }
} break;

elif event.type() == scorbit.EventType.CreditsAddRequested:
    success, credits_to_add, transaction = event.get_credits_add_requested()
    if success:
        print(f"Credits add requested: {credits_to_add}")
        # Add credits to the machine, then confirm:
        gs.set_credits_dropped(credits_to_add, transaction, True)

Transaction ID

The transaction string is provided by the backend and must be passed back in the setCreditsDropped call to confirm the transaction. Copy or use this value immediately — it is only valid for the duration of the callback.

CreditsStatusRequested¶

This event is received when the backend requests the current credit status of the machine. Respond by calling setCreditsStatus with the current state.

CC++Python

case SB_EVT_CREDITS_STATUS_REQUESTED: {
    // Report current credits status
    sb_set_credits_status(gs, free_play, current_credits, max_credits, pricing);
} break;

case scorbit::EventType::CreditsStatusRequested: {
    // Report current credits status
    gs.setCreditsStatus(freePlay, currentCredits, maxCredits, pricing);
} break;

elif event.type() == scorbit.EventType.CreditsStatusRequested:
    # Report current credits status
    gs.set_credits_status(free_play, current_credits, max_credits, pricing)

ConfigReceived¶

This event is received when configuration data is sent from the backend. This can include settings such as whether payments are enabled.

CC++Python

case SB_EVT_CONFIG_RECEIVED: {
    const char *config_json = NULL;
    if (sb_event_config_received(event, &config_json)) {
        printf("Config received: %s\n", config_json);
        // Process the config JSON string
    }

    bool payments_enabled = false;
    if (sb_event_config_payments_enabled(event, &payments_enabled)) {
        printf("Payments enabled: %s\n", payments_enabled ? "true" : "false");
    }
} break;

case scorbit::EventType::ConfigReceived: {
    std::string configJson;
    if (event.eventConfigReceived(configJson)) {
        std::cout << "Config received: " << configJson << std::endl;
        // Process config JSON
    }

    bool paymentsEnabled = false;
    if (event.getConfigPaymentsEnabled(paymentsEnabled)) {
        std::cout << "Payments enabled: " << (paymentsEnabled ? "true" : "false") << std::endl;
    }
} break;

elif event.type() == scorbit.EventType.ConfigReceived:
    success, config_json = event.event_config_received()
    if success:
        print(f"Config received: {config_json}")
        # Process config JSON

    success, payments_enabled = event.get_config_payments_enabled()
    if success:
        print(f"Payments enabled: {payments_enabled}")

Event Type Reference¶

C Enum¶

typedef enum {
    SB_EVT_GAME_START_REQUESTED,     // Game start requested from mobile app
    SB_EVT_CREDITS_ADD_REQUESTED,    // Credits add requested from mobile app
    SB_EVT_CREDITS_STATUS_REQUESTED, // Credits status requested
    SB_EVT_CONFIG_RECEIVED,          // Configuration received from backend
} sb_event_type_t;

C++ Enum¶

enum class EventType {
    GameStartRequested,
    CreditsAddRequested,
    CreditsStatusRequested,
    ConfigReceived,
};

C Helper Functions¶

Function	Description
`sb_event_type(event)`	Returns the event type
`sb_event_game_start_requested(event, &players)`	Extracts player count from a game start request
`sb_event_credits_add_requested(event, &credits, &transaction)`	Extracts credits and transaction ID
`sb_event_config_received(event, &config_json)`	Extracts the config JSON string
`sb_event_config_payments_enabled(event, &enabled)`	Extracts whether payments are enabled

For complete examples, refer to the Scorbit SDK examples which demonstrate a full game loop implementation including event handling in C, C++, and Python.