UnBattletech — Ingeniería inversa de BattleTech: The Crescent Hawk's Inception (1988)

Análisis de ingeniería inversa y reconstrucción en Godot 4 + C# de BattleTech: The Crescent Hawk's Inception, el juego MS-DOS de 1988 de Infocom.

Estructura del repositorio

├── docs/               # Documentación y hallazgos de RE
│   ├── CONTEXT.md      # Contexto principal (1050+ líneas)
│   ├── TECHNICAL_ANALYSIS.md  # Análisis técnico exhaustivo (3211 líneas)
│   ├── MEMORY_MAP.md   # Mapa de memoria completo (603 líneas)
│   ├── ADDRESS_REFERENCE.md   # Referencia de direcciones (1035 líneas)
│   ├── BLD_BYTECODE.md # Especificación del bytecode BLD (342 líneas)
│   ├── WORLD_MAP_FINDINGS.md  # Análisis del mapa del mundo (321 líneas)
│   ├── REBUILD_PLAN.md # Plan de reconstrucción en Godot
│   ├── REBUILD_ROADMAP.md     # Hoja de ruta de reconstrucción
│   └── STORY_TEXT.txt  # Texto completo de la historia extraído
│
├── tools/              # Herramientas de análisis en Python
│   ├── bld/            # Herramientas de scripts BLD (decodificador, conversor, visor)
│   ├── assets/         # Herramientas de extracción y renderizado de activos
│   └── analysis/       # Herramientas de análisis RE
│
├── reko/               # Salida del descompilador Reko
│   ├── UNBTECH.exe.c   # Descompilación C completa (2MB)
│   ├── UNBTECH.exe.h   # Cabecera con definiciones de estructuras
│   ├── UNBTECH_all.asm # Desensamblado combinado (60K líneas)
│   └── segments/       # Archivos .c/.asm/.dis por segmento
│
├── asm/                # Análisis de ensamblador
│   └── discoveries.asm # Notas de análisis manual
│
├── json/               # Conversiones BLD → JSON (26 archivos)
│
├── spice86/            # Salidas de emulación Spice86
│
├── BattleTechCHI/      # Reconstrucción en Godot 4 + C#
│
├── original/           # Activos originales del juego (solo local, no subidos)
│   ├── bld/  cmp/  icn/  mtp/  anm/  saves/  exe/
│
├── extracted_assets/   # PPM/PNG renderizados a partir de activos del juego
└── Assets/             # Hojas de sprites/tiles convertidas

Logros clave de RE

Bytecode BLD completamente ingeniado en reversa: 26 opcodes, cifrado de sustitución, intérprete de 4 capas
Mapa del mundo decodificado: cuadrícula 64×64, 93 tipos de tiles, sistema de niebla de guerra
Sistema de combate documentado: 2D6 para impactar, trazado de rayos LoS, apuntado de IA, calor/municiones
Historia completamente extraída: los 26 scripts BLD decodificados con marcadores narrativos
Mapa de memoria completo: más de 100 direcciones mapeadas en todos los segmentos

Progreso de la reconstrucción en Godot

La reconstrucción está en Fase 6 (integración ANM + ANM de combate). ~8.000 líneas de C# en más de 45 scripts en BattleTechCHI/Scripts/.

✅ Fase 0–1: Motor central, modelos de datos, cargadores de activos, bucle de juego, guardar/cargar parcial
✅ Fase 2: Renderizado de tiles, viewport del mapa mundial, mapas locales, LocationMapper, niebla de guerra
✅ Fase 3: Intérprete BLD (26 opcodes), descifrador de cifrados, despachador de 47 casos (todas las implementaciones reales), diálogo, ShopScreen
✅ Fase 4: Combate — inicio, orden de turnos, movimiento, LoS, impacto (2D6), daño, IA, calor/municiones, niebla, HUD, encuentros
✅ Fase 5: AnmPlayer + ViewportManager + BldAnmMap, descompresión ANM en tiempo de ejecución
✅ Fase 6: ANM de panel de mecha de combate (MechPortrait), ANM de cursor de mapa, corrección de StorySlots 16→8, corrección de unidad A: del emulador
⬜ Fase 7: Pruebas de juego integrales, pulido (VFX, BTSTATS, sonido, refactorización de w4FBC, migración a TileMapLayer)

Emulador e introspección en tiempo de ejecución

Emulador Spice86 con 19 herramientas MCP específicas de BattleTech para introspección del estado del juego en tiempo de ejecución:

Leer/escribir estado del juego (array de estado, slots de historia, slots de unidades, cursor, créditos, banderas)
Leer cuadrículas de combate, posiciones de unidades, niebla de guerra
Inyectar entrada de teclado (scriptear el juego a través de menús)
Leer registros de CPU y memoria

# Iniciar emulador con servidor MCP en el puerto 8081
dotnet exec bin/Debug/net10.0/UNBATTLETECH.dll \
  --Exe "/ruta/a/BTECH.EXE" \
  --CDrive "/ruta/al/juego/" \
  --HeadlessMode Minimal --McpHttpPort 8081 --NoGui

# Leer estado del juego
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":{}}}'

Herramientas y scripts

# Convertir BLD ↔ JSON
python3 tools/bld/bld_json_converter.py to-json original/bld/

# Extraer texto completo de la historia
python3 tools/bld/extract_story.py

# Decodificar todos los archivos BLD con análisis de opcodes
python3 tools/bld/decode_bld.py

# Visor ASCII en terminal para mapas
python3 tools/bld/ascii_viewer.py

# Renderizar activos CMP a PPM
python3 tools/assets/extract_assets.py

# Compilar la reconstrucción C#
cd BattleTechCHI && dotnet build

# Compilar el emulador
dotnet build UNBATTLETECH.csproj

Aviso legal

Este repositorio no contiene activos originales del juego (BLD, CMP, EXE, etc.). Solo se incluyen análisis de ingeniería inversa, documentación y código fuente original para una reconstrucción en entorno aislado. Los activos originales del juego permanecen en original/ solo para desarrollo local (gitignored).

UnBattletech

Más Populares