对 BattleTech: The Crescent Hawk's Inception(1988 年,MS-DOS;由 Infocom 发行,引擎由 Westwood Associates 开发)的逆向工程——以及一个仍在进行中的 Godot 4 / C# 复刻。
在信任本仓库中任何其他内容之前,请先阅读本节。 本项目包含两项成熟度差异极大的工作,而文档其他位置出现的“phase”一词指的是已编写的代码,而非 已验证的行为。
本项目同时产出两个产物,而第二个产物依托于第一个:
(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) 排在功能开发之前。复刻的质量取决于支撑它的逆向工程。
如果你在寻找一个位精确的移植版本,它目前尚不存在。如果你在寻找一个工具辅助的逆向工程环境,外加一个基于原始资源运行的数据驱动重建,那么这里就是。
图例:✅ 真实 / 已完成 · ⚠️ 部分、近似或存在隐性缺口 · ❓ 未知 / 未验证 · ❌ 缺失
| 系统 | 运行时读取原始文件 | 行为与原始版本匹配 | 验证 |
|---|---|---|---|
| BLD 解密 + 密文 | ✅ BldLoader.cs | ✅(文本) | ✅ 往返 BLD↔JSON 字节完全一致(tools/bld) |
| BLD 操作码解释器(28 个槽位 0xE4–0xFF) | ✅ | ⚠️ 部分 | ❓ 从未端到端运行过;操作数大小已固定(EB/EC/F6/F7 以及 ED:4 字节 idx/thresh/LE-target,匹配→跳转);所有槽位均已处理(无静默丢弃) |
Fn1CD3 分发(47 个分支) | ✅ | ⚠️ 部分 | ❓ 根据反编译实现;若干分支为近似实现;已知错误:0x23 是竞技场/房间战斗设置(1CD3:1062 → fn0FDC_0629(8)),而非新游戏初始化——如果竞技场战斗触发它,重建版的 NewGameInit 会清空当前进度;ED UnitCheckLoop 消耗 2 字节而非 4 字节,并跳过技能检查 + 跳转 |
| MTP 地图头/图块 | ✅ MapLoader.cs / LocalMapView.cs | ✅(结构) | ⚠️ 布局已解码,未逐帧比对 |
| ANM 动画(XOR-delta RLE) | ✅ 运行时,PNG 回退 | ⚠️ | ❓;仓库中没有 ANM 精灵表(Assets/Animations/ 为空) |
| ICN/CMP 图块 | ❌(已预转换) | — | TileManager 加载 BMP;Assets/Tilesets/ 为空 |
存档文件 GAME1–6(4096 B) | ✅ 解析器 SaveManager.cs | ❓ | ❌ 往返未针对原始存档验证 |
剧情状态(b0057、属性) | ✅(读取) | ❓ 含义为推断 | ❓ 语义未在游玩中确认 |
| 战斗(命中、伤害、AI、热量、弹药、战争迷雾) | —(自有逻辑) | ❌ 近似 | ❌ RNG/公式从未与原始版本比对 |
| 视口 / 屏幕布局 | — | ⚠️ 近似 | ❓ 未定位到规范视口结构体 |
| 音效 / 音乐 | ❌ | ❌ | ❌ 格式未解码 |
| 地图→BLD 触发器映射 | ✅ 已解码 | ✅([0x5460]:0x4602 + 建筑位置表 → MTP 名称列表;docs/formats/map-bld-triggers.md) | ⚠️ 入口目前仅在 MAP1 上人工验证 |
.BLD 脚本并解释执行(对话、菜单、商店、许多分发分支)——未实现的操作码存在静默缺口。.MTP 地图,并读写真实的 4096 字节存档布局。| 领域 | 状态 | 规范文档 |
|---|---|---|
| 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% | — |
这些是真正的阻塞项;§6 中的路线图以它们为前提。
docs/combat-system.md)19EF / 1000 位于 reko/gencode/(来自旧 Spice86 代码生成的 23 个文件,已排除在编译之外),另在 reko/gencode-current/ 中有一次全新重新生成;函数映射见 docs/engine/segments-19ef-1000.md。(docs/UNVERIFIED_DISCOVERIES.md §7)b0057(0/1/2)及其相邻的 b0055/b0056/b0058 已固定到代码(fn1631_11AB);D30C 数组语义已基本映射(训练/入侵、叛徒、制服、车库、录像店、小屋、竞技场标志——docs/story/story-system.md §17.5/§17.11)。属性 ID 0x1C–0x23 尚未映射。(§5)0x32C6)+ 转换表([0x5460]:0x4602)未解码docs/formats/map-bld-triggers.md);目前已在 MAP1 上人工验证入口(Citadel (34,10)、ComStar (51,10))。(docs/context.md)0x246C 的配置结构体仅
部分映射;push/pop 语义未知。(docs/engine/viewport.md)0x32C6 用于移动prop < 每场景门限 t0150;所有 0x32C6 读取点均已枚举(命中 +1、0xFF 门限、寻路扫描)——不存在按地形计算的移动消耗(MP 递减为固定步数消耗)。(§2)GAME* 加载→保存→比对。D323 门控)、财富上限停止、资产增长——机制已解码并于 2026-10-14 实机验证(docs/economy.md);费用/计时隔离 + 财务块源表仍待解决。(docs/story/story-system.md)tools/bld/opcode_coverage.py),仅 0xE7 未出现;操作数大小已修正(EB/EC/F6/F7 以及 ED)。(BldInterpreter.cs 默认分支)BTTLTECH←fn0800_4621,战斗/本地 MAP15←fn135D_055A via 1F3D:0814——docs/formats/file-formats.md);段 2A02 与别处的措辞已废弃。仅从可执行文件进行逆向工程存在局限(编译器优化后的代码、缺失的段、推断的 语义)。为了理解游戏中实际包含什么,我们交叉核对多种来源—— 它们都不能替代二进制文件,但合在一起可以厘清意图并填补空白:
docs/walkthrough/bt-walkthrough-1..3.md(导航与
事件序列)。bt_* MCP 工具提供精确的
运行时寄存器/内存状态以供比对。优先级: 对于行为,以二进制/模拟器为准;文档是意图的权威依据。
从文档或记忆中恢复的每一项主张,在进入重建之前都会标记来源并对照二进制重新验证。
完整策略(来源类别、证据标签 ✅/🟡/❓,以及来源→验证工作流)见 docs/SOURCES.md。
顺序是刻意安排的:先证明数据路径和行为,再构建更多界面。 每个关卡都是一次验证,而不是一个功能。
docs/rebuild/progress.md 和 wiki 的真实性;将每一项主张标记为
已验证 / 推断 / 未知 并注明日期。19EF/1000(战斗/移动)。reko/gencode/ + gencode-current/,映射见 docs/engine/segments-19ef-1000.md)。docs/formats/map-bld-triggers.md)。docs/economy.md);费用/计时隔离待完成。w4FBC/push-pop;完成瓦片属性位。GAME* 文件验证存档往返。WINSCENE / ENDMECH / TINYLAND。详细的逐步检查清单见 docs/rebuild/roadmap.md;阶段台账为
docs/rebuild/progress.md。
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
# 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