Un projet de décompilation en C du jeu PSX Alundra avec système de comparaison automatique et workflow CI/CD.

Ce projet vise à recréer le code source original du jeu Alundra (PlayStation 1) en C, avec des outils de comparaison binaire pour vérifier l'exactitude de la décompilation. Le projet s'inspire des meilleures pratiques des projets de décompilation Silent Hill, SOTC et Street Fighter III.

alundra-decomp/
├── src/                    # Code source C décompilé
│   ├── main/              # Code principal du jeu
│   ├── engine/            # Moteur de jeu
│   ├── game/              # Logique de gameplay
│   └── data/              # Structures de données
├── include/               # Headers C
├── assets/                # Assets extraits (sprites, sons, etc.)
├── tools/                 # Outils de décompilation
│   ├── compare.py         # Script de comparaison binaire
│   ├── extract.py         # Extracteur d'assets
│   └── analyze.py         # Analyseur de binaire
├── original/              # Binaire original d'Alundra
├── build/                 # Fichiers de build
└── .github/workflows/     # Workflows GitHub Actions

Linux / WSL:

• GCC (avec support MIPS/PSX)
• Make
• Python 3.8+
• Git

Windows:

• Visual Studio 2019 ou plus récent
• Python 3.8+
• Git

1. Cloner le repository:

git clone https://github.com/votre-username/alundra-decomp.git
cd alundra-decomp

2. Obtenir le binaire original:

   • Vous devez posséder une copie légale du jeu Alundra (PSX)
   • Extraire le binaire du jeu et le placer dans le dossier original/
   • Renommer le fichier en SLUS_XXX.XX (selon votre version)

3. Installer les dépendances Python:

pip install -r requirements.txt

4. Vérifier la configuration du SDK PSX:

python tools/verify_sdk.py

Cette commande vérifie que le SDK PSX est correctement configuré. Vous devriez voir:

✓ All checks passed!

Si vous voyez des erreurs, consultez BUILD_FIX.md pour les instructions de dépannage.

# Compilation complète
make all

# Nettoyage
make clean

# Compilation + comparaison avec l'original
make compare

# Afficher le progrès de décompilation
make progress

1. Ouvrir AlundraDecomp.sln dans Visual Studio
2. Sélectionner la configuration (Debug/Release)
3. Build > Build Solution (Ctrl+Shift+B)
4. Les outils de comparaison s'exécutent automatiquement en Post-Build

Le projet inclut une configuration complète pour objdiff:

Fichiers de configuration:

• objdiff.json - Configuration principale (chemins, architecture, algorithme)
• diff_settings.py - Paramètres avancés (toolchain, options d'affichage)

Validation de la configuration:

python tools/test_objdiff_config.py

Cette commande vérifie:

• Validité des fichiers de configuration
• Existence des binaires et symboles
• Paramètres d'architecture et de plateforme

objdiff est un outil de comparaison binaire visuel qui permet de comparer les fonctions décompilées avec l'original de manière interactive.

Le projet est pré-configuré pour objdiff avec:

• objdiff.json - Configuration principale du projet
• diff_settings.py - Paramètres de comparaison et chemins

Pour valider la configuration:

python tools/test_objdiff_config.py

# Windows
objdiff.bat

# Linux/macOS
./objdiff.sh

# Depuis le menu d'automatisation
python automate.py
# Sélectionner option 10

# Avec quick_start.py
python tools/quick_start.py --objdiff

# Ouvrir une fonction spécifique
python tools/update_function.py --objdiff main

• Interface graphique intuitive
• Comparaison côte-à-côte de l'assemblage
• Coloration des différences (vert = match, rouge = différent)
• Navigation rapide entre les fonctions
• Statistiques de correspondance en temps réel
• Support des symboles et numéros de ligne

1. Compiler le projet pour générer les symboles:

   make

2. Lancer objdiff:

   ./objdiff.sh  # ou objdiff.bat sur Windows

3. Sélectionner une fonction dans la liste et comparer l'assemblage

4. Ajuster le code C en fonction des différences observées

5. Recompiler et rafraîchir jusqu'à obtenir un match parfait (100%)

📖 Guide complet: tools/OBJDIFF_GUIDE.md

Compare le binaire généré avec l'original en ligne de commande:

python tools/compare.py original/SLUS_XXX.XX build/alundra.bin

Options disponibles:

• --html : Génère un rapport HTML détaillé
• --function <addr> : Compare une fonction spécifique
• --threshold <percent> : Définit le seuil de correspondance acceptable

Génère un rapport avec:

• Pourcentage de correspondance global
• Liste des différences byte-par-byte avec adresses mémoire
• Analyse fonction par fonction
• Visualisation des sections matchées/non-matchées

Extrait les sprites, audio et cartes du binaire original:

python tools/extract.py original/SLUS_XXX.XX --output assets/

Options:

• --sprites : Extrait uniquement les sprites
• --audio : Extrait uniquement l'audio
• --maps : Extrait uniquement les cartes
• --all : Extrait tous les assets (défaut)

Analyse le binaire pour identifier les fonctions et générer des stubs:

python tools/analyze.py original/SLUS_XXX.XX --output src/stubs/

Fonctionnalités:

• Détection automatique des fonctions
• Extraction des symboles et noms de fonctions
• Génération de stubs C prêts à l'emploi
• Création d'une carte mémoire du jeu

Affiche les statistiques de décompilation:

python tools/progress.py

Génère un rapport HTML avec graphiques:

python tools/statistics.py --html

Vérifie qu'aucune fonction validée n'a régressé:

python tools/regression.py

Le projet utilise un système de tracking pour suivre l'avancement de la décompilation:

• Fonctions décompilées: X / Y (Z%)
• Correspondance binaire: W%
• Statut: En cours

Consultez PROGRESS.md pour les détails.

1. Choisir une fonction à décompiler (voir PROGRESS.md)
2. Analyser la fonction dans le binaire original
3. Écrire le code C équivalent
4. Compiler et comparer avec l'original
5. Itérer jusqu'à correspondance parfaite
6. Soumettre une Pull Request

• Suivre le style de code existant
• Commenter les sections complexes
• Tester la compilation sur Linux et Windows
• Vérifier que les fonctions déjà matchées ne régressent pas
• Mettre à jour PROGRESS.md avec vos contributions

Le projet utilise GitHub Actions pour:

• Compilation automatique sur Linux et Windows
• Comparaison avec le binaire original
• Génération de rapports de différences
• Tests de régression
• Tracking du progrès

Les workflows s'exécutent automatiquement sur chaque push et Pull Request.

• Guide de Contribution - Comment contribuer au projet
• Documentation des Outils - Guide détaillé des outils Python
• Guide objdiff - Comparaison visuelle avec objdiff
• Intégration Ghidra - Utiliser Ghidra pour l'analyse
• Suivi des Progrès - Système de tracking de progression
• Exemples - Exemples d'utilisation des outils

Ce projet est à but éducatif et de préservation. Vous devez posséder une copie légale du jeu Alundra pour utiliser ce projet. Le code décompilé est fourni pour l'étude et la recherche uniquement.

Inspiré par les excellents projets de décompilation:

• Silent Hill Decomp
• Shadow of the Colossus Decomp
• Street Fighter III Decomp

Pour toute question ou suggestion, ouvrez une issue sur GitHub.

Note: Ce projet est en développement actif. La structure et les outils peuvent évoluer.