Sokoban

Cette documentation détaille le fonctionnement, l’architecture et la maintenance du projet Sokoban, un jeu de puzzle classique implémentant un système de génération de niveaux procéduraux et une architecture MVC (Modèle-Vue-Contrôleur).

1. Objectifs du Projet

Le but de ce projet est de fournir une version fonctionnelle et extensible du jeu Sokoban. Les objectifs principaux incluent :

• Génération Procédurale : Création automatique de niveaux de difficulté croissante.
• Architecture Propre : Séparation stricte entre la logique de jeu, l’affichage et la gestion des entrées.
• Persistance : Sauvegarde automatique de la progression de l’utilisateur.
• Système d’Annulation (Undo) : Permettre à l’utilisateur de revenir en arrière après une erreur.

2. Dépendances

Le projet est développé en Python 3.x et repose sur une seule bibliothèque externe :

• Pygame : Utilisée pour le rendu graphique, la gestion des fenêtres et les entrées clavier.

Installation

Pour installer la dépendance nécessaire, exécutez :

pip install pygame

---

3. Structure des Fichiers

Le projet est organisé comme suit :

Fichier	Rôle
main.py	Point d’entrée de l’application.
controller.py	Gère la boucle d’événements et la machine à états (Menu, Jeu, Victoire).
model.py	Contient la logique pure du jeu (coordonnées, règles de mouvement, collisions).
view.py	Gère le rendu graphique et l’affichage à l’écran via Pygame.
generator.py	Algorithme de création de niveaux (méthode de « reverse-play »).
generate_assets.py	Script utilitaire pour générer les images de base (murs, sol, joueur).
regenerate_levels.py	Script pour générer par lots les 40 fichiers de niveaux initiaux.
assets/	Répertoire contenant les textures (PNG).
levels/	Répertoire stockant les fichiers texte des niveaux.

---

4. Mode Opératoire

Initialisation

Avant de lancer le jeu pour la première fois, ou si les images sont manquantes :

1. Exécutez python generate_assets.py pour créer le dossier assets/ et les textures.
2. Exécutez python regenerate_levels.py pour remplir le dossier levels/.

Lancement du jeu

Exécutez la commande :

python main.py

Commandes en jeu

• Flèches directionnelles : Déplacer le personnage / Pousser une caisse.
• U : Annuler le dernier coup (Undo).
• R : Recommencer le niveau actuel.
• Entrée : Démarrer le jeu ou passer au niveau suivant après une victoire.
• G : Générer et jouer un niveau aléatoire instantané.
• Échap : Retour au menu ou quitter.

---

5. Détails Techniques & Maintenance

Algorithme de Génération (generator.py)

Le générateur utilise une technique de marche arrière (Reverse Play) pour garantir que chaque niveau est solvable :

1. Il crée une pièce vide de forme irrégulière (marcheur aléatoire).
2. Il place les cibles et les caisses sur ces mêmes cibles (état « gagné »).
3. Il effectue des milliers de mouvements de « tirage » (pull) au lieu de pousser. Le joueur « tire » les caisses depuis leur position finale vers une position de départ complexe.
4. Le résultat est exporté au format standard Sokoban (# Mur, @ Joueur, $ Caisse, . Cible).

Système de Sauvegarde

La progression est stockée dans un fichier simple nommé save.txt. Il contient uniquement l’index du dernier niveau atteint. Pour réinitialiser la progression, supprimez ce fichier ou changez le nombre à 1.

Maintenance de l’Affichage (view.py)

La taille des tuiles est définie par tile_size=64. Si vous souhaitez adapter le jeu pour des écrans plus petits, modifiez cette valeur. La vue s’adapte automatiquement à la taille du niveau chargé dans le modèle.

---

6. Améliorations Possibles

Pour faire évoluer ce projet, voici plusieurs pistes suggérées :

Gameplay & Fonctionnalités

• Animations de mouvement : Actuellement, le joueur se téléporte d’une case à l’autre. Ajouter une interpolation fluide améliorerait le confort visuel.
• Compteur de temps : Ajouter un chronomètre pour inciter au speedrun.
• Système de score : Calculer un score basé sur le nombre de coups minimum (comparé au nombre de pas effectués lors de la génération).

Technique

• Gestion des ressources : Créer une classe ResourceManager pour centraliser le chargement des images et sons afin d’éviter les accès disque multiples.
• Éditeur de niveaux : Développer une interface graphique simple pour permettre aux utilisateurs de dessiner leurs propres niveaux manuellement.

Audio

• Effets sonores : Ajouter des sons pour les pas, le glissement des caisses et la victoire.
• Musique d’ambiance : Intégrer une boucle musicale pour le menu et les phases de jeu.

---

Annexe : Format des Niveaux

Les niveaux sont stockés en .txt. Voici la légende des symboles :

• # : Mur
• : Sol
• . : Cible (Destination)
• @ : Joueur
• $ : Caisse
• * : Caisse sur une cible
• + : Joueur sur une cible

---

Source