PyRat API

This section gives the documentation for functions and classes in the PyRat library. All modules below are part of the PyRat library and can be used to create and manipulate mazes, players, etc. To use any of them, you can import them as follows: from pyrat import <class_name>.

# A typical import line in one of your programs
from pyrat import Game, Player, Action, GameState, Maze

The big picture

The diagram below shows all the classes of the library, which class inherits from which, and how the game, the players, the mazes and the rendering engines fit together. Your own players (in green) are the only classes you write: they inherit from Player, receive a Maze and a GameState at each turn, and return an Action.

players game rendering mazes game.enums «abstract» Player - name : str - skin : PlayerSkin + get_name() : str + get_skin() : PlayerSkin + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) Game + DEFAULT_* : default value of each setting - maze_width, maze_height : int - cell_percentage, wall_percentage, mud_percentage : float - nb_cheese : int - fixed_maze, fixed_cheese, random seeds, … - random_maze_algorithm : RandomMazeAlgorithm - render_mode : RenderMode - game_mode : GameMode - preprocessing_time, turn_time : float - continue_on_error, save_game : bool + add_player(player, team, location) + reset(keep_players, same) + start() : dict[str, object] add_player() 1..* - players GameState + player_locations : dict[str, int] + score_per_player : dict[str, float] + muds : dict[str, dict] + teams : dict[str, list[str]] + cheese : list[int] + turn : int + get_players() : list[str] + get_opponents(name) : list[str] + get_score_per_team() : dict[str, float] + is_in_mud(name) : bool + game_over() : bool receives «abstract» Maze a Graph whose vertices are cells, numbered from 0 to width × height - 1 # width : int # height : int + get_width() : int + rc_exists(row, col) : bool + get_height() : int + coords_difference(vertex_1, vertex_2) : tuple[int, int] + i_to_rc(index) : tuple[int, int] + locations_to_action(source, target) : Action | None + rc_to_i(row, col) : int + locations_to_actions(locations) : list[Action | None] + i_exists(index) : bool # _create_maze() receives «enumeration» Action NOTHING NORTH SOUTH EAST WEST turn() returns FixedPlayer - actions : list[Action] + turn(maze, game_state) : Action «your code» Your players TemplatePlayer, Random1 … Random4, … - your attributes + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) + your methods «enumeration» PlayerSkin RAT PYTHON GHOST MARIO creates one per turn PyRatException inherits from the built-in Exception raised by any class of the library when it is used incorrectly (invalid argument, …) raises RenderingEngine (renders nothing, used for RenderMode.NO_RENDERING) # rendering_speed : float # render_simplified : bool + render(players, maze, game_state) + end() creates according to render_mode 1 - rendering_engine creates at start() 1 - maze Graph - adjacency : dict[Hashable, dict[Hashable, float | int]] + add_vertex(vertex) + get_neighbors(vertex) : list[Hashable] + remove_vertex(vertex) + nb_vertices() : int + add_edge(vertex_1, vertex_2, weight, symmetric) + nb_edges() : int + remove_edge(vertex_1, vertex_2, symmetric) + is_connected() : bool + has_edge(vertex_1, vertex_2) : bool + minimum_spanning_tree(random_seed) : Graph + edge_is_symmetric(vertex_1, vertex_2) : bool + random_spanning_tree(random_seed) : Graph + get_weight(vertex_1, vertex_2) : float | int + as_dict() : dict + get_vertices() : list[Hashable] + as_numpy_ndarray() : numpy.ndarray + get_edges() : list[tuple[Hashable, Hashable]] + as_torch_tensor() : torch.Tensor PyRatPlayerException raised when a player causes an error (crash, invalid action, …) ShellRenderingEngine RenderMode.ANSI / RenderMode.ASCII - use_colors : bool - clear_each_turn : bool + render(players, maze, game_state) PygameRenderingEngine RenderMode.GUI - fullscreen : bool - trace_length : int - gui_process : Process + render(players, maze, game_state) + end() rendering.gui (internal) GameWindow, Scene, Layout, MazeDecor, Assets The window runs in its own process, fed through a queue. launches RandomMaze a random maze with no holes # wall_percentage : float # mud_percentage : float # mud_range : tuple[int, int] # rng : random.Random # _create_maze() # _add_cells() # _add_walls() # _add_mud() MazeFromDict - description : dict[int, dict[int, int]] # _create_maze() MazeFromMatrix - description : numpy.ndarray | torch.Tensor # _create_maze() BigHolesRandomMaze # cell_percentage : float # target_nb_vertices : int # _add_cells() UniformHolesRandomMaze # cell_percentage : float # target_nb_vertices : int # _add_cells() HolesOnSideRandomMaze # cell_percentage : float # target_nb_vertices : int # _add_cells() «enumeration» GameMode MATCH SYNCHRONOUS SEQUENTIAL SIMULATION «enumeration» RenderMode GUI ANSI ASCII NO_RENDERING «enumeration» RandomMazeAlgorithm BIG_HOLES UNIFORM_HOLES HOLES_ON_SIDE «enumeration» StartingLocation CENTER TOP_LEFT TOP_RIGHT BOTTOM_LEFT BOTTOM_RIGHT RANDOM SAME
players game rendering mazes game.enums «abstract» Player - name : str - skin : PlayerSkin + get_name() : str + get_skin() : PlayerSkin + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) Game + DEFAULT_* : default value of each setting - maze_width, maze_height : int - cell_percentage, wall_percentage, mud_percentage : float - nb_cheese : int - fixed_maze, fixed_cheese, random seeds, … - random_maze_algorithm : RandomMazeAlgorithm - render_mode : RenderMode - game_mode : GameMode - preprocessing_time, turn_time : float - continue_on_error, save_game : bool + add_player(player, team, location) + reset(keep_players, same) + start() : dict[str, object] add_player() 1..* - players GameState + player_locations : dict[str, int] + score_per_player : dict[str, float] + muds : dict[str, dict] + teams : dict[str, list[str]] + cheese : list[int] + turn : int + get_players() : list[str] + get_opponents(name) : list[str] + get_score_per_team() : dict[str, float] + is_in_mud(name) : bool + game_over() : bool receives «abstract» Maze a Graph whose vertices are cells, numbered from 0 to width × height - 1 # width : int # height : int + get_width() : int + rc_exists(row, col) : bool + get_height() : int + coords_difference(vertex_1, vertex_2) : tuple[int, int] + i_to_rc(index) : tuple[int, int] + locations_to_action(source, target) : Action | None + rc_to_i(row, col) : int + locations_to_actions(locations) : list[Action | None] + i_exists(index) : bool # _create_maze() receives «enumeration» Action NOTHING NORTH SOUTH EAST WEST turn() returns FixedPlayer - actions : list[Action] + turn(maze, game_state) : Action «your code» Your players TemplatePlayer, Random1 … Random4, … - your attributes + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) + your methods «enumeration» PlayerSkin RAT PYTHON GHOST MARIO creates one per turn PyRatException inherits from the built-in Exception raised by any class of the library when it is used incorrectly (invalid argument, …) raises RenderingEngine (renders nothing, used for RenderMode.NO_RENDERING) # rendering_speed : float # render_simplified : bool + render(players, maze, game_state) + end() creates according to render_mode 1 - rendering_engine creates at start() 1 - maze Graph - adjacency : dict[Hashable, dict[Hashable, float | int]] + add_vertex(vertex) + get_neighbors(vertex) : list[Hashable] + remove_vertex(vertex) + nb_vertices() : int + add_edge(vertex_1, vertex_2, weight, symmetric) + nb_edges() : int + remove_edge(vertex_1, vertex_2, symmetric) + is_connected() : bool + has_edge(vertex_1, vertex_2) : bool + minimum_spanning_tree(random_seed) : Graph + edge_is_symmetric(vertex_1, vertex_2) : bool + random_spanning_tree(random_seed) : Graph + get_weight(vertex_1, vertex_2) : float | int + as_dict() : dict + get_vertices() : list[Hashable] + as_numpy_ndarray() : numpy.ndarray + get_edges() : list[tuple[Hashable, Hashable]] + as_torch_tensor() : torch.Tensor PyRatPlayerException raised when a player causes an error (crash, invalid action, …) ShellRenderingEngine RenderMode.ANSI / RenderMode.ASCII - use_colors : bool - clear_each_turn : bool + render(players, maze, game_state) PygameRenderingEngine RenderMode.GUI - fullscreen : bool - trace_length : int - gui_process : Process + render(players, maze, game_state) + end() rendering.gui (internal) GameWindow, Scene, Layout, MazeDecor, Assets The window runs in its own process, fed through a queue. launches RandomMaze a random maze with no holes # wall_percentage : float # mud_percentage : float # mud_range : tuple[int, int] # rng : random.Random # _create_maze() # _add_cells() # _add_walls() # _add_mud() MazeFromDict - description : dict[int, dict[int, int]] # _create_maze() MazeFromMatrix - description : numpy.ndarray | torch.Tensor # _create_maze() BigHolesRandomMaze # cell_percentage : float # target_nb_vertices : int # _add_cells() UniformHolesRandomMaze # cell_percentage : float # target_nb_vertices : int # _add_cells() HolesOnSideRandomMaze # cell_percentage : float # target_nb_vertices : int # _add_cells() «enumeration» GameMode MATCH SYNCHRONOUS SEQUENTIAL SIMULATION «enumeration» RenderMode GUI ANSI ASCII NO_RENDERING «enumeration» RandomMazeAlgorithm BIG_HOLES UNIFORM_HOLES HOLES_ON_SIDE «enumeration» StartingLocation CENTER TOP_LEFT TOP_RIGHT BOTTOM_LEFT BOTTOM_RIGHT RANDOM SAME

Tip

The diagram is interactive: hover it to magnify the area under the cursor, click on the name of a class to open its documentation page, or on one of its attributes or methods to jump directly to its description. You can also open the diagram at full size in a new tab.

Tip

The diagram is interactive: hover it to magnify the area under the cursor, click on the name of a class to open its documentation page, or on one of its attributes or methods to jump directly to its description. You can also open the diagram at full size in a new tab.

How to read the diagram

The diagram follows the conventions of UML class diagrams. If you are not familiar with them, here is all you need to know.

Boxes

Each box is a class, with three compartments: its name, its attributes, and its methods. A name in italics denotes an abstract class, that cannot be instantiated directly, and an italic method is a method that subclasses must implement. Boxes marked «enumeration» list constants, that you use as Action.NORTH, RenderMode.GUI, etc.

Visibility

The symbol before each attribute or method tells who is meant to use it: + is public (you can use it), # is protected (meant for subclasses), and - is private (internal to the class). Methods are listed with the names of their arguments and their return type.

Arrows

  • A solid line with a hollow triangle is inheritance: the classes below the line are subclasses of the class at the triangle. For instance, FixedPlayer is a Player.

  • A line with a filled diamond is composition: the Game creates and owns its maze and its rendering engine.

  • A line with a hollow diamond is aggregation: the Game groups players, but you create them yourself and register them with add_player(). The label at the far end of these lines gives the attribute of Game that holds the objects, and how many of them there are.

  • A dashed arrow is a dependency: the class at the tail creates, receives or returns the class at the head.

Colors

Orange boxes are the classes of the library, grouped by package in gray frames. Blue boxes are the enumerations. The green dashed box stands for the players you write, which inherit from Player. The gray note describes internal components, that are not part of the public API.

Which class does the game create?

Several settings of Game decide which concrete class is instantiated behind the scenes. The diagram shows all the candidates, and the table below tells which one is chosen.

Setting of Game

Value

Class created

random_maze_algorithm

RandomMazeAlgorithm.BIG_HOLES (default)

BigHolesRandomMaze

RandomMazeAlgorithm.UNIFORM_HOLES

UniformHolesRandomMaze

RandomMazeAlgorithm.HOLES_ON_SIDE

HolesOnSideRandomMaze

fixed_maze

A dictionary

MazeFromDict

A numpy array or a torch tensor

MazeFromMatrix

A Maze object

Used as is (a copy is made)

render_mode

RenderMode.GUI (default)

PygameRenderingEngine

RenderMode.ANSI or RenderMode.ASCII

ShellRenderingEngine (with or without colors)

RenderMode.NO_RENDERING

RenderingEngine (renders nothing)

The packages of the library

The classes of the library are grouped in four subpackages, which also appear as gray frames in the diagram above. Each one has its own page, listing the classes it contains.

game

What runs a game: the class you instantiate to start one, what your player is given at each turn, the constants you pass around, and the exceptions raised when something goes wrong.

Game, GameState, enums, PyRatException, PyRatPlayerException.

game
players

What a character in a game is: the class your own programs inherit from, and one ready-made player.

Player, FixedPlayer.

players
mazes

The place a game is played in: the graph a maze is built upon, the mazes you describe yourself, and the ones PyRat generates at random.

Maze, Graph, and five kinds of maze.

mazes
rendering

What shows a game while it is played, in a window or directly in your terminal.

RenderingEngine and its two implementations.

rendering