PyRat Documentation¶

The PyRat mascot, a pirate rat with a python around its shoulders, looking through a spyglass and shouting Go!

Computer science course · IMT Atlantique

Teach a rat to find cheese in a maze, and learn algorithms along the way.

uvx --python 3.13 --from pyrat-game pyrat-initcreates your workspace, with PyRat installed in it

See It in Action¶

A match between two players that always run to the closest piece of cheese. The rat of Team Ratz wins 8 to 7 against the python of Team Pythonz.

What is PyRat?¶

PyRat is a maze game, played by programs. A rat, or a python, is placed in a maze where pieces of cheese are scattered. Your job is to write the program that decides, at each turn, where it goes next. Walls block the way, mud slows you down, and an opponent may be after the same pieces of cheese.

Behind the game, the maze is a graph: cells are vertices, and the passages between them are edges, weighted by the mud. Catching cheese therefore means traversing a graph, finding shortest paths, solving a traveling salesperson problem, and eventually outsmarting an opponent. PyRat takes care of everything else: it generates the mazes, runs the game, times the players, and shows what happens.

Write players in Python

A player is a class with a turn() method that returns a move. Add a preprocessing() method to think ahead before the game starts.

Watch them play

An animated interface shows every move, the mud being crossed, the scores of the teams and the final ranking.

Measure and compare

Turn the interface off to play hundreds of games in seconds, and get statistics on each of them to compare your ideas.

Shape your mazes

Choose the size, walls, mud and cheese, fix a seed to replay the same game, or draw a maze with the Maze Builder.

A Player in a Few Lines¶

A player goes in the players directory of your workspace, and a game that uses it goes in the games directory. Here is a player that moves at random, and a game in which it looks for 5 pieces of cheese.

players/my_player.py

import random
from pyrat import Player, Maze, GameState, Action

class MyPlayer (Player):

    def turn (self, maze: Maze, game_state: GameState) -> Action:

        # Go to a random neighbor of the current cell
        here = game_state.player_locations[self.get_name()]
        there = random.choice(maze.get_neighbors(here))
        return maze.locations_to_action(here, there)

games/my_game.py

from pyrat import Game
from players.my_player import MyPlayer

if __name__ == "__main__":

    # A maze of 15 by 11 cells, with 5 pieces of cheese to find
    game = Game(maze_width=15, maze_height=11, nb_cheese=5)
    game.add_player(MyPlayer())
    stats = game.start()

Then run uv run games/my_game.py from your workspace. The Random Programs tutorial goes further, with four players that get better and better.

From One Piece of Cheese to a Tournament¶

The course at IMT Atlantique uses PyRat as a thread through a series of algorithmic problems. Each step makes the game a bit harder, and calls for a new idea.

Discover PyRatInstall it, run a first game, and see how players take decisions.
Catch a piece of cheeseModel the maze as a graph, and explore it with a breadth-first or depth-first search.
Cross the mudSome moves take longer than others: find shortest paths in a weighted graph with Dijkstra's algorithm.
Catch them allVisit every piece of cheese in as few moves as possible: a traveling salesperson problem, solved by exhaustive search.
Catch them fasterTrade optimality for speed, with heuristics and greedy algorithms.
Face an opponentAnother player wants the same cheese: time to think in terms of game theory.
Win the tournamentPut your best player against those of everyone else.