WC4 BTL Reference

外观

BTL Reference 闭合状态与后续研究队列 ​

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

1. 当前结论 ​

BTL Reference v1 已经具备对外阅读所需的完整格式覆盖：

  • BTL 物理 section：20/20 有正式中文入口；
  • Header：0x80 全 32 槽覆盖；
  • Country：0x12C 全字节覆盖；
  • Building：0x20 全字节覆盖；
  • Unit：v1 0x30、v2/v3 0x40 全字节覆盖；
  • Event：0x2C 全字节覆盖，并明确 trigger/action union；
  • Reinforcement：v1 0x50、v2/v3 0x68 全字节覆盖；
  • v3+ ExtensionArea：原版 descriptor、9 个顶层字段、17 个可达 message / 78 字段 consumer coverage 已建立；
  • 其余短记录均至少有 authoritative raw-first 物理说明。

当前最新 Android 1.30.0 全 corpus：

text
BTL files             = 1383
exact physical parses = 1383 / 1383
exact length matches  = 1383 / 1383

1.29.0 / 1359 与 1.28.0 / 1358 继续作为历史差异和已有 native/专项语义证据层。

因此现在可以发布一份明显超过传统社区“偏移表”的中文 BTL Reference。

但这不表示 BTL 的所有玩法语义已经 100% 闭合。

2. 三种“完成”必须分开 ​

2.1 格式文档完整 ​

当前状态：已达到 Reference v1。

含义：

  • 文件每个 section 都知道在哪里、长度如何计算；
  • 每个主要 Record 都有完整 byte map 或明确 raw-preserve 区；
  • Unknown 不会形成未描述的文件空洞；
  • v1/v2/v3 边界已显式记录。

2.2 字段语义完整 ​

当前状态：未完成。

仍存在：

  • packed bit 未逐位闭合；
  • raw scalar 有 consumer 但没有稳定用户侧名称；
  • current corpus 无正样本；
  • type-dependent union 只闭合部分分支。

2.3 安全 writer 完整 ​

当前状态：远未等同于 Reference 完成。

BTL writer 必须另外证明：

  • 引用完整性；
  • count/length 联动；
  • 结构插入/删除；
  • unknown byte preservation；
  • protobuf reserialize compatibility；
  • invalid input 原版边界。

所以本 Reference 的“可读”不能被解释成“所有字段可写”。

3. P0：最值得继续打掉的语义 Unknown ​

这些条目会显著提升普通 MOD 作者能理解/编辑的 BTL 能力。

Unit ​

  1. +0x25 BattleMode 6 / Frontier owner-feature gate 完整语义；
  2. +0x2B 全 bit mask；
  3. +0x36/+0x38..+0x3F 逐字段/逐 bit consumer；
  4. +0x08/+0x0A 两个 legacy scalar；
  5. +0x2E；
  6. +0x2F EliteSkinIndexRaw 的 Index > 1、缺失定义、非 Elite 非零值与非法值 fallback/异常边界（字段身份与 stock 0/1 映射已由 1.30 正样本闭合）。

Building ​

  1. +0x14 全 bit mask；
  2. +0x17 全 bit mask；
  3. +0x1D high 5 bits；
  4. +0x08/+0x0A BuildingType × consumer matrix；
  5. +0x12/+0x13/+0x15/+0x1E/+0x1F。

Event ​

TriggerType 已完成第四轮 producer/lifecycle 收敛：corpus 0..5 全部列出；Type0/3 direct EventId callback gate 已闭合；Building+0x0E CaptureEventId <-> runtime Tile+0x150 已直接双向闭合；Type1/4 stock reference-role 已闭合；Type5 已闭合 caller Country.RecordId gate + positive center TileId + inclusive hex-radius 圈外→圈内算法，并确认成功执行后的 runtime executed latch 会阻止同一 Event 对象再次由 Type5 evaluator 执行。剩余：

  1. ActionType 0x00..0x19 与 TriggerType 0x00..0x05 的原版正式 enum/UI 名称；其中 0x19/25 的 native handler 来自 1.29，1.30 已新增 24 条 stock 正样本；
  2. Type3 57 条已升级为 audited normal Battle graph 下 dormant/unreachable；下一步只追未审计 computed/indirect 特殊入口或 runtime mutation 证据，不再凭空假设 producer；
  3. TriggerType 0x02 的排序/repeat/ActionType-4/missing-linked-event 边界；
  4. Type5 center/Country-gate seed-ineligible 记录的完整 lifecycle，以及 stock 没有 +0x22!=0 Type5 正样本带来的边界；
  5. ActionType 0x0D/0x18 Reinforcement 的完整占用/失败/表现时序，0x0E 异常/null/context 边界，0x0F Country 额外 runtime object cleanup 的完整业务语义；
  6. status definition 逐 ID 效果与 stack/替换边界；
  7. LinkedEvent cycle/re-entry、presentation defer、pending resume 和异常引用边界；
  8. ActionType 0x19 的 1.30 设备动态验收、GeneralId=0、无匹配/重复匹配的 author/runtime 合法性和完整反馈；1.29 native ActionType 0..25 外 parser/runtime validity，以及仍未闭合的 +0x10/+0x14/+0x18 union 长尾；
  9. 其余仍带明确历史标签的深层 producer/reachability 专项按证据需要迁移到 1.30；物理布局、Extension wire、Unit EliteSkinIndex、Event raw/value corpus、Behavior、Country、Reinforcement 与固定记录总量已前移到 1.30。

4. P1：模式和 Extension 长尾 ​

  • H50 bit16 玩法/表现含义；
  • H74；
  • H78；
  • victory type 全分支的参数命名和最终结果合成。

Country ​

  • +0x24；
  • 56 个 technology slot 的逐槽 consumer；
  • defeat policy 0..7 的完整用户侧 enum；
  • +0x120/+0x124/+0x128..+0x12B；
  • 全 BattleMode 下 controller seed 与最终控制权组合。

Extension ​

  • countryEx/buildingEx 正样本；
  • armyBuffs/armyStats 原版 disk-tail 正样本；两者 runtime 容器/导入结构已闭合，armyBuffs.buffId 已闭合为 ArmyBuffSettings.Id，并确认 BTL importer 对 lookup-success 记录逐条直接 append、不会套用正常 runtime add/refresh 的同 Id/同 Type 合并；同时已恢复 country-index 分区 tick、有限 round 递减/删除和 -1 sentinel。Android 1.30 runtime gate audit 已确认 load/post-load/native-save 链不存在额外 ArmyBuff Type/BattleMode acceptance 白名单；armyStats.statType 已扫到至少 1..17，8/9/0x0C 的剩余自然语义已闭合，10 则明确收口为 Lightning Division LegendTactics Type32/Id10602 的 Effect 投影槽且 stock 1.30 NoConsumerObserved。仍需官方/内部 authoring UI 是否过滤候选 Id、crafted duplicate 的 Type-specific 最终消费、stat 异常值/save-load acceptance，以及 key10 在未来版本/其他平台是否出现 consumer；
  • tunnelFromArea 非零 BTL 正样本 + authoring/save-load acceptance；runtime producer/consumer、全局 TileId 域与 ArmyFeature Type 0x59“隧道挖掘”绑定已闭合，仍需 FUN_00489A00 全部非法目标规则及与 TunnelArgs 的关系；
  • steelWillValue 非零 BTL authoring 正样本 + 异常值合法域 + save/load acceptance；runtime 业务语义和 FUN_0048157C 一回合 reset owner 已闭合；
  • bynameId 最终 setter 闭环；
  • legendArmyId 完整 runtime coordination consumer；
  • secondary condition 最终皇冠/奖励/胜负合成。

5. P2：异常值、生命周期和兼容边界 ​

最后的高难度部分主要包括：

  • 无效 Country/Tile/Army/Building/Event/definition 引用；
  • duplicate Unit/Building 的失败对象生命周期；
  • same-Tile 多 Unit 与 Extension area 最终对象身份；
  • Reinforcement spawn 占用冲突和 deferred Country 创建；
  • Start Group A/B 完整 mode consumer；
  • Airstrike/AirSupport 全字段；
  • Mine 触发/伤害/销毁；
  • Terrain +0x0C..+0x0F tail 语义、Primary raw setter 的真实 runtime producer、derived refresh 顺序，以及 invalid id/variant/sentinel 的完整兼容边界；前 0x0C 字节的 static visual slice 与 primary MapTerrain/TerrainType 主链已收敛到 records/terrain.md；
  • protobuf duplicate singular / malformed input / merge 的完整原版行为；第一 writer gate 对这些输入采用 fail-closed，并以 lossless local rewrite 保留 future unknown fields；同版本原版 fresh protobuf regeneration + SerializeToArray 已闭合；
  • Extension writer foundation 已完成：bynameId/legendArmyId lossless local wire transform、独立变长 preservation/transaction/Save As；其 writer qualification 仍明确来自 1.28 原版 corpus 的 407/407 no-op 与 112/112 controlled mutation+inverse，不能用当前 1.30 的 415 个 read-side payload 自动替代；剩余 package-boundary qualification、Scenario Editor product admission 和 original-game behavior acceptance；
  • 其他 MapSource 值；
  • 当前 1.30.0 stock corpus 仍未覆盖的其他版本/模式正值域。

这些问题往往无法靠继续扫描当前 1.30.0 的同一批 1383 个文件解决，需要 native consumer、cross-arch、其他合法原版样本或受控动态 trace。

6. 研究闭环模板 ​

后续每消灭一个 Unknown，固定采用：

text
Reference Unknown/Partial
-> native parser/consumer recovery
-> original corpus distribution
-> cross-architecture when useful
-> controlled runtime trace when necessary
-> update underlying evidence/canonical
-> update machine Reference index
-> update Chinese Markdown
-> update community correction/supersession if needed

不得反过来先修改文档名称，再寻找证据证明它。

7. 当前可发布范围 ​

现在可以公开/交付给普通读者的内容包括：

  • BTL 总体文件结构；
  • v1/v2/v3 差异；
  • Header/Country/Building/Unit/Event/Reinforcement 主记录；
  • Province/Owner/Behavior/Weather/Strategy；
  • v3+ BattleExArgs；
  • 社区旧文档勘误；
  • 明确的 Unknown/NoGo 列表。

公开时必须同时保留证据状态标签。不能为了让文档看起来“完整”而隐藏 Unknown。

8. 不属于本 Reference v1 的完成声明 ​

当前不能声称：

text
BTL gameplay semantics 100% closed
all BTL fields safe to edit
arbitrary BTL writer compatible
all Event actions restored
all Extension gameplay effects restored
all invalid-input behavior restored

当前准确表述是：

BTL 物理格式和中文 Reference v1 已形成完整覆盖；主要记录语义已经高度恢复，剩余工作集中在 packed/模式专属字段、Event union、Extension 无正样本字段、异常输入和动态生命周期。

除另有说明外，本站有权许可的原创文档采用 CC BY-SA 4.0；第三方内容除外。