WC4 BTL Reference

外观

BattleExArgs：BTL v3+ ExtensionArea ​

状态：Authoritative Reference v1

1. 物理入口 ​

BTL v3+ 在固定区段之后可以携带由 Header H54 指定长度的 protobuf payload：

text
fixed BTL sections
-> H54 bytes ExtensionArea
-> Game.ProtoBuf.BattleExArgs

当前 1.28.0 corpus：

text
v1/v2 AbsentByVersion = 464
v3 PresentEmpty       = 487
v3 PresentNonEmpty    = 407

407/407 个非空 payload 都符合从原版 SO 恢复出的 Game.proto descriptor：

  • 无未知 field number；
  • 无错误 wire type；
  • 无截断 message；
  • 无 unresolved message type；
  • 无 required-field 缺失。

总 ExtensionArea 数据量为 120389 字节。

2. Descriptor authority ​

原版 ARM64 SO 的 .rodata 中保存完整 FileDescriptorProto：

text
file offset = 0x83BEF4
length      = 12676 bytes
end         = 0x83F078
sha256      = 578ec76aee16db23f0814930052ba9b508837f914e6feb40fb9673c3d5c032fc
package     = Game.ProtoBuf
syntax      = proto2
messages    = 79 top-level
Enums       = 2 top-level

BattleExArgs 可达类型树共有 17 个 message、78 个字段。

这意味着字段名、编号、label 和 protobuf 类型不是社区推断，而是原版 descriptor 直接证据。

3. BattleExArgs 顶层字段 ​

Field名称类型BTL loader consumer当前 1.28 corpus语义状态
1countryExsrepeated BattleCountryExArgs按 country id 查找 Country，委托 FUN_0048934C0Confirmed consumer / UnknownNoPositiveCorpus
2secondaryConditionsrepeated SSecondaryConditionArgs复制 condition/num 到 Battle 条件表796Confirmed
4armyExsrepeated BattleArmyExArgs按 area 查找 Army，委托 FUN_00480CC88425Confirmed
5conquerEventsrepeated SConquerEventArgs构造事件运行时条目并设置相关状态0Confirmed consumer / UnknownNoPositiveCorpus
6warrecordsrepeated SWarRecordArgs复制六整数战报记录0Confirmed consumer / UnknownNoPositiveCorpus
7numintkeyarmyoptional int32写入 Battle+0x25C0Confirmed consumer / UnknownNoPositiveCorpus
8armyGroupReinforcementsrepeated SArmyGroupReinforcementArgs向 Reinforcement service 提交 armyId/num/cost0Confirmed consumer / UnknownNoPositiveCorpus
9buildingExsrepeated BattleBuildingExArgs按 area 查找 Building，委托 FUN_004879FC0Confirmed consumer / UnknownNoPositiveCorpus
10gloryChallengeStatsrepeated GloryChallengeStatArgs解析 id/count 并追加运行时记录0Confirmed consumer / UnknownNoPositiveCorpus

注意：当前 BTL corpus 只出现 field 2 和 field 4，不等于其他七个字段“未实现”。原版 BTL loader 已经存在它们的直接导入分派；缺少的是当前 1.28 原版磁盘正实例。

4. Loader consumer coverage ​

原版主导入链：

text
FUN_00331CD4
-> ParseFromArray(H54 bytes)
-> FUN_00339B58(Battle*, BattleExArgs*)

当前静态 consumer matrix：

text
BattleExArgs top-level dispatch       9 / 9
reachable messages                  17
reachable descriptor fields         78
RuntimeConsumed                     77
NoLoaderConsumerObserved             1
schema/matrix exact                78 / 78

唯一在 descriptor/generated object 中存在，但当前 BTL loader 导入链没有读取的字段是：

text
BattleCountryExArgs.countryTechCategoryIds

它的正式状态是：

text
SchemaPresentButIgnoredByBtlLoaderImportPath

这只证明当前版本 BTL loader 不读取它，不能推出该 protobuf 字段在其他路径永远无效。

5. 立即对象引用 ​

FUN_00339B58 对三类 Extension record 使用立即 lookup：

countryEx.id ​

text
countryEx.id
-> FUN_00346FB0
-> 按 runtime Country 首个 int32 / Country.RecordId 精确查找
-> missing => null
-> 不调用该条 countryEx 的委托 consumer

armyEx.area ​

text
armyEx.area
-> global Tile object vector lookup
-> Tile exists and has Army
-> FUN_00480CC8

buildingEx.area ​

text
buildingEx.area
-> global Tile object vector lookup
-> Tile exists and has Building
-> FUN_004879FC

未解析的立即引用不会由 loader 自动创建、重定位或修复对象。用户可见提示和后续动态副作用仍需单独行为验收。

6. area 使用全局 TileId 地址空间 ​

Extension 中 armyEx.area/buildingEx.area 使用的是 runtime global Tile object 地址空间。

不能用：

text
Header.AlignedTileSlotCount

作为有效性上限。

当前 8425 条 armyEx.area：

text
fixed Unit.TileId 至少一条同值 = 8425 / 8425
唯一固定 Unit 匹配             = 8372
多条固定 Unit 同 TileId         = 53
无固定 Unit 匹配                 = 0

其中 10 条 area 大于等于当前 BTL 本地 TileSlotCount，但仍有合法 fixed Unit.TileId 同值。这些是全局 TileId，不得因超出当前 crop/local slot 就删除或清零。

7. 当前可达 schema ​

原版 BattleExArgs 可达的 17 个 message：

text
BattleExArgs
BattleCountryExArgs
BattleEliteCountArgs
SCardCDArgs
SCardRoundArgs
SEventBuffArgs
TunnelArgs
SSecondaryConditionArgs
BattleArmyExArgs
SArmyBuffArgs
SArmyStatArgs
SConquerEventArgs
SWarRecordArgs
SArmyGroupReinforcementArgs
BattleBuildingExArgs
SBuildingBuffArgs
GloryChallengeStatArgs

本 Reference 当前优先对实际 corpus 中存在的：

text
SSecondaryConditionArgs
BattleArmyExArgs

做逐字段公开说明。

其余消息的 descriptor 与 BTL loader consumer 已静态闭合，但由于当前原版 BTL 无正实例，不能凭函数签名替代真实值域和动态玩法结果。

8. Schema 已知不等于 writer 已开放 ​

以下链路必须分开：

text
protobuf descriptor known
!= original disk value domain known
!= runtime dynamic behavior fully known
!= serializer compatibility known
!= safe writer

当前 ExtensionArea 仍保持：

text
semantic reconstruction writer = NoGo
variable-length save            = NoGo
canonical protobuf reserialize  = NoGo
unknown-field dropping          = NoGo
automatic reference repair      = NoGo

安全保存方式仍是原始字节 preservation。

9. Serializer / merge 未闭合边界 ​

虽然当前 407 个 payload 都完全符合 descriptor，仍没有足够证据授权重新序列化，因为尚未完整恢复：

  • 原版 serializer 是否保持输入 field 顺序；
  • duplicate singular field 的 merge 行为；
  • unknown fields 的跨版本 forward compatibility；
  • 重复 message 的排序稳定性；
  • malformed protobuf 的原版用户侧反馈；
  • writer 是否规范化默认值的显式/缺省表示。

所以“能用 protobuf library 解析”不能升级成“可以 parse 后 regenerate”。

10. 当前 closure backlog ​

Extension 剩余主要不是字段表，而是：

  1. 当前无正样本的七个顶层字段的真实 BTL 值域；
  2. countryEx/buildingEx 正实例；
  3. countryTechCategoryIds 在 BTL loader 外是否有 protobuf consumer；
  4. 无效 country/army/building/config 引用的完整动态反馈；
  5. 53 个 same-Tile Unit 多匹配时最终 Army 对象身份；
  6. protobuf serializer/merge/unknown-field 兼容边界；
  7. 静态 consumer 对应的全部动态玩法效果；
  8. 安全 writer 所需的引用、不变量和变长保存合同。

主要证据：

text
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/docs/btl_editor_round41_extension_reference_integrity_evidence_recovery_report.md
reports/btl_editor/round39/extension_descriptor_schema_evidence.json
reports/btl_editor/round40/native_consumer_coverage.json
reports/btl_editor/round41/reference_integrity_evidence.json