Le tournoi PyRat

Objectifs de la séance

Après l’examen final, un créneau horaire est dédié à un tournoi PyRat. Il se déroulera après les vacances, pour vous laisser un peu de temps si vous voulez peaufiner votre IA.

Pour ce tournoi, vous devrez concevoir un programme PyRat pour affronter un adversaire. Le joueur qui ramasse le plus de morceaux de fromage remporte la partie !

Cet événement est facultatif et non-évalué, conçu uniquement pour vous amuser.

Voici quelques vidéos réalisées depuis la création du cours PyRat ! Certaines sont plus « commerciales » que d’autres, mais elles offrent un aperçu de l’ambiance pendant le tournoi, ainsi que des versions plus anciennes du jeu !

• 2015.
• 2016.
• 2019.

Organisation du tournoi

Deux phases

Malheureusement, nous n’aurons pas le temps de faire concourir tout le monde dans le tournoi final. Par conséquent, nous procéderons sous forme de poules, dans lesquelles tous les programmes s’affronteront deux à deux, chaque rencontre se jouant en deux manches gagnantes (au plus 3 parties). Les points sont attribués comme suit :

• L’équipe qui gagne une rencontre marque l’écart entre les nombres de parties gagnées, plus 1 : 3 points pour une victoire 2 à 0, et 2 points pour une victoire 2 à 1. L’équipe qui perd ne marque rien.
• Si les deux équipes ont gagné autant de parties (par exemple, si des parties se terminent sur un match nul), la rencontre revient à celle dont le temps de calcul total est le plus faible, qui marque 1 point. En cas d’égalité parfaite (même temps de calcul), la rencontre est attribuée par tirage au sort.

Dans chaque poule, nous conserverons les deux meilleurs programmes, c’est-à-dire, ceux avec le plus grand nombre de points. En cas d’égalité de points, nous considérerons comme meilleur programme celui avec le temps de calcul total le plus faible sur les rencontres gagnées.

Une fois les vainqueurs des poules déterminés (soit 16 programmes ; s’il y a peu d’équipes inscrites, le nombre de poules est réduit), le tournoi lui-même aura lieu en amphithéâtre le 4 janvier 2027. Les matchs seront déterminés aléatoirement. Les poules étant jouées avant cette date, les programmes doivent être soumis au plus tard le 2 janvier 2027 au soir (voir comment participer).

Le/La gagnant(e) du tournoi remportera un trophée, et son IA servira de boss final pour les étudiant(e)s de l’année suivante !

Paramètres de PyRat

Les options suivantes seront utilisées pour créer les parties PyRat :

• maze_width: 25.
• maze_height: 20.
• cell_percentage: 80.0.
• wall_percentage: 60.0.
• mud_percentage: 20.0.
• mud_range: [4, 9].
• nb_cheese: 41.
• preprocessing_time: 3.0.
• turn_time: 0.1.
• game_mode: GameMode.MATCH (chaque joueur tourne dans son propre processus ; un joueur qui dépasse preprocessing_time ou turn_time saute des tours jusqu’à la fin de son calcul).
• continue_on_error: True (si votre code lève une exception, la partie continue et votre joueur ne fait rien à ce tour).

Voici le script de jeu que nous utiliserons pour le tournoi.

Le script prépare lui-même chaque équipe à partir de son dépôt : il clone le dépôt au commit indiqué, crée son environnement avec uv sync (à partir de votre pyproject.toml et de votre uv.lock), puis fait jouer votre joueur dans cet environnement, depuis la racine de votre dépôt. Votre joueur peut donc importer les autres fichiers de votre dépôt (par exemple from utils.traversal.dijkstra_traversal import DijkstraTraversal), et utiliser les bibliothèques que vous avez ajoutées avec uv add. Seule la version de PyRat est imposée : c’est celle du tournoi, pour toutes les équipes.

Pour le tester chez vous :

1. Copiez tournament.py dans le dossier games de votre workspace.

2. Ajoutez la ligne tournament_files/ au fichier .gitignore de votre workspace : ce dossier contient les copies des dépôts et les résultats, qui ne doivent pas être envoyés sur GitLab.

3. Créez le fichier tournament_files/teams.csv à la racine de votre workspace, qui liste les équipes, par exemple :

   team,url,commit,player
   Mon équipe,.,HEAD,players/mon_joueur.py
   Adversaire,.,HEAD,players/random4.py

   Chaque ligne donne le nom de l’équipe, l’adresse de son dépôt (ici ., c’est-à-dire votre propre workspace), le commit à utiliser (ici HEAD, le dernier commit), et le chemin du fichier du joueur dans le dépôt. Vous pouvez aussi faire jouer votre joueur contre une version plus ancienne de lui-même (en indiquant l’identifiant d’un ancien commit), ou contre le dépôt d’une autre équipe.

4. Lancez uv run games/tournament.py depuis le workspace. Le script prépare d’abord les équipes, et signale tout problème (commit introuvable, fichier absent, joueur qui ne se charge pas) ; uv run games/tournament.py --prepare-only s’arrête après cette étape. Les parties sont ensuite sauvegardées dans tournament_files/results/, et ce qu’affiche chaque joueur (y compris ses erreurs) dans tournament_files/logs/<équipe>.log.

Attention : le script utilise votre dépôt tel qu’il est dans le commit indiqué. Les modifications que vous n’avez pas commitées ne sont donc pas prises en compte, exactement comme lors du tournoi.

    def __init__ ( self,
                   *args:    object,
                   **kwargs: object
                 ) ->        None:

        # Inherit from parent class
        super().__init__(name="Votre nom ici", *args, **kwargs)

Comment participer ?

La participation se fait comme pour les livrables du projet (voir la séance 3) : votre joueur doit se trouver sur le dépôt GitLab de votre équipe, et vous nous indiquez sur Moodle la version à utiliser. La date limite est fixée au 2 janvier 2027 au soir (l’heure précise est indiquée sur Moodle), et non au jour du tournoi : il nous faut ce délai pour jouer les poules avant le tournoi du 4 janvier.

Comment s’inscrire

• Placez le joueur qui participera au tournoi dans le dossier players de votre dépôt. Il peut importer les autres fichiers de votre dépôt (utils, d’autres joueurs…), comme vos joueurs du projet : le tournoi utilise votre dépôt complet, au commit que vous indiquez. Le fichier du joueur ne doit définir qu’une seule sous-classe non abstraite de Player (voir plus haut). Si votre joueur a besoin de bibliothèques autres que PyRat, ajoutez-les avec uv add, et commitez les fichiers pyproject.toml et uv.lock : c’est à partir d’eux que l’environnement de votre équipe est créé.

• Ajoutez un script de jeu dans le dossier games (par exemple games/visualize_tournament_player.py), qui lance une partie avec votre joueur et les paramètres du tournoi donnés plus haut. Inspirez-vous de vos scripts visualize_xxx.py.

• Ajoutez la section suivante au début du fichier README.md de votre projet (remplacez les éléments entre chevrons <...> (chevrons inclus) par ce qui est demandé) :

  # Tournoi
  
  - Nom de l'équipe : <nom de votre équipe>
  - Membres de l'équipe : <vos noms ici>
  - Campus et groupe : <campus et groupe>
  - Fichier du joueur : <players/nom_du_fichier.py>
  - Nom du joueur : <nom donné dans le constructeur, avec super().__init__(name="...", *args, **kwargs)>
  - Script de jeu : <games/nom_du_script.py>
  
  *Décrivez en quelques lignes la stratégie de votre joueur.*
  
  <détaillez ça ici>
  
  *Des indications particulières pour faire fonctionner votre programme ?*
  *Votre joueur a-t-il besoin de bibliothèques autres que PyRat ?*
  
  <détaillez ça ici>

• Vérifiez bien que vous avez envoyé tous vos codes et le README.md sur le dépôt GitLab de votre équipe.

• Assurez-vous que votre enseignant(e) est bien membre de votre dépôt GitLab avec le rôle Maintainer, comme demandé lors de la séance 1.

• Un(e) membre de l’équipe doit se connecter sur Moodle, et fournir :

  • Votre campus.
  • L’emplacement du fichier contenant votre joueur sur le dépôt.
  • Le nom choisi pour votre équipe.
  • L’URL HTTPS de clonage de votre dépôt GitLab :
  • L’identifiant du commit à utiliser pour le tournoi :