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. 当前版本边界

当前最新审计主基线为 Android WC4 1.30.0：1383 个原版 BTL，正式物理布局合同对 1383/1383 文件均可精确切分到 EOF。1.30 仍只观察到 v1/v2/v3，固定 section 顺序、Unit/Reinforcement 记录长度和 v3 H54 + ExtensionArea 机制均未变化；1.29.0 / 1359 与 1.28.0 / 1358 继续作为历史差异和既有专项语义证据保留。

Reference 采用“最新版优先、版本证据显式标注”的规则：物理统计、Extension wire、Unit +0x2F 精英皮肤索引、Event raw/value corpus、Behavior、Country、Reinforcement 与主要固定记录总量都已按 1.30.0 重扫；尚未重跑的深层 producer/reachability/native 行为专项继续明确保留其 1.29.0 或 1.28.0 标签，不得无标记冒充最新版。Event.ActionType 0x19 的行为解释 authority 仍来自 1.29 native handler，但 1.30 已新增 24 条官方 stock 正样本，24/24 的 CountryRecordId + GeneralId 结构引用与该 handler 预期一致。任何“当前 corpus 未出现”的值都不能据此宣布为无效、padding 或永远为零。

7. 写入边界

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

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

8. 主要现有证据入口

reports/btl_reference/android_1300_baseline_and_elite_skin_index.json
reports/btl_reference/android_1300_value_domain_polish.json
reconstruction/docs/btl_event_android_1290_latest_baseline_and_action25_v1_report.md
reports/btl_semantic_recovery/event_android_1290_latest_baseline_v1/latest_baseline.json
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，本站原创内容许可与第三方材料排除规则见 LICENSE.md，第三方展示层许可见 THIRD_PARTY_NOTICES.md。

11. 内容许可

除另有明确说明外，本站贡献者原创且有权许可的文档表达采用 CC BY-SA 4.0。该许可不覆盖原版 WC4 游戏资产、截图中的第三方受保护表达、原始 APK/SO/BTL/存档/二进制材料、商标与第三方软件依赖，也不主张把事实、思想、方法或功能语义本身变成本站专有权利。

完整授权范围、推荐署名方式和第三方权利边界见 LICENSE.md。

12. 下一收敛工作

Reference v1 已不再有物理 section 文档空洞。Android 1.30 已把 Unit+0x2F 从“只有 consumer 证据”推进到“官方正样本 + EliteSkinSettings.Index 对齐”，但完整索引值域和 writer 安全性仍未闭合。下一阶段继续按 closure_backlog.md 消灭 Unit packed/Frontier、Building bitfield、Event 长尾和精英皮肤索引异常边界；每次研究闭合后同步底层 evidence、机器索引和中文 Reference。