pooltool.ruleset

Ruleset logic

Classes

class AIPlayer(*args, **kwargs)

Base Classes:

Protocol

Methods:

decide(system: System, game: Ruleset, callback: Callable[[pooltool.ai.action.Action], None] | None = None) → pooltool.ai.action.Action

Return type:

pooltool.ai.action.Action

apply(system: System, action: pooltool.ai.action.Action) → None

class BallInHandOptions

Base Classes:

pooltool.utils.strenum.StrEnum

class Player(name: str, ai: AIPlayer | None = None)

A player

Attributes:

name : str

Player’s name.

ai : AIPlayer | None

Not implemented yet...

property is_ai: bool

Return type:

bool

class Ruleset(players: list[Player] | None = None)

Abstract base class for a pool game ruleset.

This class defines the skeleton of a pool game ruleset, including player management, score tracking, and shot handling. Subclasses must implement the abstract methods to specify the behavior for specific games. For examples, see currently implemented games.

property active_player: Player

Return type:

Player

property last_player: Player

Returns the last player who played before the active player

If no turns have occurred, meaning the active player is the first player to shoot in the game, this erroneously returns the last player in the player order.

Return type:

Player

Base Classes:

abc.ABC

Methods:

set_next_player() → None

Sets the index for the next player

It is through this index that self.last_player and self.active_player are defined from.

player_order() → Generator[Player, None, None]

Generates player order from current player until last-to-play

Return type:

Generator[Player, None, None]

process_shot(shot: System) → None

Processes the information of the shot just played

Parameters:

shot : System

The shot data from the system.

advance(shot: System) → None

Advances the game state after a shot has been made and processed

Parameters:

shot : System

The shot data from the system.

process_and_advance(shot: System) → None

abstract build_shot_info(shot: System) → ShotInfo

Construct the ShotInfo object for the current shot

This method evaluates the legality of a shot, determines if the turn or game is over, and if applicable, decides the winner.

Parameters:

shot : System

The current shot being played.

Returns:

Contains details about the legality of the shot, whether the turn and game are over, and who the winner is, if there is one.

Return type:

ShotInfo

abstract next_shot_constraints(shot: System) → ShotConstraints

Determine the constraints for the next shot based on the current game state.

The method sets the conditions under which the next shot will be played, such as whether ball-in-hand rules apply and which balls are legally hittable.

Parameters:

shot : System

The current shot being played.

Returns:

Shot constraints for the next shot.

Return type:

ShotConstraints

abstract initial_shot_constraints() → ShotConstraints

Define the initial constraints for the first shot of the game.

Returns:

Predefined shot constraints for the initial shot.

Return type:

ShotConstraints

abstract respot_balls(shot: System) → None

Respot balls

This method should decide which balls should be respotted, and respot them. This method should probably make use of pooltool.ruleset.utils.respot

abstract copy() → Ruleset

Copy the game state

If you don’t know how to implement this method, you can create a placeholder function:

::

def copy(self):

return self

Return type:

Ruleset

class ShotConstraints(ball_in_hand: BallInHandOptions, movable: list[str] | None, cueable: list[str] | None, hittable: tuple[str, ...], call_shot: bool, ball_call: str | None = None, pocket_call: str | None = None)

Constraints for a player’s upcoming shot

Attributes:

ball_in_hand : BallInHandOptions

Enum specifying if and how the player can place the cue ball by hand.

movable : list[str] | None

A list of identifiers for balls that the player is allowed to move before the shot. If None, all balls are considered movable.

cueable : list[str] | None

A list of identifiers for balls that can be struck by the cue ball during the shot. If None, all balls are considered cueable.

hittable : tuple[str, ...]

A tuple of identifiers for balls that must be hit for the shot to be considered legal.

call_shot : bool

A boolean indicating whether the shot must be called (i.e., the player must declare which ball they intend to pocket and in which pocket). If False, ball_call and pocket_call need not be defined.

ball_call : str | None

The identifier of the ball the player has called to be pocketed. If None, no specific ball has been called.

pocket_call : str | None

The identifier of the pocket the player has called for the ball to be pocketed in. If None, no specific pocket has been called.

Methods:

cueball(balls: dict[str, Any]) → str

Return type:

str

can_shoot() → bool

Return type:

bool

class ShotInfo(player: Player, legal: bool, reason: str, turn_over: bool, game_over: bool, winner: Player | None, score: Counter[str])

Info about a played shot

Attributes:

player : Player

The player who played the shot.

legal : bool

Whether or not the shot was legal.

reason : str

A textual description providing the rationale for whether the shot was legal.

turn_over : bool

Whether the player’s turn is over.

game_over : bool

Whether or not the game is over as a result of the shot.

winner : Player | None

Who the winner is. None if game_over is False.

score : Counter[str]

The total game score (tallied after the shot). Keys are player names and values are points.

Functions

balls_that_hit_cushion(shot: System, exclude: set[str] | None = None) → set[str]

Return type:

set[str]

get_ball_ids_on_table(shot: System, at_start: bool, exclude: set[str] | None = None) → set[str]

Return type:

set[str]

get_highest_ball(shot: System, at_start: bool) → Ball

Get the highest ball on the table at start or end of shot

Parameters:

at_start : bool

If True, the highest ball on the table at t=0 is calculated. If False, the highest ball at the end of the shot (t=inf) is calculated. The latter returns a different result if the highest ball on the table was pocketed

Return type:

Ball

get_id_of_first_ball_hit(shot: System, cue: str = 'cue') → str | None

Return type:

str | None

get_lowest_ball(shot: System, when: StateProbe) → Ball

Get the lowest ball on the table at start or end of shot

Parameters:

at_start

If True, the lowest ball on the table at t=0 is calculated. If False, the lowest ball at the end of the shot (t=inf) is calculated. The latter returns a different result if the lowest ball on the table was pocketed

Return type:

Ball

get_pocketed_ball_ids(shot: System) → list[str]

Get list of ball IDs that are in the pocketed state (by end of shot)

See also get_pocketed_ball_ids_during_shot

Return type:

list[str]

get_pocketed_ball_ids_during_shot(shot: System, exclude: set[str] | None = None) → list[str]

Get list of ball IDs pocketed during the shot

See also get_pocketed_ball_ids

Return type:

list[str]

is_ball_hit(shot: System) → bool

Return type:

bool

is_ball_pocketed(shot: System, ball_id: str) → bool

Return type:

bool

is_ball_pocketed_in_pocket(shot: System, ball_id: str, pocket_id: str) → bool

Return type:

bool

is_lowest_hit_first(shot: System) → bool

Return type:

bool

is_numbered_ball_pocketed(shot: System) → bool

Return type:

bool

is_shot_called_if_required(shot_constraints: ShotConstraints) → bool

Return type:

bool

is_target_group_hit_first(shot: System, target_balls: tuple[str, ...], cue: str) → bool

Return type:

bool

respot(shot: System, ball_id: str, x: float, y: float, z: float | None = None) → None

Respot a ball

Parameters:

z : float | None

If not provided, z is set to the ball’s radius

Notes

• FIXME check if respot position overlaps with ball

get_ruleset(game: GameType, enforce_rules: bool = True) → type[Ruleset]

Retrieve a ruleset class

Parameters:

• game : GameType

  The game type.

• enforce_rules : bool

  Whether to enforce game rules. If False, returns ruleless mode.

Returns:

An uninitialized class object representing a game.

Return type:

Type[Ruleset]