pooltool.ruleset

Ruleset logic

Overview

Classes

AIPlayer	Base class for protocol classes.
BallInHandOptions	Enum where members are also (and must be) strings
Player	A player
Ruleset	Abstract base class for a pool game ruleset.
ShotConstraints	Constraints for a player’s upcoming shot
ShotInfo	Info about a played shot

Function

get_ruleset(game)

Retrieve a ruleset class

Classes

class pooltool.ruleset.AIPlayer(*args, **kwargs)

Bases: Protocol

class pooltool.ruleset.BallInHandOptions(value)

An enumeration.

Bases: pooltool.utils.strenum.StrEnum

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

A player

name

Player’s name.

Type:

str

ai

Not implemented yet…

Type:

pooltool.ruleset.datatypes.AIPlayer | None

class pooltool.ruleset.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.

Bases: abc.ABC

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

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: pooltool.system.datatypes.System) → None

Processes the information of the shot just played

Parameters:

shot (pooltool.system.datatypes.System) -- The shot data from the system.

advance(shot: pooltool.system.datatypes.System) → None

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

Parameters:

shot (pooltool.system.datatypes.System) -- The shot data from the system.

abstract build_shot_info(shot: pooltool.system.datatypes.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 (pooltool.system.datatypes.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: pooltool.system.datatypes.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 (pooltool.system.datatypes.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: pooltool.system.datatypes.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 pooltool.ruleset.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

ball_in_hand

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

Type:

pooltool.ruleset.datatypes.BallInHandOptions

movable

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

Type:

List[str] | None

cueable

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

Type:

List[str] | None

hittable

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

Type:

Tuple[str, …]

call_shot

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.

Type:

bool

ball_call

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

Type:

str | None

pocket_call

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

Type:

str | None

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

Info about a played shot

player

The player who played the shot.

Type:

pooltool.ruleset.datatypes.Player

legal

Whether or not the shot was legal.

Type:

bool

reason

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

Type:

str

turn_over

Whether the player’s turn is over.

Type:

bool

game_over

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

Type:

bool

winner

Who the winner is. None if game_over is False.

Type:

pooltool.ruleset.datatypes.Player | None

score

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

Type:

Counter[str]

Functions

pooltool.ruleset.get_ruleset(game: pooltool.game.datatypes.GameType) → Type[datatypes.Ruleset]

Retrieve a ruleset class

Parameters:

game (pooltool.game.datatypes.GameType) -- The game type.

Returns:

An uninitialized class object representing a game.

Return type:

Type[Ruleset]