UnBattletech

Ingeniería inversa de BattleTech: The Crescent Hawk's Inception (1988, MS-DOS; publicado por Infocom, motor de Westwood Associates) — y una recreación en Godot 4 / C# en curso del mismo.

Lee esta sección antes de confiar en cualquier otra cosa de este repositorio. El proyecto son dos esfuerzos con madurez muy distinta, y la palabra "fase" en el resto de la documentación significa código escrito, no comportamiento demostrado.

---

1. Dos entregables, construidos en paralelo

Este proyecto produce dos artefactos al mismo tiempo, y el segundo se apoya sobre el primero:

(1) La ingeniería inversa documentada. La descompilación de reko/, las especificaciones de docs/, el emulador Spice86 con herramientas MCP específicas de BattleTech, y las herramientas en Python. Este es el trabajo real de RE: formatos de archivo, texto de la historia, mapa de memoria, y gran parte de la lógica del motor están documentados y verificados cruzadamente contra la salida del descompilador y trazas en vivo del emulador. Es un entregable por derecho propio, y también es la especificación para (2).

(2) La recreación (BattleTechCHI/). Un programa en Godot 4 C# que deriva de (1): lee archivos de datos originales (.BLD, .MTP, .ANM, partidas guardadas GAME*) y reimplementa el comportamiento del motor según lo documentado por (1). Es fiel a los datos, no fiel al comportamiento, y nunca ha sido validado de extremo a extremo contra el original.

Se ejecutan en paralelo, pero la dirección de dependencia es fija:

(2) solo puede ser tan fiel como (1) sea completo y verificado. Donde (1) dice inferido o abierto, (2) es una conjetura.

Por eso la hoja de ruta pone cerrar las brechas de RE (Track 1) y la validación diferencial de (2) contra el emulador (Track 3) por delante del trabajo de características. Una recreación es tan buena como la ingeniería inversa que la sustenta.

Si buscas un port bit-exacto, aún no existe. Si buscas un entorno de RE asistido por herramientas más una reconstrucción basada en datos que se ejecuta sobre los activos originales, eso es lo que hay aquí.

---

2. Matriz de estado honesta

Leyenda: ✅ verdadero / hecho · ⚠️ parcial, aproximado, o con vacíos silenciosos · ❓ desconocido / no verificado · ❌ ausente

Sistema	Lee archivos originales en tiempo de ejecución	El comportamiento coincide con el original	Validación
Descifrado BLD + texto cifrado	✅ BldLoader.cs	✅ (texto)	✅ round-trip BLD↔JSON byte-idéntico (tools/bld)
Intérprete de opcodes BLD (28 slots 0xE4–0xFF)	✅	⚠️ parcial	❓ nunca jugado de extremo a extremo; tamaños de operando fijos (EB/EC/F6/F7); todos los slots manejados (sin descarte silencioso)
Despacho Fn1CD3 (47 casos)	✅	⚠️ parcial	❓ implementado desde la descompilación; varios casos son aproximaciones
Cabecera/teselas de mapa MTP	✅ MapLoader.cs / LocalMapView.cs	✅ (estructura)	⚠️ diseño decodificado, no comparado fotograma a fotograma
Animación ANM (RLE con delta XOR)	✅ en tiempo de ejecución, fallback PNG	⚠️	❓; el repositorio no tiene spritesheets ANM (Assets/Animations/ vacío)
Teselas ICN/CMP	❌ (preconvertidas)	—	TileManager carga BMP; Assets/Tilesets/ vacío
Archivos de guardado GAME1–6 (4096 B)	✅ parser SaveManager.cs	❓	❌ round-trip no verificado contra partidas originales
Estado de la historia (b0057, props)	✅ (lecturas)	❓ significado inferido	❓ semántica no confirmada en juego
Combate (to-hit, daño, IA, calor, munición, niebla)	— (lógica propia)	❌ aproximado	❌ RNG/fórmulas nunca comparados contra el original
Viewport / diseño de pantalla	—	⚠️ aproximado	❓ no se localizó struct de viewport canónico
Sonido / música	❌	❌	❌ formato sin decodificar
Mapeo de disparadores mapa→BLD	⚠️ parcial	❓	tabla de propiedades de tesela + traducción [0x5460]:0x4602 sin decodificar

Lo que la reconstrucción puede hacer hoy

• Arrancar la secuencia de título/inicio y las vistas de mapa local + mapa del mundo.
• Cargar y descifrar los scripts .BLD reales e interpretarlos (diálogo, menús, tiendas, muchos casos de despacho) — con vacíos silenciosos en opcodes no implementados.
• Parsear los mapas .MTP reales, y leer/escribir el diseño real de guardado de 4096 bytes.
• Ejecutar un bucle de combate táctico desde cero (RNG/LoS/to-hit/daño/IA propios).

Lo que no puede afirmar honestamente

• Que reproduce el comportamiento del original. El combate, el renderizado del viewport, y partes de la máquina de estados de la historia son reconstrucciones, no ports verificados.
• Que es visualmente autocontenido: los tilesets, animaciones y fuentes no están en el repositorio (solo 15 PNGs de mapas convertidos y 44 PNGs de sprites de mechs).

---

3. Lo que está genuinamente RE'd (y dónde)

Área	Estado	Doc canónico
Formato BLD, cifrado, opcodes	🟢 sólido	docs/formats/bld-bytecode.md
Texto de la historia (los 26 BLD)	🟢 extraído	docs/story/STORY_TEXT.txt
Mapa de memoria (100+ direcciones, segmentos)	🟢 sólido	docs/formats/memory-map.md
Mapa del mundo / mapas locales	🟢 sólido	docs/world-map.md
Modelo de combate	🟡 ~90%, algo inferido	docs/combat-system.md
Economía / tiendas / stock	🟡 flujo de UI ahora observado en vivo	docs/story/story-system.md
Formato ANM	🟢 documentado	docs/formats/anm-format.md
Abstracción de viewport	🔴 incompleto	docs/engine/viewport.md
Sonido	🔴 0%	—

---

4. Incógnitas conocidas (el RE que queda por hacer)

Estos son los bloqueadores reales; la hoja de ruta de §6 depende de ellos.

1. Combate byte-exacto. RNG, iniciativa/orden de turnos, modificadores de to-hit, tabla de localización de impactos, resolución de clusters, calor, explosión de munición, selección de objetivos de la IA — actualmente inspirados por el desensamblado, nunca comparados. (docs/combat-system.md)
2. Segmentos no descompilados. El código de combate/movimiento en los segmentos 19EF / 1000 falta en la salida de Reko; esas rutinas deben recuperarse. (docs/UNVERIFIED_DISCOVERIES.md §7)
3. Semántica del estado de la historia. b0057 (0/1/2) y los vecinos b0055/b0056/b0058 son inferidos; los IDs de propiedad 0x1C–0x23 sin mapear. (§5)
4. Mapeo de disparadores mapa→BLD. Tabla de propiedades de tesela (0x32C6) + tabla de traducción ([0x5460]:0x4602) sin decodificar; las entradas se encuentran actualmente caminando el mapa a mano (Ciudadela (34,10), ComStar (51,10) en el mapa inicial). (docs/context.md)
5. Modelo de viewport. No se encontró struct de viewport canónico; el struct de configuración del seg-0x246C está solo parcialmente mapeado; semántica de push/pop desconocida. (docs/engine/viewport.md)
6. Propiedades de tesela / colisión. Qué bits significan agua/muro; qué rutina lee 0x32C6 para movimiento. (§2)
7. Round-trip del formato de guardado. El parser existe; una carga→guardado→comparación real de GAME* no se ha hecho.
8. Economía de cadete y ciclo diario. Tick de asignación, umbral de parada, sueño en barracones, puerta de misión diaria — mecánica observada, código no localizado. (docs/story/story-system.md)
9. Vacíos de opcodes BLD. Qué opcodes ocurren realmente en los 26 archivos, y cuáles el intérprete omite silenciosamente. (rama por defecto de BldInterpreter.cs)
10. Formato de sonido/música. Completamente sin decodificar.
11. Ubicación de datos del mapa del mundo. De dónde se cargan los datos de teselas/mapa (segmento 2A02 vs otro lugar). (§1)

---

5. Arqueología retro (fuera del binario)