🐚 MOULEHUNTER

1. Présentation du Projet

1.1 Vue d'Ensemble

MouleHunter est une intelligence artificielle sophistiquée développée pour jouer au jeu compétitif de la "Pêche aux Moules". L'IA utilise des algorithmes de pathfinding avancés, notamment un parcours en largeur modifié (BFS), pour naviguer efficacement dans un environnement de type labyrinthe, collecter des moules et optimiser l'utilisation de bonus stratégiques.

1.2 Objectifs du Projet

• Performance compétitive : Développer une IA capable de rivaliser avec d'autres joueurs humains et artificiels
• Optimisation stratégique : Maximiser le score en optimisant les déplacements et l'utilisation des ressources
• Adaptabilité : S'adapter dynamiquement aux changements de l'environnement de jeu
• Efficacité algorithmique : Prendre des décisions en temps réel avec des calculs optimisés

1.3 Fonctionnalités Principales

Intelligence Stratégique

• Pathfinding Optimisé : Algorithme BFS (Breadth-First Search) pour trouver les chemins les plus courts
• Gestion des Bonus : Utilisation intelligente des frites (🍟) et bières (🍺)
• Évaluation Dynamique : Comparaison des stratégies pour choisir la meilleure approche à chaque tour

Stratégies Avancées

• Collecte prioritaire des moules à haute valeur
• Optimisation du ratio distance/valeur
• Anticipation des bonus disponibles sur le trajet
• Mode exploration automatique lorsqu'aucune moule n'est visible

1.4 Système de Scoring

Score = (Valeur_Moule × 10) + (Bonus_Collectés) - (Distance × 0.3) - (Ressources_Utilisées)

2. Architecture Technique

2.1 Structure du Projet

MouleHunter/
│
├── main.py                 # Point d'entrée principal de l'application
├── .env                    # Configuration (non versionné, à créer)
├── .example.env            # Template de configuration
├── .gitignore             # Fichiers exclus du versioning
├── _config.yml            # Configuration Jekyll (documentation web)
├── README.md              # Documentation utilisateur
├── LICENSE                # Licence MIT
│
├── .github/
│   └── workflows/         # CI/CD GitHub Actions
│
└── docs/                  # Documentation complémentaire
    

2.2 Composants Logiciels

2.2.1 Classe Labyrinthe

Responsable du parsing et de la gestion de l'environnement de jeu :

• Parse les données reçues du serveur
• Maintient la représentation de la grille de jeu
• Gère les positions des joueurs et les états des cases
• Identifie les murs, moules, et bonus

2.2.2 Classe IA

Cerveau décisionnel du bot comportant :

• Gestion d'Inventaire : Suivi en temps réel des frites et bières disponibles
• Algorithmes de Pathfinding :
  • parcourt_largeur_avec_frites() - Navigation avec capacité de saut
  • parcourt_largeur_avec_biere() - Navigation avec mouvements multiples
• Évaluation : evaluer_objectif() pour scorer chaque cible potentielle
• Décision : choisir_coup() pour sélectionner le meilleur mouvement

2.3 Architecture Réseau

┌─────────────────┐
│  Serveur de Jeu │
│   (TCP/IP)      │
└────────┬────────┘
         │
         │ Socket Connection
         │ (IP:PORT)
         │
         ▼
┌─────────────────┐
│  MouleHunter    │
│     Client      │
│                 │
│  ┌───────────┐  │
│  │ Labyrinthe│  │
│  │  Parser   │  │
│  └─────┬─────┘  │
│        │        │
│        ▼        │
│  ┌───────────┐  │
│  │    IA     │  │
│  │  Engine   │  │
│  └─────┬─────┘  │
│        │        │
│        ▼        │
│  ┌───────────┐  │
│  │ Decision  │  │
│  │  Maker    │  │
│  └───────────┘  │
└─────────────────┘
        

3. Prérequis Système

3.1 Configuration Matérielle Minimale

3.2 Logiciels Requis

3.2.1 Python

• Version : Python 3.8 ou supérieur
• Vérification : python --version ou python3 --version
• Installation : https://www.python.org/downloads/

3.2.2 Bibliothèques Python

Le projet utilise uniquement les bibliothèques standard de Python :

• socket - Communication réseau
• os - Gestion des variables d'environnement
• collections - Structures de données (deque pour BFS)
• random - Génération de mouvements aléatoires

3.3 Accès Réseau

4. Installation et Configuration

4.1 Installation

4.1.1 Méthode 1 : Clone via Git

# Cloner le repository
git clone https://github.com/Thenoob24/MouleHunter.git

# Naviguer dans le dossier
cd MouleHunter
    

4.1.2 Méthode 2 : Téléchargement ZIP

1. Aller sur https://github.com/Thenoob24/MouleHunter
2. Cliquer sur "Code" → "Download ZIP"
3. Extraire l'archive dans le dossier de votre choix
4. Ouvrir un terminal dans ce dossier

4.2 Configuration

4.2.1 Création du Fichier de Configuration

# Copier le template de configuration
cp .example.env .env

# Sous Windows :
copy .example.env .env
    

4.2.2 Paramètres de Configuration

Éditer le fichier .env avec vos paramètres :

# Configuration du serveur de jeu
SERVEUR_IP=192.168.1.100
SERVEUR_PORT=5555
NOM_EQUIPE=MouleHunter_Team
    

4.3 Vérification de l'Installation

# Vérifier la version Python
python --version
# ou
python3 --version

# Devrait afficher : Python 3.8.x ou supérieur

# Lister les fichiers du projet
ls -la
# ou sous Windows :
dir
    

4.4 Structure de Fichiers Attendue

Après installation et configuration, votre dossier devrait contenir :

MouleHunter/
├── main.py          ✓ Script principal
├── .env             ✓ Votre configuration (créé)
├── .example.env     ✓ Template
├── README.md        ✓ Documentation
├── LICENSE          ✓ Licence MIT
└── docs/            ✓ Documentation supplémentaire
    

5. Déploiement

5.1 Déploiement Local

5.1.1 Lancement Simple

python main.py
# ou si nécessaire :
python3 main.py
    

5.1.2 Vérification du Démarrage

Un démarrage réussi affiche :

🎮 Connecté → MouleHunter_Team (Joueur 0)
En attente du début de la partie...
    

5.2 Déploiement sur Serveur

5.2.1 Déploiement avec Screen (Linux)

# Créer une session screen
screen -S moulehunter

# Lancer l'application
python3 main.py

# Détacher la session : Ctrl+A puis D
# Réattacher : screen -r moulehunter
    

5.2.2 Déploiement avec tmux (Linux)

# Créer une session tmux
tmux new -s moulehunter

# Lancer l'application
python3 main.py

# Détacher : Ctrl+B puis D
# Réattacher : tmux attach -t moulehunter
    

5.2.3 Déploiement comme Service Systemd (Linux)

Créer le fichier /etc/systemd/system/moulehunter.service :

[Unit]
Description=MouleHunter IA Bot
After=network.target

[Service]
Type=simple
User=votre_utilisateur
WorkingDirectory=/chemin/vers/MouleHunter
ExecStart=/usr/bin/python3 /chemin/vers/MouleHunter/main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
    

Commandes de gestion du service :

# Recharger systemd
sudo systemctl daemon-reload

# Activer le service au démarrage
sudo systemctl enable moulehunter

# Démarrer le service
sudo systemctl start moulehunter

# Vérifier le statut
sudo systemctl status moulehunter

# Voir les logs
sudo journalctl -u moulehunter -f
    

5.3 Déploiement Docker (Optionnel)

Créer un Dockerfile :

FROM python:3.10-slim

WORKDIR /app
COPY . /app

CMD ["python", "main.py"]
    

Construction et exécution :

# Construire l'image
docker build -t moulehunter .

# Exécuter le conteneur
docker run -d --name moulehunter-bot \
    --env-file .env \
    --restart unless-stopped \
    moulehunter
    

6. Guide d'Utilisation

6.1 Lancement du Bot

python main.py
    

6.2 Sortie Console Typique

🎮 Connecté → GodMoules2025 (Joueur 0)

🎮 Tour à (5, 3) | 🍟 2 | 🍺 1
🎯 Stratégie FRITES: 4 coups, 1 frites nécessaires
   Bonus en route: 🍟 1 | 🍺 0
🍟 UTILISE FRITE ! (reste 1)
  → 🍟 +1 frite (total: 2)
  → 🐚 +5 moules
➡️  JOUE: Bs-N
    

6.3 Interprétation des Messages

6.3.1 Messages de Connexion

6.3.2 Messages de Tour

6.4 Commandes et Mouvements Envoyés

L'IA envoie des commandes au serveur sous forme de chaînes de caractères spécifiques. Voici les principaux formats :

7. Algorithmes et Stratégies

7.1 Pathfinding Principal (BFS Modifié)

L'algorithme central est un Breadth-First Search adapté aux contraintes du jeu :

• Prise en compte des coûts variables (1 tour normal vs saut frite vs combo bière)
• État étendu : position + inventaire frites/bières restant
• Arrêt anticipé dès qu'une cible viable est atteinte (moule ou bonus prioritaire)
• Complexité : O(L × W × I) où L×W = taille labyrinthe, I = états inventaire (limité)

Variantes implémentées

• parcourt_largeur_avec_frites() : autorise un saut de mur si frite disponible
• parcourt_largeur_avec_biere() : simule des séquences de 2 ou 3 cases en un coup
• exploration_aléatoire_pondérée() : backup quand aucune cible n'est visible

7.2 Logique de Décision

À chaque tour, l'IA :

1. Parse la grille et met à jour l'inventaire
2. Identifie toutes les cibles visibles (moules + bonus)
3. Calcule pour chacune le score via evaluer_objectif()
4. Choisit la cible avec le meilleur ratio valeur / coût estimé
5. Simule le chemin optimal (avec ou sans bonus)
6. Envoie la commande correspondante

8. Maintenance et Monitoring

8.1 Mise à Jour du Code

# Aller dans le dossier du projet
cd MouleHunter

# Récupérer les dernières modifications
git pull origin main

# Relancer le bot
python3 main.py
        

8.2 Logs et Monitoring

• Logs console très verbeux (position, inventaire, stratégie, coup joué)
• Redirection recommandée :

  python3 main.py >> logs/moulehunter_$(date +%Y%m%d_%H%M).log 2>&1

• Surveillance live :

  tail -f logs/moule*.log

• Outils utiles : htop, ss -tuln (connexions), journalctl -u moulehunter (si systemd)

8.3 Sauvegarde Configuration

Conservez toujours une copie de votre .env en lieu sûr (ne jamais le commiter).

9. Dépannage

10. Sécurité

• Connexion sortante uniquement (pas de port entrant)
• Aucune authentification forte (nom d'équipe seulement)
• Recommandations :
  • Ne pas exposer le serveur de jeu sur Internet sans VPN / reverse-proxy
  • Utiliser un firewall limitant les IP sortantes
  • Ne jamais commiter .env
  • Sur serveur partagé : lancer sous utilisateur dédié (non-root)

11. Optimisation des Performances

• Pathfinding : BFS reste < 100-200 ms même sur grandes grilles (grâce à arrêt anticipé)
• Mémoire : < 50 Mo (grille + états limités)
• Optimisations possibles :
  • Cache des chemins calculés
  • Pruning agressif des cibles trop éloignées
  • Multithreading léger pour simulations parallèles (non implémenté)

12. Annexes

12.1 Exemple Complet de .env

# ────────────────────────────────────────────────
# MouleHunter - Fichier .env
# ────────────────────────────────────────────────

SERVEUR_IP=127.0.0.1
SERVEUR_PORT=12345
NOM_EQUIPE=GodMoules2026
        

12.2 Symboles du Jeu (référence serveur)

• Mu / # : Mur
• 0-9 : Moule (valeur)
• Bs : Bonus Frites
• Bp : Bonus Bière
• Te : Case vide / traversable

12.3 Liens Utiles

• Serveur de référence : https://github.com/synave/peche_aux_moules
• Dépot du projet : https://github.com/Thenoob24/MouleHunter