这是一个基于 WSE2 Lua 的《骑马与砍杀：战团》普通士兵持久化系统。它的目标不是给英雄单位加功能，而是让普通士兵也能拥有稳定的姓名、性别、脸、装备、战绩、服役时间，并在招募、升级、受伤、死亡、逃跑、驻军、俘虏、交换、战后转交等复杂流程中尽量保持“这个人还是这个人”。
系统尽量不修改原模组的 txt 文件，而是在 Lua 层通过 WSE2 array、mission trigger、operation hook 和战场 agent 接管来实现。
因此它可以挂在**不同模组**上直接使用，但仍然会受限于战团本身对普通士兵的黑箱/硬编码处理方式。
在不同模组中使用此脚本可能会遇到各种红字错误。经测试，潘德子mod和战团原版暂无特别严重的恶性bug，也暂时没遇到抛出红字的情况（做了专门适配）。
注：由于本lua脚本的特殊性，在安装本模组后，视为你自愿充当小白鼠。请你务必反馈遇到的问题。

## 主要功能
### 普通士兵持久化
每个被花名册管理的普通士兵都有一个独立条目。条目保存：
- 当前兵种。
- 随机姓名种子。
- 性别。
- 脸型 key 和拆解后的脸型字段。
- 当前装备。
- 加入队伍的游戏内时间。
- 击杀数。
- 受伤次数。
- 老兵敬意判定用的上次击杀数和上次服役天数。
- 当前状态：在玩家部队、在外部部队/驻军、在俘虏列表，或者空闲。
- 如果不在玩家部队，还会保存它所在的 party id。
普通士兵在玩家部队里增减时，系统会用玩家队伍的 troop stack 数量和花名册条目数量做同步。多出来的同兵种士兵会创建新条目，减少的同兵种士兵会移除或转移条目，升级则会迁移旧条目到新兵种。

### 姓名系统
姓名由 `roster/name_config。lua` 控制。配置文件支持：
- 男性保底姓名池。
- 女性保底姓名池。
- 按性别和 troop 阵营匹配的专用姓名池。
- `first` 和 `bynames` 两段式组合。
系统通过 `store_troop_faction` 获取 troop 的阵营编号，再按 `pools` 中的 `genders` 和 `factions` 选择姓名池。没有匹配池时走 `fallback`。姓名不是每次重新随机，而是根据条目保存的 seed 生成，所以同一个士兵在读档、升级、驻军、俘虏后仍会得到同一个名字。
**注意**
本脚本内自带的姓名库，对应的阵营号是以潘德的预言子mod制作的。如果你想应用于别的mod，我建议你重新以该mod的阵营号调整姓名库。否则可能会出现串风格的情况。
我预留了以下风格的姓名库，对应的阵营包括但不限于：
维京风格（菲尔兹威、凡斯凯瑞强盗、女武神骑士团、克拉肯战士教团等）
罗斯风格（凛鸦王国、龙骑士团、鸭矛骑士团、猎鹰骑士团、迷雾山强盗等）
法兰西风格（烈狮王国、潘德王国、狮骑士团、号角召唤游侠团、乌木护手骑士团、狮鹫骑士团等）
Muslin风格（德夏、辛加尔、御风者团、天蝎刺客团等）
罗马风格（巴克斯帝国、马里庭帝国、不朽者团、凤凰骑士团等）
蒙古风格（迦图）
神罗风格（梅滕海姆）
西班牙风格（巴克利）
精灵风格（诺多精灵）
默认风格（普通中世纪姓名杂烩，仅在阵营没被上述池包含时使用）

### 性别、脸和装备
花名册会保存士兵的性别、脸和装备。对于某些模组常见的“同一个 troop 在生成时随机改男女”的做法，系统会拦截和观察 `troop_set_type`，在首次生成时尽量锁定该条目真正得到的性别。以后升级、迁移、驻军取回或战场重新生成时，都按花名册里保存的性别来生成，而不是再次被模组随机触发器覆盖。
脸型部分会保存完整 face key，同时拆解出发型、胡子、贴图、发色、年龄、肤色和 morph 字段，便于重建和修复。装备部分保存武器、头盔、身甲、腿甲、手套、马匹等槽位，并在战场生成 clone 时强制应用。

### 战场姓名和统计显示
进入场景后，系统会在士兵头顶显示姓名。按键可配置：
- `N` 默认切换姓名显示。
- `M` 默认切换统计显示。
姓名和统计显示彼此独立。统计行和姓名同色，内容格式为：
服役天数 击杀数/受伤次数
显示距离、快捷键、是否按性别染色、男女颜色、默认颜色都在 `roster/config。lua` 中配置。姓名使用居中 overlay，统计行使用左对齐 overlay。
注：对于特殊性别——包括潘德等模组里的“漂亮女性脸”、“精灵脸”、“恶魔脸”，名字颜色默认显示蓝色。

### 击杀经验补偿
战团原生普通士兵经验是按 party stack 处理的。Lua 生成的 clone 不一定会被原生系统正确视为玩家队伍中的普通士兵，所以 clone 击杀敌人后，系统会手动给玩家队伍中对应兵种 stack 增加经验。
经验按敌方 troop 等级计算基础值，再乘以 `roster。config。regulars_xp_multiplier`。默认值是 Native 常见的 `3`。如果模组的 `module。ini` 使用了不同倍率，建议直接在 `roster/config。lua` 里设置。但注意，原生士兵击杀敌方Agent获得经验值的操作应该仍然是个黑箱。本人观察到，即使在conig。lua里调整倍率为3，士兵杀敌获得的经验值可能比原版获得的多。你可以自己慢慢调试。

### 老兵敬意
当花名册士兵被击倒时，可以触发“老兵敬意”判定。判定成功时，这次击倒会强制按受伤处理，而不是死亡。
成功率由两部分相加：
- 自上次判定后新增击杀数 × `veteran_respect_kill_chance_percent`。
- 自上次判定后新增服役天数 × `veteran_respect_service_day_chance_percent`。
判定后会记录本次击杀数和服役天数，下一次只计算新增部分。这个功能由 `veteran_respect_enabled` 总开关控制。

## 为什么需要“本体 + 克隆人”
战团的普通士兵本质上不是一个长期存在的“角色”。在大地图上，普通兵只是一组 troop stack 计数；进入战场后，游戏才临时生成 agent。战斗结束后，原生脚本再按 agent 伤亡结果回写到 party stack。
这会带来几个核心限制：
- 普通士兵没有原生持久 ID。
- 同一兵种的多个士兵在 party stack 里没有个体差异。
- 想给某个普通士兵应用指定脸、性别、装备，只能通过 troop 模板影响生成出来的 agent。
- troop 模板是全局的，如果长期修改，会污染同兵种的其他普通士兵。
- 直接用 Lua 生成的 agent 往往没有合法 party id，原生伤亡统计和 AI 脚本可能会遇到 `party_id = -1`。
因此系统采用“隐藏原生本体 + 生成花名册 clone”的方案。
流程是：
1. 战场开始前，系统根据花名册构建需要接管的条目队列。
2. 原生 mission 正常生成普通士兵 agent。
3. 系统找到与花名册条目匹配的原生 agent，把它隐藏、禁战、移到地下或特殊位置，作为“本体”保留。
4. 系统短暂修改该 troop 模板的性别、脸和装备。
5. 用修改后的模板生成一个新的 clone agent。
6. clone 生成成功后把 troop 模板放入短延迟恢复队列，避免引擎尚未完成 agent 身体初始化时就把性别恢复回原始值。
7. clone 负责真正出现在战场上、战斗、显示姓名和统计。
8. 本体负责让原生战斗结算仍能识别这名士兵属于原来的 party/stack。
这个方案看起来绕，但它解决了两个互相冲突的需求：一方面要让玩家看到并使用“个体化”的士兵，另一方面又不能让原生脚本完全丢失这个士兵的伤亡结算上下文。只生成 clone 而不保留本体，容易导致原生伤亡统计、逃跑统计、战后 wounded/dead 计算失真；只修改原生 agent，又很难稳定控制它的生成前脸型、性别、装备，并且会污染 troop 模板。

## 战场接管流程
### 队列构建
在 `ti_before_mission_start`，系统会先同步一次玩家队伍，再构建接管队列。队列来源包括：
- 玩家部队中的 active 条目。
- 当前战斗中可识别的外部 party/驻军条目。
- 最近战后转交给友军的条目。
- siege、settlement、lead_charge 等场景中可通过当前 encounter、当前城镇、附属 party 推断出的 garrison 条目。
队列不是简单按 troop 数量全部替换，而是只替换花名册中实际存在的条目。这样城堡里原本有 4 个普通 A，玩家只存进去 1 个命名 A 时，理论上只会接管 1 个 A，其余 4 个仍然是普通原生士兵。

### 隐藏本体
接管到原生 agent 后，系统会保存它的上下文：
- troop id。
- party id。
- stack no。
- team、division、position。
- 是否友军。
- 马匹。
随后隐藏本体、禁用战斗、限制速度、降低可见性，并保留它用于后续伤亡同步。对于 routed 逃跑，本体不会立即删除，而是按 clone 的逃跑节奏设置逃跑状态并移向边界，尽量让离场时机与 clone 一致。

### 生成 clone
生成 clone 时，系统会：
- 临时设置 troop 性别。
- 临时应用保存的脸型。
- 临时清空并写入保存的装备。
- 在本体位置生成 agent。
- 将 clone 与花名册条目绑定。
- 恢复 troop 原始性别和装备。
- 记录 clone 和本体的映射关系。
延迟恢复 troop 模板是关键步骤。恢复太早时，clone 可能显示了正确姓名颜色却继承回原始性别；恢复太晚时，同一场战斗后续援军、敌方同兵种、友军同兵种又可能错误继承某个花名册士兵的脸或装备。当前做法是在 clone 生成后保留一个短窗口，再由恢复队列把 troop 模板还原。

### 援军与后续刷兵
因为每次 clone 生成后都会在短延迟后恢复 troop 模板，所以后续刷出的同兵种原生 agent 不应该继承花名册外观。系统还会在 mission tick 中尝试 rebind 未绑定 agent，用于处理某些模组晚生成 agent 或援军刷新。
设计原则是：只有能匹配到花名册队列或外部 party 条目的 agent 才会被接管。普通同兵种 agent 不应被污染。

## 伤亡、击晕、逃跑同步
clone 在战场上被击杀或击晕时，系统会找到对应的隐藏本体，并把同样的命运同步给本体。
### 击杀和击晕
当 clone 倒地：
1. 记录该条目的受伤次数或死亡结果。
2. 如果触发老兵敬意，把死亡改成受伤。
3. 尝试让隐藏本体受到对应伤害，让原生脚本正常统计。
4. 如果原生同步失败，则用手动 casualty fallback 对 party stack 直接做伤亡处理。
5. 清理 clone 的姓名和统计 overlay。
这么做的原因是：战团最终在 `count_mission_casualties_from_agents` 等脚本中按 agent 状态统计伤亡。如果 clone 没有合法 party id，而本体又没有同步倒地，战后就会出现“clone 倒了但部队没事”或“死亡/受伤数量不对”的问题。
### 逃跑
clone 逃跑时不能简单 `remove_agent`，因为原生可能把移除视为击杀或导致统计异常。系统会把本体也设置为 routed，并让本体移动到地图边界或离场位置，等待原生逃跑逻辑处理。这样可以避免 clone 还在逃跑、本体已经被提前清掉造成的离场时机不同步。

### 操作码保护
Lua 生成或接管的 agent 有时会让原生脚本拿到无效 id，例如 `party_id = -1` 或 `agent_id = -1`。系统在 Lua 层对几个高风险操作做了最小保护：
- `agent_get_party_id`
- `party_get_template_id`
- `party_get_morale`
- `agent_set_speed_limit`
这些保护不改原模组脚本，只是在返回值明显非法时给出合理兜底。例如 clone 等价于玩家部队时，`party_get_morale` 可以借用玩家 party 士气。
但是，游戏内有大量有关party获取的操作码，这里并没有全部兜底。如果你发现在某个模组内抛出红字错误，大概率是因为如上原因。虽然看着丑陋，但应该不影响游戏本身。

## 主队伍同步
大地图上没有 agent，只有 party stack。因此主队伍同步靠“前后快照差异”判断。
系统会定期读取玩家队伍：
- 每个 troop stack 的人数。
- 可升级人数。
- 玩家俘虏 stack。
然后和花名册 active 条目数对比。
### 招募
如果某个 troop 的 party 数量多于 active 条目数量，多出来的部分会创建新条目。新条目会立即保存 troop、姓名 seed、加入时间、初始击杀/受伤数、初始性别等。
### 解散或损耗
如果某个 troop 的 party 数量少于 active 条目数量，系统会移除对应数量的条目。默认策略是 `least_veteran`：优先移除击杀更少、服役更短、受伤更少的条目，用来尽量保留老兵。也可以在配置中改回旧式 first-match 行为。
### 升级
升级无法直接监听原生部队界面的升级按钮，所以系统通过 delta 推断：
- 某个源 troop 数量减少。
- 某个目标 troop 数量增加。
- 目标 troop 是源 troop 的原生升级路径或配置中的额外升级路径。
- 可升级人数下降可以作为额外提示。
- 支持多级链式推断，例如在同一个部队界面里快速 A -> B -> C。
迁移条目时，系统优先迁移击杀数最高的条目；击杀数相同则在候选中随机。这样更符合“表现好的士兵更可能被升级”的直觉，也减少老兵被误当新人刷新的概率。