UnBattletech — Reverse Engineering di BattleTech: The Crescent Hawk's Inception (1988)

Analisi di reverse engineering e ricostruzione in Godot 4 + C# di BattleTech: The Crescent Hawk's Inception, il gioco MS-DOS del 1988 di Infocom.

Struttura del repository

├── 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

Risultati principali del reverse engineering

• Bytecode BLD completamente reverse-engineered: 26 opcode, cifrario di sostituzione, interprete a 4 livelli
• Mappa del mondo decodificata: griglia di 64×64 tile, 93 tipi di tile, sistema di nebbia di guerra
• Sistema di combattimento documentato: tiro per colpire 2D6, ray-casting della linea di vista (LoS), targeting dell'IA, calore/munizioni
• Storia completamente estratta: tutti i 26 script BLD decodificati con marcatori narrativi
• Mappa di memoria completa: oltre 100 indirizzi mappati in tutti i segmenti

Avanzamento della ricostruzione in Godot

La ricostruzione è in Fase 6 (integrazione ANM + ANM del combattimento). ~8.000 righe di C# in oltre 45 script in BattleTechCHI/Scripts/.

• ✅ Fase 0–1: motore principale, modelli dati, loader di asset, ciclo di gioco, salvataggio/caricamento parziale
• ✅ Fase 2: rendering delle tile, viewport della mappa del mondo, mappe locali, LocationMapper, nebbia di guerra
• ✅ Fase 3: interprete BLD (26 opcode), decodificatore del cifrario, dispatcher a 47 casi (tutte le implementazioni reali), dialoghi, ShopScreen
• ✅ Fase 4: combattimento — inizializzazione, ordine di turno, movimento, LoS, tiro per colpire (2D6), danni, IA, calore/munizioni, nebbia, HUD, incontri
• ✅ Fase 5: AnmPlayer + ViewportManager + BldAnmMap, decompressione ANM a runtime
• ✅ Fase 6: ANM del pannello mech in combattimento (MechPortrait), ANM del cursore della mappa, fix StorySlots 16→8, fix emulatore unità A:
• ⬜ Fase 7: playtesting end-to-end, polish (VFX, BTSTATS, suono, refactor di w4FBC, migrazione a TileMapLayer)

Emulatore e introspezione a runtime

Emulatore Spice86 con 19 strumenti MCP specifici per BattleTech per l'introspezione a runtime dello stato di gioco:

• Lettura/scrittura dello stato di gioco (array di stato, slot della storia, slot delle unità, cursore, crediti, flag)
• Lettura delle griglie di combattimento, posizioni delle unità, nebbia di guerra
• Iniezione di input da tastiera (scriptare il gioco attraverso i menu)
• Lettura dei registri della CPU e della memoria

# 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":{}}}'

Strumenti e script

# 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

Disclaimer

Questo repository non contiene asset originali del gioco (BLD, CMP, EXE, ecc.). Sono inclusi solo analisi di reverse engineering, documentazione e codice sorgente originale per una ricostruzione clean-room. Gli asset originali del gioco rimangono in original/ solo per lo sviluppo locale (esclusi tramite gitignore).