UnBattletech

对 BattleTech: The Crescent Hawk's Inception（1988 年，MS-DOS；由 Infocom 发行，引擎由 Westwood Associates 开发）的逆向工程——以及一个进行中的 Godot 4 / C# 复刻项目。

在信任本仓库中的任何其他内容之前，请先阅读本节。 本项目包含两项成熟度差异极大的工作，文档中其他地方出现的“阶段”一词指的是代码已编写，而非 行为已验证。

---

1. 两个并行构建的交付物

本项目同时产出两个工件，且第二个建立在第一个之上：

（1）有文档记录的逆向工程。 reko/ 反编译输出、docs/ 规范、带有 BattleTech 专用 MCP 工具的 Spice86 模拟器，以及 Python 工具链。这是真正的逆向工程工作：文件格式、剧情文本、内存映射以及大部分引擎逻辑均已记录，并与反编译器输出和实时模拟器跟踪进行交叉验证。它本身就是一个独立的交付物，同时也是（2）的规范。

（2）复刻项目（BattleTechCHI/）。 一个 Godot 4 C# 程序，派生自（1）：它读取原始数据文件（.BLD、.MTP、.ANM、GAME* 存档），并按照（1）所记录的内容重新实现引擎行为。它忠实于数据，而非忠实于行为，并且从未针对原版进行过端到端验证。

两者并行运行，但依赖方向是固定的：

（2）的忠实度只能达到（1）的完整与验证程度。 凡是（1）标注为推断或未决之处，（2）都只是猜测。

这就是为什么路线图将填补逆向工程空白（Track 1）以及**（2）针对模拟器的差分验证（Track 3）**置于功能开发之前。复刻的质量取决于支撑它的逆向工程。

如果你在寻找一个逐位精确的移植版本，它尚不存在。如果你在寻找一个工具辅助的逆向工程环境，外加一个基于原始资源运行的数据驱动重建，那么这里就是。

---

2. 诚实的现状矩阵

图例：✅ 真实 / 已完成 · ⚠️ 部分、近似或存在隐性缺口 · ❓ 未知 / 未验证 · ❌ 缺失

系统	运行时读取原始文件	行为与原版一致	验证
BLD 解密 + 密文	✅ BldLoader.cs	✅（文本）	✅ BLD↔JSON 往返字节一致（tools/bld）
BLD 操作码解释器（28 个槽位 0xE4–0xFF）	✅	⚠️ 部分	❓ 从未端到端游玩；操作数大小固定（EB/EC/F6/F7）；所有槽位均已处理（无静默丢弃）
Fn1CD3 分发（47 个分支）	✅	⚠️ 部分	❓ 依据反编译实现；若干分支为近似
MTP 地图头/图块	✅ MapLoader.cs / LocalMapView.cs	✅（结构）	⚠️ 布局已解码，未逐帧比对
ANM 动画（XOR 差分 RLE）	✅ 运行时，PNG 回退	⚠️	❓；仓库中没有 ANM 精灵表（Assets/Animations/ 为空）
ICN/CMP 图块	❌（预转换）	—	TileManager 加载 BMP；Assets/Tilesets/ 为空
存档文件 GAME1–6（4096 B）	✅ 解析器 SaveManager.cs	❓	❌ 往返未针对原始存档验证
剧情状态（b0057、属性）	✅（读取）	❓ 含义为推断	❓ 语义未在游玩中确认
战斗（命中、伤害、AI、热量、弹药、战争迷雾）	—（自有逻辑）	❌ 近似	❌ RNG/公式从未与原版比对
视口 / 屏幕布局	—	⚠️ 近似	❓ 未定位到规范视口结构体
音效 / 音乐	❌	❌	❌ 格式未解码
地图→BLD 触发器映射	⚠️ 部分	❓	图块属性表 + [0x5460]:0x4602 转换未解码

重建版目前能做什么

• 启动标题/开场序列以及本地地图 + 世界地图视图。
• 加载并解密真实的 .BLD 脚本并解释执行（对话、菜单、商店、许多分发分支）——未实现的操作码存在静默缺口。
• 解析真实的 .MTP 地图，并读写真实的 4096 字节存档布局。
• 运行一个从零编写的战术战斗循环（自有 RNG/视线/命中/伤害/AI）。

它无法诚实声称的内容

• 它复现了原版的行为。战斗、视口渲染以及部分剧情状态机是重建，而非经过验证的移植。
• 它在视觉上是自包含的：仓库中不包含图块集、动画和字体（仅有 15 张转换后的地图 PNG 和 44 张机甲精灵 PNG）。

---

3. 真正完成逆向工程的部分（及其位置）

领域	状态	规范文档
BLD 格式、密码、操作码	🟢 可靠	docs/formats/bld-bytecode.md
剧情文本（全部 26 个 BLD）	🟢 已提取	docs/story/STORY_TEXT.txt
内存映射（100+ 地址、段）	🟢 可靠	docs/formats/memory-map.md
世界地图 / 本地地图	🟢 可靠	docs/world-map.md
战斗模型	🟡 ~90%，部分为推断	docs/combat-system.md
经济 / 商店 / 库存	🟡 UI 流程现已实时观察	docs/story/story-system.md
ANM 格式	🟢 已记录	docs/formats/anm-format.md
视口抽象	🔴 不完整	docs/engine/viewport.md
音效	🔴 0%	—

---

4. 已知未知（尚待完成的逆向工程）

这些是真正的阻塞项；§6 中的路线图以它们为门槛。

1. 字节精确的战斗。 RNG、先攻/回合顺序、命中修正、命中部位表、集束结算、热量、弹药爆炸、AI 目标选择——目前受反汇编启发，从未比对。（docs/combat-system.md）
2. 未反编译的段。 段 19EF / 1000 中的战斗/移动代码在 Reko 输出中缺失；这些例程必须被恢复。（docs/UNVERIFIED_DISCOVERIES.md §7）
3. 剧情状态语义。 b0057（0/1/2）及相邻的 b0055/b0056/b0058 为推断；属性 ID 0x1C–0x23 未映射。（§5）
4. 地图→BLD 触发器映射。 图块属性表（0x32C6）+ 转换表（[0x5460]:0x4602）未解码；入口目前通过手动遍历地图找到（起始地图上的 Citadel (34,10)、ComStar (51,10)）。（docs/context.md）
5. 视口模型。 未找到规范视口结构体；段 0x246C 配置结构体仅部分映射；push/pop 语义未知。（docs/engine/viewport.md）
6. 图块属性 / 碰撞。 哪些位表示水/墙；哪个例程为移动读取 0x32C6。（§2）
7. 存档格式往返。 解析器已存在；尚未进行真实的 GAME* 加载→保存→比较。
8. 学员经济与昼夜循环。 津贴计时、停止阈值、营房睡眠、每日任务门槛——机制已观察，代码未定位。（docs/story/story-system.md）
9. BLD 操作码缺口。 26 个文件中实际出现哪些操作码，以及解释器静默跳过哪些。（BldInterpreter.cs 默认分支）
10. 音效/音乐格式。 完全未解码。
11. 世界地图数据位置。 图块/地图数据从何处加载（段 2A02 还是其他地方）。（§1）

---

5. 复古考古（二进制之外）

仅从可执行文件进行逆向工程有其局限（编译器优化代码、缺失的段、推断的语义）。为了理解游戏中实际有什么，我们交叉核对几种来源——它们都无法替代二进制文件，但合在一起可以厘清意图并填补空白：

• 原始文档——手册、线索/提示书以及 1988–89 年的杂志评测（设计意图、术语、预期 UI）。尚未获取——一项考古任务。
• 个人游玩测试——作者自己的游玩过程：玩家实际观察到什么，也是生成假设并在模拟器中验证的最佳来源。
• 已发布的攻略——已使用：docs/walkthrough/bt-walkthrough-1..3.md（导航与事件序列）。
• Westwood 同门引擎作品——Mines of Titan（1989，x86，已指纹识别：图形/文本方面有 25 个共享函数）以及后来的视口引擎（Eye of the Beholder、Kyrandia、Lands of Lore）用于视口模型。
• 其他 BattleTech CHI 移植/发行版——C64 / Apple II / Amiga（如有）以及后来的“Gold”版本；不同的编译器暴露不同的结构。
• 作为基准真相的模拟器工具——Spice86 跟踪 + 23 个 bt_* MCP 工具提供精确的运行时寄存器/内存状态以供比对。

优先级： 对于行为，二进制/模拟器优先；文档对意图具有权威性。每一条从文档或记忆中恢复的声明，在进入复刻项目之前，都会标注来源并针对二进制重新验证。完整策略（来源类别、证据标签 ✅/🟡/❓ 以及来源→验证工作流）见 docs/SOURCES.md。

---

6. 真正的路线图（从这里到忠实的 Godot 复刻）

顺序是刻意安排的：在构建更多界面之前，先证明数据路径和行为。 每个门槛都是一次验证，而非一个功能。

Track 0 — 真相维护（持续进行）

• 保持本 README、docs/rebuild/progress.md 和 wiki 诚实；将每条声明标注为已验证 / 推断 / 未知并注明日期。
• 没有验证工件（跟踪、差异或字节比较），不得新增“✅”。

Track 1 — 填补逆向工程谜团（§4，按优先级排序）

1. 反编译/注释段 19EF/1000（战斗/移动）。← 解除对 2 的阻塞
2. 将战斗公式/RNG 与模拟器跟踪进行比对（字节精确表）。← 解除对 Track 3 的阻塞
3. 解码地图→BLD 触发表，使入口由数据驱动，而非手动查找。
4. 定位学员经济 / 昼夜循环代码。
5. 解决视口结构体 + w4FBC/push-pop；完成图块属性位。
6. 针对真实 GAME* 文件验证存档往返。

Track 2 — 使数据路径忠实

• TileManager 应在运行时解码 ICN/CMP（无需预烘焙 BMP）；提交或重新生成图块集/动画/字体，或记录确切的提取步骤。
• ANM：消除对 PNG 回退的依赖；运行时解码器是唯一真相来源。
• 枚举并实现实际出现的每一个 BLD 操作码；遇到未知操作码时大声失败。

Track 3 — 差分验证（缺失的拱心石）

• 构建一个测试框架，将相同的脚本化输入分别通过（a）Spice86 模拟器和（b）Godot 重建版运行，然后比较：状态数组、剧情槽位、信用点、光标、单位槽位、战斗网格以及渲染帧。
• 首批目标：一个完整的训练日（任务 → 睡眠）、一次商店交易、一场战斗遭遇。
• 只有当某个系统的场景差异为空时，该系统才算“完成”。

Track 4 — 功能完成（每个领域仅在 Track 3 之后）

• 股票市场 UI（分发器 0x2A/0x2B 已存在；UI 待定）。
• 科技/BTSTATS 界面、完整装备管理。
• 终局：WINSCENE / ENDMECH / TINYLAND。
• 音效，如果 Track 1 解码了格式。

Track 5 — 复古考古（并行，为 Track 1 提供输入）

• 手册 / 线索书 / 杂志扫描件；同门游戏函数映射扩展。

详细的逐步清单见 docs/rebuild/roadmap.md；阶段台账为 docs/rebuild/progress.md。

---

7. 仓库布局

docs/                 RE documentation (canonical doc per topic: docs/INDEX.md)
reko/                 Reko decompiler output (C + asm, per segment)
tools/
  bld/                BLD decode / JSON round-trip / story extraction
  assets/             Asset extraction & rendering
  analysis/           Binary & memory-dump analysis
  playtest/           bt.py — drive the emulator via MCP + memory API
BattleTechCHI/        Godot 4 + C# recreation (~4.9k lines, ~45 scripts)
  Scripts/{Core,Data,Maps,BLD,Combat,UI}
  Assets/             15 map PNGs, 44 mech sprites, 9 screens (tilesets/ANM/fonts EMPTY)
original/             Original game files (local only, gitignored)
BattleTechMcpTools/   Spice86 override supplier + 23 bt_* MCP tools

---

8. 运行各部分

# Emulator + MCP (ground truth for traces)
fuser -k 20000/tcp 8086/tcp 2>/dev/null
: > /tmp/emu.log
dotnet exec bin/Debug/net10.0/UNBATTLETECH.dll \
  --Exe "/path/to/UNBTECH.exe" --CDrive "/path/to/game/" \
  --HeadlessMode Minimal --McpHttpPort 8086 --NoGui

# Playtest harness
python3 tools/playtest/bt.py state      # mode/cursor/credits/flags snapshot
python3 tools/playtest/bt.py png out.png # true-colour screenshot

# Godot rebuild (needs a display; use xvfb-run headless)
cd BattleTechCHI && dotnet build && bash run.sh

# BLD round-trip / story extraction
python3 tools/bld/bld_json_converter.py to-json original/bld/
python3 tools/bld/extract_story.py

---

9. 免责声明

本仓库不包含任何原始游戏资源（EXE、BLD、CMP、ICN、MTP、ANM、存档）。仅包含逆向工程分析、文档以及用于净室重建的原创源代码。BattleTechCHI/Assets/ 下的 69 张 PNG 是用于本地开发的转换渲染图。原始资源保留在 original/（已 gitignore）中，运行加载器需要它们。