UnBattletech — Rétro-ingénierie de BattleTech: The Crescent Hawk's Inception (1988)

Analyse de rétro-ingénierie et reconstruction en Godot 4 + C# de BattleTech: The Crescent Hawk's Inception, le jeu MS-DOS de 1988 par Infocom.

Structure du dépôt

├── docs/               # RE documentation & findings
│   ├── CONTEXT.md      # Master context (1050+ lines)
│   ├── TECHNICAL_ANALYSIS.md  # Comprehensive technical analysis (3211 lines)
│   ├── MEMORY_MAP.md   # Full memory map (603 lines)
│   ├── ADDRESS_REFERENCE.md   # Address reference (1035 lines)
│   ├── BLD_BYTECODE.md # BLD bytecode specification (342 lines)
│   ├── WORLD_MAP_FINDINGS.md  # World map analysis (321 lines)
│   ├── REBUILD_PLAN.md # Godot rebuild plan
│   ├── REBUILD_ROADMAP.md     # Rebuild roadmap
│   └── STORY_TEXT.txt  # Extracted full story text
│
├── tools/              # Python analysis tools
│   ├── bld/            # BLD script tools (decoder, converter, viewer)
│   ├── assets/         # Asset extraction & rendering tools
│   └── analysis/       # RE analysis tools
│
├── reko/               # Reko decompiler output
│   ├── UNBTECH.exe.c   # Full C decompilation (2MB)
│   ├── UNBTECH.exe.h   # Header with struct definitions
│   ├── UNBTECH_all.asm # Combined disassembly (60K lines)
│   └── segments/       # Per-segment .c/.asm/.dis files
│
├── asm/                # Assembly analysis
│   └── discoveries.asm # Manual analysis notes
│
├── json/               # BLD → JSON conversions (26 files)
│
├── spice86/            # Spice86 emulation outputs
│
├── BattleTechCHI/      # Godot 4 + C# rebuild
│
├── original/           # Original game assets (local only, not uploaded)
│   ├── bld/  cmp/  icn/  mtp/  anm/  saves/  exe/
│
├── extracted_assets/   # Rendered PPM/PNG from game assets
└── Assets/             # Converted sprite/tile sheets

Principales réalisations de RE

• Bytecode BLD entièrement rétro-conçu : 26 opcodes, chiffrement par substitution, interpréteur à 4 couches
• Carte du monde décodée : grille de tuiles 64×64, 93 types de tuiles, système de brouillard de guerre
• Système de combat documenté : toucher sur 2D6, calcul de ligne de vue (LoS), ciblage IA, chaleur/munitions
• Histoire entièrement extraite : les 26 scripts BLD décodés avec marqueurs narratifs
• Carte mémoire complète : plus de 100 adresses cartographiées dans tous les segments

Progrès de la reconstruction Godot

La reconstruction est en Phase 6 (intégration ANM + ANM de combat). ~8 000 lignes de C# réparties dans 45+ scripts dans BattleTechCHI/Scripts/.

• ✅ Phase 0–1 : Moteur principal, modèles de données, chargeurs d'actifs, boucle de jeu, sauvegarde/chargement partielle
• ✅ Phase 2 : Rendu de tuiles, vue de la carte du monde, cartes locales, LocationMapper, brouillard de guerre
• ✅ Phase 3 : Interpréteur BLD (26 opcodes), décodeur de chiffrement, répartiteur à 47 cas (toutes les implémentations réelles), dialogue, ShopScreen
• ✅ Phase 4 : Combat — initialisation, ordre de tour, déplacement, ligne de vue, toucher (2D6), dégâts, IA, chaleur/munitions, brouillard, HUD, rencontres
• ✅ Phase 5 : AnmPlayer + ViewportManager + BldAnmMap, décompression ANM en temps réel
• ✅ Phase 6 : ANM du panneau de mech de combat (MechPortrait), ANM du curseur de carte, correction des StorySlots 16→8, correctif du lecteur A: de l'émulateur
• ⬜ Phase 7 : Tests de jeu de bout en bout, polissage (VFX, BTSTATS, son, refactorisation de w4FBC, migration TileMapLayer)

Introspection de l'émulateur et du runtime

Émulateur Spice86 avec 19 outils MCP spécifiques à BattleTech pour l'introspection de l'état du jeu en cours d'exécution :

• Lecture/écriture de l'état du jeu (tableau d'état, emplacements d'histoire, emplacements d'unités, curseur, crédits, drapeaux)
• Lecture des grilles de combat, positions des unités, brouillard de guerre
• Injecter des entrées clavier (scripter le jeu à travers les menus)
• Lire les registres CPU et la mémoire

# Start emulator with MCP server on port 8081
dotnet exec bin/Debug/net10.0/UNBATTLETECH.dll \
  --Exe "/path/to/BTECH.EXE" \
  --CDrive "/path/to/game/" \
  --HeadlessMode Minimal --McpHttpPort 8081 --NoGui

# Read game state
curl -s -X POST http://localhost:8081/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bt_get_state","arguments":{}}}'

Outils et scripts

# Convert BLD → JSON and back
python3 tools/bld/bld_json_converter.py to-json original/bld/

# Extract full story text
python3 tools/bld/extract_story.py

# Decode all BLD files with opcode analysis
python3 tools/bld/decode_bld.py

# ASCII terminal viewer for maps
python3 tools/bld/ascii_viewer.py

# Render CMP assets to PPM
python3 tools/assets/extract_assets.py

# Build C# rebuild
cd BattleTechCHI && dotnet build

# Build emulator
dotnet build UNBATTLETECH.csproj

Avertissement

Ce dépôt ne contient aucun actif de jeu original (BLD, CMP, EXE, etc.). Seules l'analyse de rétro-ingénierie, la documentation et le code source original pour une reconstruction en chambre blanche sont inclus. Les actifs de jeu originaux restent dans original/ pour le développement local uniquement (gitignorés).