UnBattletech

Reverse Engineering von BattleTech: The Crescent Hawk's Inception (1988, MS-DOS; veröffentlicht von Infocom, Engine von Westwood Associates) — und eine in Arbeit befindliche Godot 4 / C#-Neuerstellung davon.

Lies diesen Abschnitt, bevor du irgendetwas anderem in diesem Repo vertraust. Das Projekt besteht aus zwei Bestrebungen mit sehr unterschiedlicher Reife, und das Wort „Phase" anderswo in den Docs bedeutet Code geschrieben, nicht Verhalten bewiesen.

---

1. Zwei Ergebnisse, parallel erstellt

Dieses Projekt erzeugt zwei Artefakte gleichzeitig, und das zweite setzt auf dem ersten auf:

(1) Das dokumentierte Reverse Engineering. Die reko/-Dekompilierung, docs/-Spezifikationen, der Spice86-Emulator mit BattleTech-spezifischen MCP-Tools und die Python-Tooling. Dies ist die eigentliche RE-Arbeit: Dateiformate, Story-Text, Speicherkarte und ein großer Teil der Engine-Logik sind dokumentiert und gegen Dekompiler-Ausgabe und Live-Emulator-Traces gegengeprüft. Es ist ein Ergebnis für sich genommen, und es ist auch die Spezifikation für (2).

(2) Die Neuerstellung (BattleTechCHI/). Ein Godot 4 C#-Programm, das von (1) abgeleitet ist: Es liest Originaldatendateien (.BLD, .MTP, .ANM, GAME*-Spielstände) und reimplementiert das Engine-Verhalten wie von (1) dokumentiert. Es ist datentreu, nicht verhaltenstreu, und wurde niemals Ende-zu-Ende gegen das Original validiert.

Sie laufen parallel, aber die Abhängigkeitsrichtung ist festgelegt:

(2) kann nur so treu sein, wie (1) vollständig und verifiziert ist. Wo (1) abgeleitet oder offen sagt, ist (2) eine Vermutung.

Deshalb setzt die Roadmap das Schließen der RE-Lücken (Track 1) und die differentielle Validierung von (2) gegen den Emulator (Track 3) vor die Feature-Arbeit. Eine Neuerstellung ist nur so gut wie das Reverse Engineering, das sie trägt.

Wenn du einen bit-exakten Port suchst, existiert er noch nicht. Wenn du eine tool-gestützte RE-Umgebung plus eine datengetriebene Rekonstruktion suchst, die auf Original-Assets läuft, dann ist das hier.

---

2. Ehrliche Statusmatrix

Legende: ✅ wahr / erledigt · ⚠️ teilweise, ungefähr oder mit stillen Lücken · ❓ unbekannt / unverifiziert · ❌ fehlend

System	Liest Originaldateien zur Laufzeit	Verhalten entspricht dem Original	Validierung
BLD-Entschlüsselung + Cipher-Text	✅ BldLoader.cs	✅ (Text)	✅ Round-Trip BLD↔JSON byte-identisch (tools/bld)
BLD-Opcode-Interpreter (28 Slots 0xE4–0xFF)	✅	⚠️ teilweise	❓ nie Ende-zu-Ende gespielt; Operandengrößen fest (EB/EC/F6/F7); alle Slots behandelt (kein stilles Verwerfen)
Fn1CD3-Dispatch (47 Fälle)	✅	⚠️ teilweise	❓ aus Dekompilat implementiert; mehrere Fälle sind Annäherungen
MTP-Kartenheader/Tiles	✅ MapLoader.cs / LocalMapView.cs	✅ (Struktur)	⚠️ Layout dekodiert, nicht Frame-für-Frame gediffed
ANM-Animation (XOR-Delta-RLE)	✅ Laufzeit, PNG-Fallback	⚠️	❓; Repo enthält keine ANM-Spritesheets (Assets/Animations/ leer)
ICN/CMP-Tiles	❌ (vorkonvertiert)	—	TileManager lädt BMP; Assets/Tilesets/ leer
Speicherdateien GAME1–6 (4096 B)	✅ Parser SaveManager.cs	❓	❌ Round-Trip nicht gegen Original-Spielstände verifiziert
Story-Zustand (b0057, Props)	✅ (liest)	❓ Bedeutung abgeleitet	❓ Semantik nicht im Spiel bestätigt
Kampf (Trefferwurf, Schaden, KI, Hitze, Munition, Fog)	— (eigene Logik)	❌ ungefähr	❌ RNG/Formeln nie gegen das Original gediffed
Viewport / Bildschirmlayout	—	⚠️ ungefähr	❓ keine kanonische Viewport-Struktur gefunden
Sound / Musik	❌	❌	❌ Format undekodiert
Map→BLD-Trigger-Zuordnung	⚠️ teilweise	❓	Tile-Property-Tabelle + [0x5460]:0x4602-Übersetzung nicht dekodiert

Was der Rebuild heute kann

• Die Titel-/Startsequenz und die Local-Map- + World-Map-Ansichten booten.
• Die echten .BLD-Skripte laden und entschlüsseln und interpretieren (Dialoge, Menüs, Shops, viele Dispatch- Fälle) — mit stillen Lücken bei nicht implementierten Opcodes.
• Die echten .MTP-Karten parsen und das echte 4096-Byte-Speicherlayout lesen/schreiben.
• Eine von Grund auf neu gebaute taktische Kampfschleife ausführen (eigener RNG/LoS/Trefferwurf/Schaden/KI).

Was er nicht ehrlich behaupten kann

• Dass er das Verhalten des Originals reproduziert. Kampf, Viewport-Rendering und Teile der Story- Zustandsmaschine sind Rekonstruktionen, keine verifizierten Ports.
• Dass er visuell eigenständig ist: Tilesets, Animationen und Fonts sind nicht im Repo (nur 15 konvertierte Karten-PNGs und 44 Mech-Sprite-PNGs sind enthalten).

---

3. Was tatsächlich RE'd ist (und wo)

Bereich	Zustand	Kanonisches Dokument
BLD-Format, Cipher, Opcodes	🟢 solide	docs/formats/bld-bytecode.md
Story-Text (alle 26 BLD)	🟢 extrahiert	docs/story/STORY_TEXT.txt
Speicherkarte (100+ Adressen, Segmente)	🟢 solide	docs/formats/memory-map.md
Weltkarte / lokale Karten	🟢 solide	docs/world-map.md
Kampfmodell	🟡 ~90%, teils abgeleitet	docs/combat-system.md
Wirtschaft / Shops / Bestand	🟡 UI-Flow jetzt live beobachtet	docs/story/story-system.md
ANM-Format	🟢 dokumentiert	docs/formats/anm-format.md
Viewport-Abstraktion	🔴 unvollständig	docs/engine/viewport.md
Sound	🔴 0%	—

---

4. Bekannte Unbekannte (das noch zu erledigende RE)

Dies sind die echten Blocker; die Roadmap in §6 ist an sie gekoppelt.

1. Byte-exakter Kampf. RNG, Initiative/Zugreihenfolge, Trefferwurf-Modifikatoren, Trefferort-Tabelle, Cluster- Auflösung, Hitze, Munitionsexplosion, KI-Zielauswahl — derzeit inspiriert von der Disassembly, nie gediffed. (docs/combat-system.md)
2. Nicht dekompilierte Segmente. Kampf-/Bewegungscode in den Segmenten 19EF / 1000 fehlt in der Reko-Ausgabe; diese Routinen müssen wiederhergestellt werden. (docs/UNVERIFIED_DISCOVERIES.md §7)
3. Story-Zustands-Semantik. b0057 (0/1/2) und Nachbarn b0055/b0056/b0058 sind abgeleitet; Property-IDs 0x1C–0x23 nicht zugeordnet. (§5)
4. Map→BLD-Trigger-Zuordnung. Tile-Property-Tabelle (0x32C6) + Übersetzungstabelle ([0x5460]:0x4602) nicht dekodiert; Eingänge werden derzeit durch manuelles Ablaufen der Karte gefunden (Citadel (34,10), ComStar (51,10) auf der Startkarte). (docs/context.md)
5. Viewport-Modell. Keine kanonische Viewport-Struktur gefunden; die Seg-0x246C-Konfigurationsstruktur ist nur teilweise zugeordnet; Push/Pop-Semantik unbekannt. (docs/engine/viewport.md)
6. Tile-Properties / Kollision. Welche Bits Wasser/Wand bedeuten; welche Routine 0x32C6 für Bewegung liest. (§2)
7. Save-Format-Round-Trip. Parser existiert; ein echtes GAME*-Laden→Speichern→Vergleichen wurde nicht durchgeführt.
8. Kadetten-Wirtschaft & Tageszyklus. Allowance-Tick, Stop-Schwelle, Barracken-Schlaf, Daily-Mission-Gate — Mechanik beobachtet, Code nicht lokalisiert. (docs/story/story-system.md)
9. BLD-Opcode-Lücken. Welche Opcodes tatsächlich über die 26 Dateien hinweg vorkommen und welche der Interpreter still überspringt. (BldInterpreter.cs Default-Zweig)
10. Sound-/Musikformat. Vollständig undekodiert.
11. Position der Weltkartendaten. Woher Tile-/Kartendaten geladen werden (Segment 2A02 vs. anderswo). (§1)

---

5. Retro-Archäologie (außerhalb der Binärdatei)

RE allein aus der ausführbaren Datei hat Grenzen (compiler-optimierter Code, fehlende Segmente, abgeleitete Semantik). Um zu verstehen, was tatsächlich im Spiel ist, prüfen wir mehrere Quellenarten gegen — keine kann die Binärdatei ersetzen, aber zusammen klären sie die Absicht und füllen Lücken: