护卫犬挂载自选（Guard Dog Loadout）
**项目地址 / 下载：** https://github.com/junze0910/junze-hd2-lua-mod/releases/latest
**当前版本：** v1.0.1
## Description · 简介
把《绝地潜兵 2》的**护卫犬（机枪犬 `drone_mg`）挂载的武器**变成可配置：
- 原装 **AR-23P**
- **SEAF MG-43**（实弹，火力更强）
- **自定义物品哈希**（想在狗身上挂什么就挂什么）
它取代旧版 `Stronger Kinetic Guard Dog`（更强的实弹狗）：旧版只能把武器**写死**成 MG-43，
想换别的就得再打一个包，两个包同时装还会互相覆盖。本 mod 只改**一条记录的 8 个字节**，
所有改动都发生在运行时内存，不修改任何游戏文件，禁用后重启游戏即完全还原。
## Main features · 主要特性
### 1. 下挂物品三选一
| 选项 | 挂到狗身上的武器 | 说明 |
|---|---|---|
| **AR-23P（原装）** | 原装 `drone_mg_weapon` | **不改写**：本来就是原装 → 零写入；之前被改过（比如旧的实弹狗）→ 写回原装 |
| **MG-43（SEAF）** | `587878FB76F4B9B1` | 与「更强的实弹狗」完全相同的效果 |
| **自定义（读 cfg）** | 你填的 16 位哈希 | 见下一条 |
> 选 **AR-23P（原装）** 时狗身上**不会有任何变化** —— 那个选项的语义就是「不改写」，这是正常的。
### 2. 自定义物品哈希
- 配置文件：`%LOCALAPPDATA%\CowboyBingus\Helldivers2\GuardDogLoadout.cfg`
- 写成 `weapon=custom` + `custom=<16 位 BE 十六进制>`，**改完 1 秒热生效**，不用重开游戏
- 大小写、前后空格、行尾 `# 注释` 都行
- 带 `0x` 前缀 / 长度不足 / 全 0 / 留空 → **拒写**：保持当前值，并把原因写进日志
- ⚠ **不校验哈希的含义**：填一个不存在 / 不适配的物品哈希会**真的写进挂载槽**，
狗可能召唤异常 —— 请填你**确认存在**的物品哈希
### 3. 随便改
- 三个选项可以**反复来回切换**，改完再改照样生效
- 写入判据是「原装」或「本次目标」或「**上次自己写过的值**」，不是只认原装
—— 不会出现"一个槽只能改一次"
- 在 MODS 页改选项 / 手改 cfg 后**下一帧**就写入（不用等定期复扫）
### 4. 陌生值拒写（刻意保护）
- 如果这个槽位当前的武器**不是本 mod 写的、也不是原装**（例如被别的 mod 改过），
本 mod 会**拒写**并把原因写进日志 —— 不会去覆盖别人的改动
- 想强行带回原装，用「**初始化**」
### 5. 初始化
- 一键回到**原始默认**：
- 挂载武器 = 原装 **AR-23P**
- cfg 复位为 `weapon=ar23p` / `custom=` 空
- **即使当前值认不出来，也会强行写回原装**
- **不会读你上次退出的 cfg** —— 初始化就是「回原始默认」
### 6. 自动复查
- 改完任何设置（MODS 页改选项 / 手改 cfg）都会**立刻**触发一轮写入 —— 不需要手动按「写一次」
- 之后每 300 帧自动**复查**：被游戏冲掉的补丁会被重写
### 7. 设置入口与 cfg
- **原生 MODS 页**（推荐）：`下挂物品` 三选一 + `初始化` 开关，
**选项右边的描述页里写着 cfg 的完整路径**
- 想手改 cfg 也行：文件里带着填写说明，**改完 1 秒热生效**；
并且你在 MODS 页改选项时，这些说明注释**不会被抹掉**
- 读取 cfg 时自动忽略 UTF-8 BOM（避免"改了但没生效"这种静默失败）
## Operation flow · 操作流程
### 第一步：安装前置
1. 安装 **Bingus Shared Loader v15+（API 1）**，或兼容的 MDL；
2. 安装 **HD2 Scanner v0.7.0+**（提供挂载表地址 —— **本 mod 的必需前置**）；
3. 安装 **Mod Options Menu v1.1+**（提供原生 MODS 设置页；不装仍可手改 cfg）；
4. 用 HD2 管理器导入 `GuardDogLoadout-v1.0.1.zip`，启用并部署；
5. 启动游戏。
### 第二步：选择下挂物品
**原生 MODS 页**（推荐）：ESC → **MODS** → **护卫犬挂载自选** → `下挂物品` 三选一。
改完**立即写入**，不需要另外按 Apply。
> 选项**右边的描述页**里写着 cfg 的完整路径 —— 想手改 cfg 的话照那个路径找就行。
### 第三步：自定义哈希（可选，不进游戏也能改）
1. 打开 `%LOCALAPPDATA%\CowboyBingus\Helldivers2\GuardDogLoadout.cfg`；
2. 改成：
```text
weapon=custom
custom=587878FB76F4B9B1
```
3. 存盘 —— **1 秒内自动生效**，不用重开游戏、不用点按钮。
### 第四步：进任务，先别召唤护卫犬
⚠ **这是本 mod 最容易踩的坑**：挂载表（`MountComponentData`）是**生成无人机时读一次**的静态配置，
补丁必须**早于召唤**。
1. 进入任务后，**先不要召唤**护卫犬；
2. 等日志出现这两行：
```text
[GuardDogLoadout] 已接上 HD2Scanner（前置）：MountComponentData 由 Scanner 提供
[GuardDogLoadout] 已写：drone_mg 挂载 7933E1BDE32126A3 -> 587878FB76F4B9B1（recIdx 97，node=0x53BEC437/pad=0 未动）
```
3. 看到之后**再召唤**护卫犬。
### 第五步：召唤确认
召唤出来的狗就是当前配置。状态盘可以随时核对：
```text
%LOCALAPPDATA%\CowboyBingus\Helldivers2\Logs\GuardDogLoadout_STATUS.log
```
第一行出现 `OK - 补丁生效中（1 处）` 就表示生效了。
### 第六步：后续修改
每次改配置后：
1. 在 MODS 页改选择（或直接改 cfg）；
2. 等日志出现新的 `已写：…` 一行
（若只是从 MG-43 换成另一个值，这一行会立刻出现；选回原装则会写回 `A32621E3BDE13379`）；
3. **重新召唤 / 让狗重新部署** —— 已经放出来的那只不会跟着变。
### 第七步：初始化
要回到原始默认：
1. 在 MODS 页的「护卫犬挂载自选」里找到「**初始化（强制写回原装 + cfg 复位）**」开关；
2. 打开它；
3. 会执行：
- 挂载武器写回**原装 AR-23P**
- CFG 回到默认（`weapon=ar23p` / `custom=` 空）
- 清空写入状态
4. 日志会写：
```text
[GuardDogLoadout] 初始化：已强制写回原装，cfg 复位为 AR-23P（原装）
```
## Requirements · 依赖
* **Helldivers 2**（v1.0 实机测试于 `1.8.45850.0` + loader v17）
* **Bingus Shared Loader v15+（API 1）**，或兼容的 MDL
* **HD2 Scanner v0.7.0+** —— 必需（挂载表地址来源）
* **Mod Options Menu v1.1+** —— 设置 UI 前置（提供原生 MODS 页；不装仍可手改 cfg）
* 一个能导入 zip 的 HD2 mod 管理器（HD2MM / Arsenal 等）
* Windows x64
> 必需前置：**HD2 Scanner**。缺少它时本 mod **零写入**，只把原因写进日志与状态行（不会乱写内存）。
> 缺少 ModOptionsMenu 时改不了图形设置页，但仍然可以**手改 cfg**（1 秒热重读）。
## Compatibility · 兼容性
* 取代 `Stronger Kinetic Guard Dog`（更强的实弹狗）—— 两者改的是**同一条记录的同一个槽位**，
请**二选一**；同时启用只会互相覆盖。
* 与 AC-8、TD-110 挂载切换、EXO 战备自选、HD2 Scanner 互不冲突。
* 只改本机内存；联机时其他玩家通常看不到你的改动。
* 与其它改写同一槽位的 mod 同时使用时，若当前值本 mod 不认识，会**拒写**（不覆盖别人的改动）；
想强行带回原装请用「**初始化**」。
* 游戏启用 nProtect GameGuard，使用第三方工具的风险由使用者自行承担。
## Known limits · 已知限制
* 自定义哈希**只能手改 cfg 文件** —— MODS 页只支持固定选项，**不支持自由文本输入**。
* 挂载是「**生成无人机时读一次**」：改完必须**重新召唤**（或让狗重新部署）；
已经放出来的那只不会跟着变。
* ⚠ 自定义哈希**不校验含义**：填错可能造成召唤异常，请填你确认存在的物品哈希。
* 选「**AR-23P（原装）**」而狗身上没变化是**正常行为** —— 那个选项的语义就是「不改写」。
* 首次加载后没有热重载：cfg 是 1 秒热重读，但**更换 mod 版本需要重启游戏**。
* 实机验证状态：**v1.0 已实机跑通**；v1.0.1 是写入保护与 cfg 边界的加固（写入路径未变），实机复验完成。
## Logs · 日志
```text
%LOCALAPPDATA%\CowboyBingus\Helldivers2\Logs\GuardDogLoadout.log
%LOCALAPPDATA%\CowboyBingus\Helldivers2\Logs\GuardDogLoadout_STATUS.log
%LOCALAPPDATA%\CowboyBingus\Helldivers2\Logs\HD2Scanner.log
```