WC4 BTL Reference

外观

BattleArmyExArgs：单位 Extension ​

状态：Authoritative Reference v1

1. Schema ​

原版 Game.proto descriptor：

proto
message BattleArmyExArgs {
    int32 area = 1;
    repeated SArmyBuffArgs armyBuffs = 2;
    int32 bynameId = 3;
    int32 tunnelFromArea = 4;
    int32 steelWillValue = 5;
    repeated SArmyStatArgs armyStats = 6;
    int32 legendArmyId = 7;
}

7/7 字段均进入原版 BTL Extension loader 的 Army 委托链，因此字段存在、编号和 loader consumer coverage 均为 Confirmed。

2. Corpus ​

当前 1.28.0：

text
含 armyExs 的 BTL         = 112
BattleArmyExArgs 总数     = 8425
area 出现                 = 8425，非零 8425
bynameId 出现             = 8425，非零 7972
tunnelFromArea 出现       = 8379，非零 0
steelWillValue 出现       = 8363，非零 0
legendArmyId 出现         = 8223，非零 453
armyBuffs disk 实例       = 0
armyStats disk 实例       = 0

armyBuffs/armyStats 没有当前磁盘正实例，不代表 loader 不支持：descriptor、generated copy 和委托 consumer 都已经存在。

3. area：运行时 Army 查找键 ​

导入链：

text
BattleArmyExArgs.area
-> global Tile object vector lookup
-> Tile exists and contains Army
-> FUN_00480CC8(Army, BattleArmyExArgs)

当前 8425/8425 条 area 都至少匹配一条固定 Unit.TileId：

text
唯一 fixed Unit 匹配 = 8372
多条 same-Tile Unit   = 53
未匹配                = 0

因此 area 是全局地图 Tile/Army identity，而不是 Unit record index。

53 个多匹配样本仍不能仅按固定记录先后猜测最终对象。Extension 实际作用于 runtime Tile 上最终存在的 Army 对象；精确构造/拒绝/替换身份必须服从 Unit duplicate 的原版生命周期证据。

4. armyBuffs ​

armyBuffs descriptor 和 loader consumer 已确认：

text
repeated SArmyBuffArgs
-> generated copy
-> buff conversion
-> apply to Army runtime object

但当前 1.28.0 磁盘 BTL Tail 中：

text
positive instances = 0

所以：

text
schema             = Confirmed
loader consumer    = Confirmed
BTL value domain   = UnknownNoPositiveCorpus
dynamic effects    = Partial
writer             = NoGo

不得用合成 protobuf 样本冒充原版正样本。

5. bynameId ​

当前 corpus：

text
出现    = 8425
非零    = 7972
不同值  = 277
范围    = 0..11302

原版 descriptor 名 bynameId 已确认。现有资源和 UI consumer 证据强烈支持：

text
bynameId > 0
-> unit_name_<id>
-> 覆盖具体地图单位的完整显示名称

UI-facing 名称覆盖字段本身已有直接 consumer/fallback 证据；bynameId 到该最终 UI 字段的精确标量 setter 仍未在旧 Legend 报告中闭合，因此当前业务语义保持 StrongEvidence / Partial，不提升为完整动态行为 Confirmed。

bynameId = 0 表示不提供该名称覆盖的方向有 corpus/资源支持，但 writer 仍未开放。

6. tunnelFromArea ​

当前 corpus：

text
字段显式出现 = 8379
值为 0       = 8379
字段缺省     = 46
非零实例     = 0

原版 FUN_00480CC8 会把它复制到 Army runtime 字段，但在 Extension 导入阶段不立即按 area lookup。

因此当前状态：

text
schema/consumer       = Confirmed
nonzero semantics     = UnknownNoPositiveCorpus
reference target      = Unknown
writer                = NoGo

不能仅凭字段名把它自动关联到某个 TunnelArgs 目标并生成引用修复。

7. steelWillValue ​

当前 corpus：

text
字段出现 = 8363
全部为 0

字段名和 runtime 导入已 Confirmed，但当前原版 BTL 没有非零值，无法从磁盘样本恢复有效范围、动态效果或与其他 steel-will 系统状态的组合关系。

状态：UnknownNoPositiveCorpus（值语义），writer NoGo。

8. armyStats ​

与 armyBuffs 类似：

text
repeated SArmyStatArgs
-> generated copy helper
-> runtime stat collection

descriptor 与 loader consumer 已确认，但当前 disk-tail corpus 没有 field 6 正实例。

所以不能因为 message schema 已知就制作正式编辑表单。

9. legendArmyId ​

当前：

text
字段出现 = 8223
非零     = 453
非零范围 = 1..10

分布：

ID数量
153
247
340
443
552
641
744
845
941
1047

原版 descriptor 名、Legend 语料和 legend_army_* 资源共同支持它表示 Legend 编制/协同身份，当前为 StrongEvidence。

但精确运行时协同消费者和全部判定入口尚未闭合，所以不把它扩大为完整玩法规则。

10. bynameId 与 legendArmyId 绝不能合并 ​

两者在原版 schema 是独立字段，corpus 也存在独立组合。

例如已有记录满足：

text
bynameId = 0
legendArmyId = 10

同时资源存在：

text
legend_army_10 = 第51高地师

这说明：

  • bynameId 可以负责地图单位显示名称覆盖；
  • legendArmyId 可以在不提供 bynameId 的情况下标记 Legend 编制身份；
  • “显示名相同”不等于“同一字段”。

工具若把两者合并，会破坏原版数据语义。

11. area 与当前 local TileSlotCount ​

当前有 10 条 armyEx.area：

text
area >= Header.AlignedTileSlotCount

但它们全部仍能命中固定 Unit 的全局 TileId。

因此：

text
local TileSlotCount overflow
!= invalid armyEx.area

尤其 external-map/cropped BTL 必须按全局 Tile 地址空间判断。

12. Writer 边界 ​

当前全部 BattleArmyExArgs 语义写入仍是 NoGo：

  • protobuf 变长重建未授权；
  • area 有 53 个 runtime object disambiguation 未闭合；
  • buff/stat 没有当前正样本；
  • tunnel/steelWill 没有非零正样本；
  • byname/Legend 的完整动态 consumer 仍有长尾；
  • serializer/merge compatibility 未闭合。

因此当前 Reference 只提供读取和研究 authority。

13. 主要证据 ​

text
reports/btl_v3_tail_legend_recovery.md
reports/btl_v3_army_extensions_matrix.csv
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