# Epic 版 FM27 适配说明（FM Tactics Lab）

适配目标：让 FM Tactics Lab 直接使用 **Epic Games Store 版足球经理 27** 的本地比赛引擎，
不依赖 Steam 客户端登录。

- 源码基线：官方 `v1111.1`（适配构建 `27.0.1+2494687`）
- Epic 游戏路径（示例）：`D:\Epic Games\Guinnessc2uBe`
- 适配状态：**已跑通**——预检通过、整场比赛自然终场、批量推演正常出统计

---

## 一、Epic 版和 Steam 版的差异（实测结论）

| 项目 | 结果 |
| --- | --- |
| 游戏构建号 | 两者都是 `27.0.1+2494687`，逻辑层一致 |
| PE ImageBase | 相同（`0x180000000`） |
| 前 8 个 PE 节区（含 292MB 主代码节 `.data1`） | RVA 与属性完全一致 |
| 91 个关键代码锚点（作者公开的 SHA256 校验） | **68 个逐字节一致** |
| 23 个不一致锚点 | 入口点、TLS 回调、商店胶水代码 |
| 9~10 处 5 字节差异 | 全是 `E9 rel32` 跳转桩（函数体挪位，调用透明） |
| 尾部 5 个节（`.srdata/.reloc/.udata/.shared/.data`） | Epic 版多出约 6MB 商店相关内容，整体后移 |
| 导入表 | 806 个 IAT 条目中 **700 个同址**，其余用 Epic 自己的条目锚定 |
| 宿主的 104 个硬编码调用点 | 仅 9 个落在跳转桩上，其余代码一致；数据引用全部有效 |
| 引擎初始化依赖 | Epic 版主要走 **EOS SDK**（109 个导入符号），Steam API 仅 11 个 |

结论：**同一份游戏代码，只有商店接入层不同**，因此不需要重新逆向战术/AI/比赛逻辑，
只需要换掉"适配契约"和两处商店相关的启动细节。

---

## 二、代码改动（全部共 38 行 diff）

### 1. `native/desktop_host.cpp` —— 激活方式改为由适配契约驱动

Steam 版引擎在 `0x1718f818` 有一个"就绪状态字"，宿主轮询到 0 才继续。
Epic 版的该地址是代码字节（永远非零），因此永远等不到；Epic 版改为调用官方导出的
`WaitForActivation()`（实测 78ms 返回）。

```cpp
if(compat_activation_kind==1){
    auto wait=(void(*)())GetProcAddress((HMODULE)module,compat_activation_export);
    if(wait)wait();
}
auto flag=(volatile unsigned int*)((unsigned char*)module+compat_activation_rva);
for(unsigned i=0;i<100;i++){
    if(compat_activation_kind==1||*flag==0){ ... }
}
```

### 2. `scripts/profile_header.py` —— 契约头文件输出激活配置

新增三项常量：`compat_activation_kind`、`compat_activation_export`、`compat_activation_rva`。
缺省仍是 Steam 的"轮询 `0x1718f818`"，因此不影响原版行为。

### 3. `scripts/build_native_epic.py`（新增）—— Epic 适配 profile 生成 + 编译

流程：

1. 读取本机 Epic 版 `game_plugin.dll`；
2. 用作者公开的 `profile_metadata.json` 做锚点比对：
   - 逐字节一致的锚点 → 原位置保留（保留 Steam 交叉校验意义）；
   - `E9` 跳转桩 → 锚点迁移到跳转目标（新函数体位置）；
   - 商店胶水锚点 → 用 Epic 本地字节重新生成；
3. 入口点/节表/TLS/import 表全部改用 Epic 版自身值；
4. 写入 `private/native/engine_compat_profile.h`、`private/engine/fm27_native/engine_compat_profile.json`、
   `adapter_version.json`；
5. 调用 `cl.exe` 编译 `FM27Simulator.exe`，并立刻执行 `--check-image` 自检。

### 4. `build_epic.bat`（新增）—— 编译入口

手工设置 MSVC + Windows SDK 环境变量（绕过 `vcvars64.bat` 内部调用被拦截的 `reg.exe`），
然后调用上面的脚本。

---

## 三、重新构建与运行

### 构建（游戏更新后需要重做）

```bat
D:
cd \fm-tactics-lab
build_epic.bat
```

成功的标志：

```
check-image: {"event":"native_engine_compatibility","profile":"fm27_epic_2494687_adapter_v1",
              "compatible":true,"trial_allowed":false,"disposition":"verified","warning_count":0,
              "reason":"ok","rva":0,"whole_file_hash_is_gate":false}
```

### 运行

```bat
C:\Users\<你>\AppData\Local\Programs\Python\Python312\python.exe scripts\run.py ^
  --game-root "D:\Epic Games\Guinnessc2uBe" --port 18765
```

浏览器打开 `http://127.0.0.1:18765`。**不需要打开 Steam。**

前置条件（一次性）：

```bat
py -3.12 -m pip install -r requirements.txt
```

私有运行资源已从官方发布包提取到 `private/engine/`（编辑器快照、定位球目录、
`match.pkm` 模拟样本、战术 UI 目录）。

---

## 四、验证记录

| 验证项 | 结果 |
| --- | --- |
| `--check-image` 预检 | `compatible:true / verified` |
| 引擎加载 | `windows_load_returned success:true` |
| 激活 | `native_activation_export found:true, ms:79` |
| 资源归档 | `native_archive_opened success:true` ×2（simatch.fmf / simatchshared.fmf） |
| 资源索引 | `indexed_keys:261`，`xg` 目录 143 条 |
| 引擎 bootstrap | `accepted:true` |
| 整场比赛 | `natural_match_finished full_match_completed:true, tick:22835, score:[1,2]` |
| 确定性 | 相同种子两次运行比分一致 |
| 批量推演（服务层） | 2 场全部有效，`win_rate 0 / draws 2 / goals_for 1.0 / goals_against 1.0` |

---

## 五、已知限制

1. **只接受 Epic 版 DLL**：`FM27Simulator.exe` 内已写入 Epic 契约，Steam 版 DLL 会被预检拒绝。
   如需同时支持两版，可扩展为按 DLL 指纹在多个 profile 中选择。
2. **构建号绑定**：Epic 游戏更新后（构建号变化）需要重新执行 `build_epic.bat`。
3. **仅 Windows x64 + Python 3.12**：与官方源码版限制一致。
4. 存档解析（`fmsave`）走的是同一个 DLL，未单独验证 Epic 存档差异；如遇 `.fm` 读取问题，
   先确认存档版本与工具适配版本一致。

---

## 六、可提交给上游的内容

`epic_patch/` 下是相对官方 `v1111.1` 源码的补丁：

- `desktop_host.patch`：宿主激活方式契约化（22 行 diff）
- `profile_header.patch`：契约头文件输出激活配置（16 行 diff）
- `build_native_epic.py` / `build_epic.bat`：Epic profile 生成与编译入口

建议同时附上本文档与 `--check-image` 输出，作者只需在 Steam 侧回归一次即可合并。
