Documentation.md

Alice Chess API Documentation

Player

Represents a player.

Properties

Name	Type	Description
color	Color	The player color.
is_human	bool	Whether this player is human.

Abstract Methods

• make_move(game_state: GameState) -> Move

  Called when this player should make their next move.

  Arguments:

  Name	Type	Description
  game_state	GameState	The current game state.

  Returns Move: The move to make.

• promote(game_state: GameState) -> PromoteType

  Called when this player can promote a pawn.

  Arguments:

  Name	Type	Description
  game_state	GameState	The current game state.

  Returns PromoteType: The piece type to promote to.

Examples

See bots.py for some example simple bots.

Game

Represents a game of Alice Chess.

Wrapper around GameState to easily start a game.

Constructors

• Game(*, white: Type[Player], black: Type[Player])

  Initializes a Game with the given players.

  The players must be subclasses of Player (not instances).

  Arguments:

  Name	Type	Description
  white	Type[Player]	The player for white.
  black	Type[Player]	The player for black.

Methods

• new() -> GameState

  Returns a new game.

  Returns GameState: The first state of the game.

• start_window(non_human_player_delay: int = None, debug: bool = None)

  Starts the game in a window.

  Arguments:

  Name	Type	Description
  non_human_player_delay	int	The number of seconds of delay for non-human players to simulate realism.
  debug	bool	Whether to print debug information.

Examples

from alicechess import Game, HumanPlayer

game = Game(white=HumanPlayer, black=SuperGoodBotPlayer)
game.new().run()

from alicechess import Game, HumanPlayer

game = Game(white=HumanPlayer, black=SuperGoodBotPlayer)
game.start_window()

GameState

A GameState is an immutable state of a game. It includes the board state, the previous move and previous GameState, the captured pieces, the possible moves, the end game state, and more.

Constructors

• GameState.new(*, white: Type[Player], black: Type[Player])

  Initializes the first GameState of a game.

• GameState.from_fen(fen: str, *, white: Type[Player], black: Type[Player])

  Initializes a GameState from a FEN string, using the given players.

Properties

Name	Type	Description
id	int	The game state id.
white	Player	The white player.
black	Player	The black player.
prev	Optional[GameState]	The previous GameState.
move	Optional[PieceMoved]	The move from the previous GameState.
end_game_state	Optional[EndGameState]	The end game state.
current_color	Color	The color of the current player.
current_player	Player	The current player.
half_move_clock	int	The number of half-moves since the last capture or the last pawn moved.
num_moves	int	The number of full moves played in the entire game.

Methods

• fen() -> str

  Returns the FEN representation of the game.

  Since Alice Chess has two boards, the piece placement field is doubled in length, where the first 8 ranks refer to Board A (on the left) and the last 8 ranks refer to Board B (on the right).

• board_to_str(empty: str = " .") -> str

  Returns a string representation of the board.

  Arguments:

  Name	Type	Description
  empty	str	A placeholder to use for empty positions. Must have length 2.

  Raises:

  • ValueError: If empty does not have length 2.

  Returns str: The string representation.

• moves_to_str(columns: int = 4, captured_empty: bool = True) -> str

  Returns a string representation of the moves for each piece.

  If captured_empty is True, there will be empty spaces for piece ids that don't have associated pieces currently on the board (assumed to be captured).

  Arguments:

  Name	Type	Description
  columns	int	The number of columns to split the pieces into. Must be positive.
  captured_empty	bool	Whether to leave empty spaces for captured pieces.

  Raises:

  • ValueError: If columns is not positive.

  Returns str: The string representation.

• debug()

  Prints debug information about this game state.

• is_game_over() -> bool

  Returns whether the game is over (checkmate, stalemate, or draw).

• is_in_checkmate() -> bool

  Returns whether the current player is in checkmate.

• winner() -> Optional[Color]

  Returns the winner of the game (for checkmate).

• is_in_stalemate() -> bool

  Returns whether the current player is in stalemate.

• is_draw() -> bool

  Returns whether the game is a draw.

• is_in_check() -> bool

  Returns whether the current player is in check.

• needs_promotion() -> bool

  Returns whether the state is waiting for a promotion for the last moved pawn.

• promote(promote_type: PromoteType) -> GameState

  Promotes the promoting pawn.

  A pawn is able to be promoted if it was last moved into the last row for its direction of movement.

  Arguments:

  Name	Type	Description
  promote_type	PromoteType	The type to promote to.

  Raises:

  • RuntimeError: If there is no pawn waiting for a promotion.

  Returns GameState: The new game state with the promoted pawn.

• yield_all_pieces() -> Iterator[Piece]

  Yields all the pieces.

• yield_player_pieces() -> Iterator[Piece]

  Yields all the pieces for the current player.

• yield_player_moves() -> Iterator[PieceMove]

  Yields all the possible moves for the current player.

• yield_captured() -> Iterator[Piece]

  Yields the captured pieces.

• get_piece(bn: int, r: int, c: int) -> Optional[Piece]

  Gets the piece at the given position.

  Arguments:

  Name	Type	Description
  bn	int	The board number.
  r	int	The row.
  c	int	The column.

  Raises:

  • ValueError:
    • If bn is not 0 or 1.
    • If r and c are not bounded within [0, 7].

  Returns Optional[Piece]: The piece, or None.

• make_move(move: Move) -> GameState

  Makes the given move.

  If a promotion is needed after this move, the pawn will simply be moved without being promoted. It is up to the caller to call the GameState.promote() method on the returned state.

  Arguments:

  Name	Type	Description
  move	Move	The move to make.

  Raises:

  • RuntimeError:
    • If the game is over.
    • If the state is waiting for a promotion.
  • ValueError: If the given move is invalid.

  Returns GameState: The next game state.

• step() -> GameState

  Advances a step of the game.

  Prompts the current player for a move, and also prompts them for promotion if necessary. Returns the next game state.

  Raises:

  • RuntimeError: If the current player is a human (call make_move() instead).
  • ValueError: If the move given by the player is invalid.

  Returns GameState: The next game state.

• run() -> GameState

  Runs the game until it's over.

  Returns the last game state.

• restart() -> GameState

  Returns the starting state with the same players.

Piece

Represents a piece.

The special piece Pawn is described below.

Properties

Name	Type	Description
id	int	The piece id.
name	str	The piece name.
type	PieceType	The piece type.
color	Color	The piece color.
pos	BoardPosition	The piece position.
num_moves	int	The number of possible moves.
is_captured	bool	Whether this piece is captured.
is_threatened	bool	Whether this piece is being threatened on the current board. False if not known.

Methods

• is_at_start_pos(pos = None) -> bool

  Returns whether the given position could be a start position of the piece.

  Returns bool: Whether the given position could be a start position of the
  piece.

• copy() -> Piece

  Returns a copy of this piece.

  Returns Piece: The copy.

• yield_moves() -> Iterator[PieceMove]

  Yields the possible moves for this piece.

  Yields PieceMove: Each possible move.

• can_make_move(bn: int, tr: int, tc: int) -> bool

  Returns whether this piece can move to the given position.

  Arguments:

  Name	Type	Description
  bn	int	The board number.
  tr	int	The target row.
  tc	int	The target column.

  Raises:

  • ValueError:
    • If bn is not 0 or 1.
    • If tr and tc are not bounded within [0, 7].

  Returns bool: Whether this piece can move to the given position.

• move_to(pos: BoardPosition) -> Piece

  Returns a copy of this piece that is moved to the given position.

  Arguments:

  Name	Type	Description
  pos	BoardPosition	The position to move to.

  Returns Piece: The copy.

• capture() -> Piece

  Returns a copy of this piece that is captured.

  Returns Piece: The copy.

Pawn

Subclass of Piece.

Additional Properties

Name	Type	Description
dr	int	The direction of movement.
can_promote	bool	Whether the pawn can be promoted.

Utilities

Color

Enum for the possible colors for each piece.

Values

• Color.WHITE
• Color.BLACK

Methods

• abbr() -> str

  Returns the first letter of the color.

• title() -> str

  Returns the enum name as a title string (first letter is capital; all others are lowercase).

• other() -> Color

  Returns the other color.

Positions

Positions are represented as tuples of row and column (r, c) or as tuples of board number, row, and column (bn, r, c). The following sections describe the actual objects Position and BoardPosition that are used throughout the code, but any methods that expect a Position or BoardPosition can also accept tuples representing the same.

The board number is 0 or 1, representing Board A (on the left) and Board B (on the right), respectively. The row and column are 0-indexed values in the range [0, 7], counting from the top left of each board. This means that each file is numbered 0 to 7 (i.e., file a is c = 0, file b is c = 1, and so on), but each rank is numbered in reverse order (i.e., rank 1 is r = 7, rank 2 is r = 6, and so on, with rank 8 being r = 0).

Position

Represents a position on a single board.

Constructors

• Position(r: int, c: int)

  Initializes a Position.

• Position.of(obj)

  Initializes a Position from a tuple or Position object.

• Position.from_code(code: str)

  Constructs a Position based on its code.

Properties

Name	Type	Description
pos	Tuple[int, int]	The row and column.
r	int	The row.
c	int	The column.
code	str	The position code (in algebraic notation).

Static Methods

• to_str(iterable: Iterable[Position], sep: str = " ") -> str

  Returns the Positions in the given iterable as a string.

Methods

• debug() -> str

  Returns a string representation for debugging.

BoardPosition

Represents a position on either board.

Constructors

• BoardPosition(r: int, c: int)

  Initializes a BoardPosition.

• BoardPosition.of(obj)

  Initializes a BoardPosition from a tuple or BoardPosition object.

• BoardPosition.from_code(code: str)

  Constructs a BoardPosition based on its code.

Properties

Name	Type	Description
pos	Tuple[int, int, int]	The board number, row, and column.
bn	int	The board number.
r	int	The row.
c	int	The column.
code	str	The position code (in algebraic notation).

Static Methods

• to_str(iterable: Iterable[BoardPosition], sep: str = " ") -> str

  Returns the BoardPositions in the given iterable as a string.

Methods

• debug() -> str

  Returns a string representation for debugging.

Moves

Moves are represented as tuples of a piece's BoardPosition and its target resulting Position ((bn, r, c), (tr, tc)). The following sections describe the actual objects Move, PieceMove, and PieceMoved that are used throughout the code, but any methods that expect a Move can also accept a tuple representing the same. (PieceMove and PieceMoved objects are only ever returned or accessed by the user.)

Move

Represents a move of a piece.

Constructors

• Move(pos: BoardPosition, target: Position)

  Initializes a Move.

• Move.of(obj)

  Initializes a Move from a tuple or Move object.

Properties

Name	Type	Description
pos	BoardPosition	The piece position.
target	Position	The target position.
capture_pos	BoardPosition	The capture position.
result_pos	BoardPosition	The piece's resulting position, after teleporting.

Static Methods

• to_str(iterable: Iterable[Move], sep: str = " ") -> str

  Returns the Moves in the given iterable as a string.

PieceMove

Represents a possible move for a piece, which is a Move that includes information about the piece.

Constructors

• PieceMove(pos: BoardPosition, target: Position, piece: Piece)

  Initializes a PieceMove.

• PieceMove.of(obj)

  Initializes a PieceMove from a tuple or PieceMove object.

Properties

Name	Type	Description
pos	BoardPosition	The piece position.
target	Position	The target position.
capture_pos	BoardPosition	The capture position.
result_pos	BoardPosition	The piece's resulting position, after teleporting.
piece_moved	Piece	The piece that is being moved.

Static Methods

• to_str(iterable: Iterable[PieceMove], sep: str = " ") -> str

  Returns the PieceMoves in the given iterable as a string.

PieceMoved

Represents a move done by a piece, which is a PieceMove that includes information about a possible capture.

These are constructed by GameState objects when moves are made, and users will likely not need to create them themselves.

Constructors

• PieceMoved(pos: BoardPosition, target: Position, piece: Piece, captured: Optional[Piece] = None)

  Initializes a PieceMoved.

• PieceMoved.of(obj)

  Initializes a PieceMoved from a tuple or PieceMoved object.

Properties

Name	Type	Description
pos	BoardPosition	The piece position.
target	Position	The target position.
capture_pos	BoardPosition	The capture position.
result_pos	BoardPosition	The piece's resulting position, after teleporting.
piece_moved	Piece	The piece that was moved.
move_captured	bool	Whether the move captured a piece.
piece_captured	Optional[Piece]	The piece that was captured, if given.

Static Methods

• to_str(iterable: Iterable[PieceMoved], sep: str = " ") -> str

  Returns the PieceMoveds in the given iterable as a string.

PieceType

Enum for the possible piece types.

Values

• PieceType.KING
• PieceType.QUEEN
• PieceType.ROOK
• PieceType.KNIGHT
• PieceType.BISHOP
• PieceType.PAWN

Methods

• title() -> str

  Returns the enum name as a title string (first letter is capital; all others are lowercase).

PromoteType

Enum for the possible promotion types.

Values

• PromoteType.QUEEN
• PromoteType.ROOK
• PromoteType.KNIGHT
• PromoteType.BISHOP

Static Methods

• by_index(i: int) -> PromoteType

  Returns the PromoteType at index i (in the order above).

EndGameState

Enum for the possible states for the end of the game.

Values

• EndGameState.CHECKMATE
• EndGameState.STALEMATE
• EndGameState.INSUFFICIENT_MATERIAL_DRAW: A draw by having insufficient material to end in a checkmate (such as only two kings).
• EndGameState.FIFTY_MOVE_DRAW: A draw through the fifty move rule.
• EndGameState.THREEFOLD_REPETITION_DRAW: A draw through the threefold repetition rule.

Methods

• human_readable() -> str

  Returns a human-readable name of this state.

• is_draw() -> bool

  Returns whether the current state is a type of draw.

Others

MovesCalculator

This is a helper class to calculate the possible moves for a given board state. There was a lot of code involved (such as checking for special cases like castling and en passant), including additional helper methods, so it was cleaner to bring it out to another class instead of including all of it in the GameState constructor. However, this means that only a MovesCalculator needs to know the possible ways a piece can move, and individual Piece objects are simply given their possible moves.

HumanPlayer

A HumanPlayer is a Player that does not implement the make_move() and promote() methods, and instead relies on other means of input to make moves in the game. For instance, HumanPlayers in a windowed game will use click events to select pieces and move them.

You will only need to use this if you want a human to play in a game by passing HumanPlayer as the white or black player to a Game.

Window

A Window is where a game can be played visually.

It uses the tkinter library to create the window. In my experience I have only ever used the Canvas object, so that is what I also used here. I believe there is more that tkinter has to offer, but I have stuck with what I know. The package comes installed with Python and is available on most Unix and Windows systems.

Constructors

• Window(game_state: GameState, non_human_player_delay: int = 3, debug: bool = False)

  Initializes a Window.

  Arguments:

  Name	Type	Description
  game_state	GameState	The starting game state.
  non_human_player_delay	int	The number of seconds of delay for non-human players to simulate realism.
  debug	bool	Whether to print debug information.

Methods

• run()

  Runs the game.

Keyboard Actions

Key	Action
q	Quit the game (press twice within 3 seconds).
p	Print debug information.
d	Toggle debug.
+	Increase the non-human player delay by 1 second.
-	Decrease the non-human player delay by 1 second.
Space	Pause/unpause the game (for games with no human players).