WC4 BTL 格式与运行语义参考

状态：Publication-Ready Reference v1 / Semantic Closure Incomplete

适用项目：WC4 Reconstruction

主要语言：简体中文（zh-CN）

1. 定位

本目录是 WC4 Reconstruction 面向中文研究者、MOD 作者和工具作者维护的 BTL 正式阅读入口。

它的目标不是再制作一份经验型“偏移表”，而是把已经通过 clean-room 证据恢复的内容按统一格式组织为：

磁盘字段
-> 原版 parser / native 构造
-> clean-room raw 表示
-> runtime consumer
-> corpus / 动态行为证据
-> 当前证据状态
-> 写入门禁

本 Reference 不覆盖底层机器 authority。字段的最终证据仍由对应 canonical、原版 native 证据、语料矩阵、运行 trace、源码合同和专项报告承担；本文档负责稳定组织、中文解释和导航。

2. 语言规则

正文使用简体中文。以下内容保留原始英文或代码标识，不强行翻译：

• ArmyAIConfig、BattleExArgs 等原版或 clean-room 类型名；
• FUN_0048059C 等 native 函数标识；
• BattleMode、MapSource 等已经进入代码/证据体系的字段名；
• Confirmed、Partial、Unknown、NoGo 等机器状态值。

中文名称用于解释，不得反向替换原始标识或制造未经证据支持的新术语。

3. 证据状态

状态	中文含义	使用边界
Confirmed	已确认	当前声明已有足够直接证据支持
Partial	部分确认	已确认用途范围或部分链路，但完整语义仍开放
Unknown	未知	当前证据不足，不允许用推测填空
UnknownNoPositiveCorpus	无正样本未知	结构或 consumer 已知，但当前原版语料没有正值实例
Refuted	已否定	旧命名或旧解释已被更强证据推翻
NoGo	禁止推断/写入	当前边界明确禁止把未知行为实现成自创规则，或禁止对应写入

证据状态必须针对具体声明使用。“记录长度已确认”不代表“每一个 bit 的玩法语义已确认”。

4. 文档结构

btl-reference/
├── README.md
├── 00_introduction.md
├── 01_file_layout.md
├── evidence_methodology.md
├── records/
├── extension/
├── semantics/
├── values/
└── community/

当前规划：

• 01_file_layout.md：文件包络、固定 section 顺序、版本记录长度；
• records/：Header、Country、Building、Unit、Event、Reinforcement 等逐记录参考；
• extension/：v3+ protobuf ExtensionArea；
• semantics/：加载链、引用、版本转换和 runtime consumer；
• values/：ActionType、TriggerType、OperationType 等“值 -> 语义”速查，只收有证据的值；
• community/：社区旧文档兼容、勘误和术语映射。

5. 机器索引

机器可读的 Reference 元数据位于：

reports/btl_reference/reference_schema.json
reports/btl_reference/reference_catalog.json
reports/btl_reference/value_domains.json

机器索引只登记 Reference 结构、状态词汇和证据引用，不取代原始 canonical 数据。

6. 当前版本边界

当前核心 corpus authority 以 WC4 1.28.0 的 1358 个原版 BTL 为主要基线，并保留已恢复的 v1/v2/v3 格式差异。

任何“当前 corpus 未出现”的值都不能据此宣布为无效、padding 或永远为零。

7. 写入边界

“字段语义已确认”和“允许编辑器写入”是两件事。

Reference 必须单独记录写入状态。未经过 BTL writer 专项门禁的字段，即使读取语义已确认，也不得自动推导出安全写权限。

8. 主要现有证据入口

reports/btl_v1280_so_recovery.md
reports/btl_third_party_validation_matrix.csv
reports/btl_v3_tail_legend_recovery.md
reconstruction/docs/btl_editor_round33_file_envelope_and_header_evidence_recovery_report.md
reconstruction/docs/btl_editor_round34_header_schema_and_roundtrip_contract_report.md
reconstruction/docs/btl_editor_round37_header50_bitfield_evidence_recovery_report.md
reconstruction/docs/btl_editor_round38_unknown_compatibility_record_semantics_recovery_report.md
reconstruction/docs/btl_editor_round39_extension_descriptor_complete_schema_recovery_report.md
reconstruction/docs/btl_editor_round40_extension_native_consumer_coverage_recovery_report.md
reconstruction/src/WC4.Runtime.BattleData/

9. 当前 Reference v1 覆盖

当前已经覆盖 BTL 的全部 20/20 物理 section。主要记录均有完整 byte map 或显式 raw-preserve 区：

Header
Country
Terrain
Province / Tile Owner
Building
Unit
Mine
Behavior / ArmyAIConfig
Weather
Event
Reinforcement
Airstrike
Start Group A/B
Flag / Capital
Initial Country Strategy Override
Country Strategy Schedule
Air Support
ExtensionArea / BattleExArgs

机器覆盖状态：

reports/btl_reference/reference_coverage.json

剩余语义闭合队列：

reconstruction/docs/btl-reference/closure_backlog.md

10. HTML 阅读站

本目录同时提供 VitePress 静态 HTML 展示层。Markdown 与机器索引继续是 authority，HTML 只负责可读性、导航、搜索和分发。

npm ci
npm run docs:dev
npm run docs:build
npm run docs:check
npm run docs:preview

详细构建和分发边界见 SITE_BUILD.md，第三方展示层许可见 THIRD_PARTY_NOTICES.md。

11. 下一收敛工作

Reference v1 已不再有物理 section 文档空洞。下一阶段按 closure_backlog.md 从 P0 开始逐项消灭 Partial/Unknown，优先 Unit packed/Frontier 字段、Building bitfield 和 Event trigger/action union；每次研究闭合后同步底层 evidence、机器索引和中文 Reference。