Workspace API

PyRat comes with a workspace that you should use to start working on your games. It is created with the pyrat-init command that we ask you to run in the installation instructions, which puts it in a pyrat_workspace directory.

Your programs live in that directory, organized around the two directories documented in this section.

Your workspace is added to the directories Python imports from, which is what lets your programs import each other. An import names the file to read as its path inside your workspace, with a dot instead of each / and without the .py, followed by what you want to take from it. For instance, this is how the sample_game.py script imports the Random2 class written in players/random2.py:

from players.random2 import Random2

Nothing has to be declared anywhere for this to work, it works wherever you run your program from, and renaming or moving your workspace changes nothing.

Players

The programs that control a character during a game. A player is a class that inherits from Player, and decides which action to take at each turn.

Your workspace comes with five of them.

Players
Games

The scripts that set up a game and make players compete in it. This is what you run to actually see a game.

Your workspace comes with two of them.

Games

You can later add more directories to your workspace if you want to organize your programs differently, and they are importable the same way: a class Tools written in utils/tools.py is imported with from utils.tools import Tools. Your workspace also contains the files used by uv to describe the Python version and the libraries of your project, which you usually do not need to edit by hand. Finally, it contains a .gitignore file listing what Git should not version (the virtual environment, temporary files, etc.), so that it is ready to be put under version control.

Tip

The programs documented in this section are the ones created in your workspace. Reading their source code, linked on each page, is the fastest way to understand how a PyRat program is written.

The big picture

The diagram below shows the programs of your workspace, and how they relate to the PyRat library: the players inherit from Player, and the game scripts create a Game in which they make some of these players compete, using the enumerations of the library to choose their skin and their starting location.

pyrat players games Game + __init__(maze_width, maze_height, nb_cheese, …) + add_player(player, team, location) + reset(keep_players, same) + start() : dict[str, object] «abstract» Player - name : str - skin : PlayerSkin + __init__(name, skin) + get_name() : str + get_skin() : PlayerSkin + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) «script» sample_game.py A match between two teams: a Random2 against a Random3 Custom maze size, walls, mud and cheese Prints the statistics of the game create a Game «enumeration» PlayerSkin RAT PYTHON GHOST MARIO skin of the players «enumeration» StartingLocation CENTER TOP_LEFT TOP_RIGHT BOTTOM_LEFT BOTTOM_RIGHT RANDOM SAME «script» visualize_random_players.py Random1 to Random4 in the same maze, one after the other Fixed random seed, no mud, a single piece of cheese Prints the statistics of each player starting location of the players TemplatePlayer does nothing, the file to copy for a new player + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) Random1 moves at random + __init__(*args, **kwargs) + turn(maze, game_state) : Action + find_next_action() : Action Random2 avoids walls + __init__(*args, **kwargs) + turn(maze, game_state) : Action + find_next_action(maze, game_state) : Action Random3 prefers unvisited cells + visited_cells : set[int] + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + find_next_action(maze, game_state) : Action Random4 also avoids dead ends + visited_cells : set[int] + reduced_maze : Maze + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + find_next_action(maze, game_state) : Action + remove_dead_ends(maze, locations_to_keep) : Maze add players
pyrat players games Game + __init__(maze_width, maze_height, nb_cheese, …) + add_player(player, team, location) + reset(keep_players, same) + start() : dict[str, object] «abstract» Player - name : str - skin : PlayerSkin + __init__(name, skin) + get_name() : str + get_skin() : PlayerSkin + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) «script» sample_game.py A match between two teams: a Random2 against a Random3 Custom maze size, walls, mud and cheese Prints the statistics of the game create a Game «enumeration» PlayerSkin RAT PYTHON GHOST MARIO skin of the players «enumeration» StartingLocation CENTER TOP_LEFT TOP_RIGHT BOTTOM_LEFT BOTTOM_RIGHT RANDOM SAME «script» visualize_random_players.py Random1 to Random4 in the same maze, one after the other Fixed random seed, no mud, a single piece of cheese Prints the statistics of each player starting location of the players TemplatePlayer does nothing, the file to copy for a new player + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + postprocessing(maze, game_state, stats) Random1 moves at random + __init__(*args, **kwargs) + turn(maze, game_state) : Action + find_next_action() : Action Random2 avoids walls + __init__(*args, **kwargs) + turn(maze, game_state) : Action + find_next_action(maze, game_state) : Action Random3 prefers unvisited cells + visited_cells : set[int] + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + find_next_action(maze, game_state) : Action Random4 also avoids dead ends + visited_cells : set[int] + reduced_maze : Maze + __init__(*args, **kwargs) + preprocessing(maze, game_state) + turn(maze, game_state) : Action + find_next_action(maze, game_state) : Action + remove_dead_ends(maze, locations_to_keep) : Maze add players

Tip

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

Tip

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