``pooltool.ruleset`` ==================== .. py:module:: pooltool.ruleset Ruleset logic Classes ------- .. autoclass:: AIPlayer Bases: :py:obj:`Protocol` .. rubric:: Methods: .. py:method:: decide(system: pooltool.system.datatypes.System, game: Ruleset, callback: collections.abc.Callable[[pooltool.ai.action.Action], None] | None = None) -> pooltool.ai.action.Action .. py:method:: apply(system: pooltool.system.datatypes.System, action: pooltool.ai.action.Action) -> None .. autoclass:: BallInHandOptions Bases: :py:obj:`pooltool.utils.strenum.StrEnum` .. autoclass:: Player .. py:property:: is_ai :type: bool .. autoclass:: Ruleset Bases: :py:obj:`abc.ABC` .. py:property:: active_player :type: Player .. py:property:: last_player :type: 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. .. rubric:: Methods: .. py:method:: 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. .. py:method:: player_order() -> collections.abc.Generator[Player, None, None] Generates player order from current player until last-to-play .. py:method:: process_shot(shot: pooltool.system.datatypes.System) -> None Processes the information of the shot just played :param shot: The shot data from the system. .. py:method:: advance(shot: pooltool.system.datatypes.System) -> None Advances the game state after a shot has been made and processed :param shot: The shot data from the system. .. py:method:: process_and_advance(shot: pooltool.system.datatypes.System) -> None .. py:method:: build_shot_info(shot: pooltool.system.datatypes.System) -> ShotInfo :abstractmethod: 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. :param shot: 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. :rtype: ShotInfo .. py:method:: next_shot_constraints(shot: pooltool.system.datatypes.System) -> ShotConstraints :abstractmethod: 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. :param shot: The current shot being played. :returns: Shot constraints for the next shot. :rtype: ShotConstraints .. py:method:: initial_shot_constraints() -> ShotConstraints :abstractmethod: Define the initial constraints for the first shot of the game. :returns: Predefined shot constraints for the initial shot. :rtype: ShotConstraints .. py:method:: respot_balls(shot: pooltool.system.datatypes.System) -> None :abstractmethod: 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`` .. py:method:: copy() -> Ruleset :abstractmethod: 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 .. autoclass:: ShotConstraints .. rubric:: Methods: .. py:method:: cueball(balls: dict[str, Any]) -> str .. py:method:: can_shoot() -> bool .. autoclass:: ShotInfo Functions --------- .. py:function:: balls_that_hit_cushion(shot: pooltool.system.datatypes.System, exclude: set[str] | None = None) -> set[str] .. py:function:: get_ball_ids_on_table(shot: pooltool.system.datatypes.System, at_start: bool, exclude: set[str] | None = None) -> set[str] .. py:function:: get_highest_ball(shot: pooltool.system.datatypes.System, at_start: bool) -> pooltool.objects.ball.datatypes.Ball Get the highest ball on the table at start or end of shot :param at_start: 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 .. py:function:: get_id_of_first_ball_hit(shot: pooltool.system.datatypes.System, cue: str = 'cue') -> str | None .. py:function:: get_lowest_ball(shot: pooltool.system.datatypes.System, when: StateProbe) -> pooltool.objects.ball.datatypes.Ball Get the lowest ball on the table at start or end of shot :param 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 .. py:function:: get_pocketed_ball_ids(shot: pooltool.system.datatypes.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 .. py:function:: get_pocketed_ball_ids_during_shot(shot: pooltool.system.datatypes.System, exclude: set[str] | None = None) -> list[str] Get list of ball IDs pocketed during the shot See also get_pocketed_ball_ids .. py:function:: is_ball_hit(shot: pooltool.system.datatypes.System) -> bool .. py:function:: is_ball_pocketed(shot: pooltool.system.datatypes.System, ball_id: str) -> bool .. py:function:: is_ball_pocketed_in_pocket(shot: pooltool.system.datatypes.System, ball_id: str, pocket_id: str) -> bool .. py:function:: is_lowest_hit_first(shot: pooltool.system.datatypes.System) -> bool .. py:function:: is_numbered_ball_pocketed(shot: pooltool.system.datatypes.System) -> bool .. py:function:: is_shot_called_if_required(shot_constraints: pooltool.ruleset.datatypes.ShotConstraints) -> bool .. py:function:: is_target_group_hit_first(shot: pooltool.system.datatypes.System, target_balls: tuple[str, Ellipsis], cue: str) -> bool .. py:function:: respot(shot: pooltool.system.datatypes.System, ball_id: str, x: float, y: float, z: float | None = None) -> None Respot a ball :param z: If not provided, z is set to the ball's radius .. admonition:: Notes - FIXME check if respot position overlaps with ball .. py:function:: get_ruleset(game: pooltool.game.datatypes.GameType, enforce_rules: bool = True) -> type[datatypes.Ruleset] Retrieve a ruleset class :param game: The game type. :param enforce_rules: Whether to enforce game rules. If False, returns ruleless mode. :returns: An uninitialized class object representing a game. :rtype: Type[Ruleset]