BTL Reference 使用说明

1. 读者

本文档主要面向：

• WC4 BTL MOD 作者；
• BTL 查看器、编辑器和转换工具作者；
• 需要核对原版 BTL 字段的研究者；
• WC4 Reconstruction 后续 clean-room 工作单元。

如果只需要修改某个字段，应优先阅读对应 records/*.md；如果需要理解字段为什么这样命名，应继续查看条目引用的 native/corpus/runtime 证据。

2. Offset 记法

所有记录内 offset 默认使用十六进制，并相对于该记录起点：

Unit +0x22
Building +0x14
Header +0x58

文件绝对 offset 只在描述 section layout 或具体样本时使用。

3. 数值类型

Reference 必须尽量区分：

• uint8 / int8；
• uint16 / int16 little-endian；
• uint32 / int32 little-endian；
• packed byte / bitfield；
• protobuf varint / length-delimited；
• 原始字节序列。

如果原版只按位读取而没有足够证据支持整体 scalar 语义，应写成 packed/bitfield，而不是人为赋予一个整数字段名。

4. 字段条目模板

单个字段默认使用以下信息：

项目	说明
Offset	记录内偏移
Size	物理字节长度
Raw type	原始读取类型
中文语义	当前允许公开的中文解释
原始/代码标识	native、descriptor 或 clean-room 名称
Versions	适用 BTL 版本
Physical status	物理布局证据状态
Semantic status	完整语义证据状态
Consumer status	runtime consumer 恢复程度
Corpus status	原版语料覆盖情况
Write status	当前写入门禁
Evidence	canonical/report/code 路径
Community note	社区旧称、兼容名或勘误

只有存在证据时才填具体结论。缺项不能用“通常”“应该”“大概”补齐。

5. 字段与运行时状态的区别

BTL 是战局初始/脚本数据输入，不等于完整 BattleState。

因此以下情况必须明确区分：

BTL serialized input
runtime copied state
runtime-derived state
runtime-only state
presentation-only state

某个 runtime offset 与 BTL offset 数值相近，不构成字段等价证据。

6. 版本差异

当前已恢复的主要版本差异包括：

• Unit：v1 为 0x30，v2/v3 为 0x40；
• Reinforcement：v1 为 0x50，v2/v3 为 0x68；
• v3+ 可以在固定 section 后携带 H54 字节的 protobuf ExtensionArea；
• 老格式记录会由原版 loader 转换到较新的 common runtime representation。

Reference 不把“common runtime representation”误写成旧版磁盘记录本身。

7. 社区资料的使用方式

社区 TXT、XLSM、编辑器标签和修改经验属于线索来源，不直接获得 Confirmed 身份。

处理流程为：

社区说法
-> 定位原始字段
-> native parser/consumer 核对
-> 原版 corpus 核对
-> 必要时 runtime trace/probe
-> Confirmed / Partial / Refuted / Unknown

社区旧称如果已被广泛使用，可以作为兼容搜索词保留，但必须与当前结论分开显示。

8. “未知”是正式结果

Unknown 和 NoGo 不是文档缺陷，而是 clean-room 边界的一部分。

尤其禁止：

• 因为一个字段在 1358 个当前 BTL 中全为零就称其为 padding；
• 因为某个 bit 改动后画面变化就直接命名为“皮肤 ID”；
• 因为社区编辑器给出了标签就把标签当原版语义；
• 因为写入后游戏没有立即崩溃就宣布 writer 安全。