Ending a Player Turn (End of Ball)

When a player's ball drains or their turn ends, you'll need to update the game state to reflect the player change and ball progression. This is a critical part of maintaining accurate game flow.

Basic Usage

CC++Python

void end_player_turn(sb_game_handle_t state, sb_player_t current_player, sb_player_t next_player) {
    // Clear any active modes from previous player
    sb_clear_modes(state);

    // Update to next player
    sb_set_active_player(state, next_player);

    // Update ball number if we've cycled through all players
    if (next_player <= current_player) {
        sb_ball_t next_ball = current_ball + 1;
        sb_set_current_ball(state, next_ball);
    }

    // Commit the changes
    sb_commit(state);
}

void end_player_turn(scorbit::GameState& gs, int current_player, int next_player) {
    // Clear any active modes from previous player
    gs.clearModes();

    // Update to next player
    gs.setActivePlayer(next_player);

    // Update ball number if we've cycled through all players
    if (next_player <= current_player) {
        int next_ball = current_ball + 1;
        gs.setCurrentBall(next_ball);
    }

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

def end_player_turn(gs, current_player, next_player):
    # Clear any active modes from previous player
    gs.clear_modes()

    # Update to next player
    gs.set_active_player(next_player)

    # Update ball number if we've cycled through all players
    if next_player <= current_player:
        next_ball = current_ball + 1
        gs.set_current_ball(next_ball)

    # Commit the changes
    gs.commit()

Key Concepts

1. State Cleanup

• Clear active modes from the previous player
• Ensure final score is recorded for the ending turn
• Prepare state for next player's turn

2. Player Progression

• Update the active player to the next in sequence
• Handle wrap-around for multiple player games
• Maintain correct player order

3. Ball Management

• Increment ball number when all players complete their turns
• Track ball progression through the game
• Handle special cases (extra balls, replays)

Example with Extra Ball

Here's a more detailed example showing how to handle extra balls and special cases:

CC++Python

void handle_ball_end(sb_game_handle_t state, bool extra_ball_awarded) {
    sb_player_t current_player = get_current_player();
    sb_player_t next_player;
    sb_ball_t current_ball = get_current_ball();

    if (extra_ball_awarded) {
        // Same player continues, same ball number
        next_player = current_player;
    } else {
        // Move to next player
        next_player = get_next_player();

        // If we're cycling back to player 1, increment ball
        if (next_player <= current_player) {
            sb_set_current_ball(state, current_ball + 1);
        }
    }

    // Clear modes regardless of extra ball
    sb_clear_modes(state);

    // Set next active player
    sb_set_active_player(state, next_player);

    // Commit changes
    sb_commit(state);
}

void handle_ball_end(scorbit::GameState& gs, bool extra_ball_awarded) {
    int current_player = get_current_player();
    int next_player;
    int current_ball = get_current_ball();

    if (extra_ball_awarded) {
        // Same player continues, same ball number
        next_player = current_player;
    } else {
        // Move to next player
        next_player = get_next_player();

        // If we're cycling back to player 1, increment ball
        if (next_player <= current_player) {
            gs.setCurrentBall(current_ball + 1);
        }
    }

    // Clear modes regardless of extra ball
    gs.clearModes();

    // Set next active player
    gs.setActivePlayer(next_player);

    // Commit changes
    gs.commit();
}

def handle_ball_end(gs, extra_ball_awarded):
    current_player = get_current_player()
    current_ball = get_current_ball()

    if extra_ball_awarded:
        # Same player continues, same ball number
        next_player = current_player
    else:
        # Move to next player
        next_player = get_next_player()

        # If we're cycling back to player 1, increment ball
        if next_player <= current_player:
            gs.set_current_ball(current_ball + 1)

    # Clear modes regardless of extra ball
    gs.clear_modes()

    # Set next active player
    gs.set_active_player(next_player)

    # Commit changes
    gs.commit()

Note

Always clear modes when a player's turn ends, even if they've earned an extra ball. This ensures clean state tracking for each ball played.

Warning

Make sure to commit changes after updating player and ball information. The game state won't be updated until committed.

Tip

Consider implementing a queue or tracking system for extra balls to handle multiple extra balls earned during the same turn.

Common Scenarios

1. Normal Ball End

• Clear modes
• Move to next player
• Increment ball if all players have played

2. Extra Ball Awarded

• Clear modes
• Keep same player active
• Maintain current ball number

3. Last Ball of Game

• Clear modes
• Update final scores
• Prepare for game end