abix-/modforge
GitHub: abix-/modforge
跨引擎游戏 Mod 开发框架，提供 UE5/Unity/原生PE 三种宿主环境的统一 Rust 开发基础设施，内置内存操作、Hook、热重载和二进制反编译能力。
Stars: 0 | Forks: 0
# modforge
一个用于游戏 Mod 的 Rust 工作空间。包含一个基础 crate
(**`modforge`**)，两个将其适配到特定宿主运行时（UE5、Unity）
的引擎绑定“forge” crate，以及直接或通过 forge 消费
modforge 的单游戏 mod crate。
```
┌────────────────────────────┐
│ modforge │
│ HTTP server · op registry │
│ selector grammar · RPG │
│ log · scanner · winproc │
│ shutdown · settings │
└─────────────┬──────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
┌────▼────┐ ┌─────▼─────┐ (no engine; per-game
│ ueforge │ │unityforge │ crate consumes modforge
│ UE5 │ │ Unity │ directly with its own
│ UE4SS │ │ Mono / │ loader, e.g. PE inject)
│ │ │ IL2CPP │
└────┬────┘ └─────┬─────┘
│ │
┌─────┴─────────┐ ┌─────┴─────────┐ ┌──────────────┐
│ grounded2-mod │ │ wwm-mod │ │ horsey-mod │
│ outworld- │ │ il2cpp-smoke │ │ (Horsey Game,│
│ station-mod │ │ │ │ PE inject) │
│ │ │ │ │ │
└───────────────┘ └───────────────┘ └──────────────┘
```
“引擎 forge”是可复用的：任何 UE5 游戏都建立在 ueforge 之上，
任何 Unity 游戏都建立在 unityforge 之上。原生 PE 游戏没有
托管加载器可依靠，因此其单游戏 crate 携带它
自己的注入器 + 特定游戏的访问器，并直接消费 modforge。
第一个此类 crate 是 `horsey-mod` (Horsey Game)。
如果出现第二个原生 PE 游戏，horsey-mod 中的
`inject + HTTP-bind + binary-patch` 模式将被提取到
一个共享的 `modforge::inject` 模块中；在那
之前，它留在被使用的地方。
## modforge. 基础
所有与游戏无关的内容都在这里：localhost HTTP 控制平面、
操作注册表、允许操作按名称寻址运行中进程状态的选择器语法、RPG 模块
（`Effect` / `Trigger` / `Skill`）、扫描器（类型化内存
读取 / 写入 / 特征码扫描）、winproc 辅助工具（模块
基址、地址重定位、VirtualProtect）、按行刷新的
日志、关闭注册表和设置文件加载器。
## 两个引擎 forge
引擎 forge 是一个轻量的 crate，它将 modforge 绑定到一个
宿主*引擎*运行时，并仅提供特定于引擎的
机制。任何建立在该引擎上的游戏都位于其之上。
### ueforge. UE5 / UE4SS
第一个 forge。拥有 UE SDK shim（UObject / UClass /
UFunction / GObjects / TypedField）、`ue4ss_mod!` 宏、
C++ shim、带有关闭时按 hook 清理的 ProcessEvent vtable hook、ImGui 绑定、热重载（阶段 A + B）以及
五个定制化 mod 形状模块：
| 模块 | 你针对每个游戏编写的内容 |
|------------|-----------------------------------------------------|
| RPG | 一个 `Skill` 行的目录。十分之九的通用形状由 `StandardEffect` 覆盖。 |
| Stacks | `StackTweak::new(table, offset, default_mult, skip)` |
| Difficulty | 每个 knob 的 `DifficultyKnob::new(class, offset)` |
| Inventory | `ViewportBinder` trait 实现 |
| Damage | `DamageBinder` trait 实现 |
测试框架：`ueforge::client::{research, diff, scenario}`
将测试样板代码简化为 Pester 风格的单行代码。
参见 [`ueforge/README.md`](ueforge/README.md)。
### unityforge. Unity (Mono + IL2CPP)
通过 BepInEx 加载的
`Unityforge.Shim.{Mono,Il2Cpp}.dll` C# shim 将 modforge 绑定到 Unity 游戏中，该 shim 会执行 LoadLibrary 加载
单游戏 Rust cdylib，并分派逐帧的 Update +
生成版本化的热重载。提供了一个 Mono 桥接
（对已加载程序集的反射、Harmony 补丁、
GameObject / Component / 字段访问）、一个 IL2CPP 桥接和一个
Unity 侧的 Input 桥接。生成版本化的热重载
（从不执行 `FreeLibrary`；每次重载都是对一个
新命名的 gen 文件执行 `LoadLibrary`）避免了 FreeLibrary 崩溃类问题。
参见 [`unityforge/`](unityforge/) 和 [`docs/unityforge-plan.md`](docs/unityforge-plan.md)。
## 游戏侧 Mod
| Crate | 游戏 | 绑定方式 | 功能描述 |
|---------------------------|-------------------|--------------|------------------------------------------------------------------------------|
| `grounded2-mod` | Grounded 2 | ueforge | 异星工厂风格的 RPG / 升级。13 项技能，目标约 25 项。 |
| `outworld-station-mod` | Outworld Station | ueforge | 堆叠大小调整 (DT_Materials.MaxCanStack 倍数)。在第二款 UE5 游戏上验证了 ueforge。 |
| `wwm-mod` | Wild West Miner | unityforge | RPG / 升级 + 演示结束阻挡 (TutorialManager.CompleteDemo 前缀)。Mono。 |
| `il2cpp-smoke` | (冒烟测试目标) | unityforge | 在发布真正的 IL2CPP 游戏 mod 之前对 IL2CPP 路径进行端到端测试。 |
| `horsey-mod` | Horsey Game | modforge (PE 注入) | 作弊 + 研究界面。睡眠安全的疲劳抑制器、金钱/年份/马匹操作、调试模式解锁。自带独立的注入器 EXE。 |
`horsey-mod` 是个例外：Horsey Game 没有
第三方插件加载器，因此该 crate 直接消费 modforge
并提供一个小型注入器 EXE，该 EXE 向正在运行的
进程执行 `CreateRemoteThread` 调用 `LoadLibraryW`。它还拥有二进制补丁基础设施
（VirtualProtect / 写入 / FlushInstructionCache /
分离时还原）以及通过带时间戳的暂存 DLL 进行的热重载
（cargo 的输出绝不是游戏已加载的文件，因此
它永远不会被锁定）。所有内容都是 Horsey 特有的。参见
[`horsey-mod/README.md`](horsey-mod/README.md) 和
[`horsey-mod/research/`](horsey-mod/research/) 获取有关 Horsey Game 的研究。
单游戏研究笔记：
- [`grounded2-mod/docs/`](grounded2-mod/docs/). 伤害
内部机制（战斗 / 坠落 / 环境）、物品栏、
目录、持久化。
- [`docs/wild-west-miner-research.md`](docs/wild-west-miner-research.md)。
Wild West Miner 托管侧研究日志。
- [`horsey-mod/research/`](horsey-mod/research/). Horsey Game 反编译
+ 函数注释 + 逆向工程笔记（子树合并自
前 `horsey-mods` 仓库）。
## 研究工具
### decomp. 二进制到 Rust 的输出后端（探索性存档）
基于 [r2sleigh](https://github.com/radareorg/r2sleigh)（
radare2 组织的基于 SLEIGH 的纯 Rust 反编译器栈，具有
完整的 x86-64 支持、SSA 流水线、真正的结构化器、类型
推断）。遍历 r2sleigh 的公开 `r2dec::ast::CFunction`
并生成供人类阅读的 `unsafe fn` 形状的 Rust 伪代码。
命令行：`decomp print --addr 0xADDR` / `batch` / `dump-il`。
从 Ghidra 的 INDEX.md 以及 key-funcs/文件名标识中恢复的名称。示例输出：
```
pub unsafe fn price_or_score_formula(arg1: i64, arg2: i64) {
rbx = fn_1400285e0();
fn_1400ca670();
ecx = *(fn_1400285e0() + 596_i64);
*(fn_1400285e0() + 596_i64) = *(rcx + 596_i64) + 1_i64;
...
}
```
在
[`horsey-mod/research/decompiled/rust-r2sleigh/`](horsey-mod/research/decompiled/rust-r2sleigh/)
提供的示例产物：
18 个已文档化的 Horsey 关键函数中有 13 个恢复了友好名称。
**构建：** 仅限 WSL（libsla-sys 的 Ghidra C++ 源码需要
Windows MSVC 兼容性工作；参见
[`decomp/docs/polish-ladder.md`](decomp/docs/polish-ladder.md)
第 1 项）。出于相同原因，decomp 故意尚未成为 cargo 工作空间的
成员。将 r2sleigh 作为同级目录克隆，在 WSL 中执行 `cargo build --release`。
参见 [`decomp/README.md`](decomp/README.md) 获取
单页介绍，以及 [`decomp/docs/`](decomp/docs/) 获取
进阶路线图。
#### 历史：falcon-printer（已于 2026-05-14 停用）
`decomp/` 取代了 [`falcon-printer/`](falcon-printer/)，
这个原型教会了我们需要哪些遍历操作。已停用
crate 的文档保留在
[`falcon-printer/docs/`](falcon-printer/docs/)（策略
迁移计划、生态调查、中间端遍历操作详解、架构）。Cargo.toml + src/ 已
删除；git 历史即为存档。
## 仓库布局
```
.
+- modforge/ -- the foundation crate
+- ueforge/ -- UE5 / UE4SS forge (60+ submodules, 5 modules)
+- unityforge/ -- Unity Mono + IL2CPP forge (with C# shim)
+- grounded2-mod/ -- Grounded 2 RPG / level-up mod (ueforge)
+- outworld-station-mod/ -- Outworld Station mod (ueforge)
+- wwm-mod/ -- Wild West Miner mod (unityforge / Mono)
+- il2cpp-smoke/ -- IL2CPP smoke target (unityforge / IL2CPP)
+- horsey-mod/ -- Horsey Game mod (PE inject; modforge directly)
+- horsey-mod/research/ -- Horsey Game research (decomp, RE notes, plans)
+- decomp/ -- Binary-to-Rust decompiler (r2sleigh-based; WSL-only)
+- falcon-printer/ -- prototype that decomp replaces; archive (docs only)
+- docs/ -- workspace-level (todo, changelog, research)
+- Cargo.toml -- workspace manifest
+- README.md -- this file
```
每个 crate 的文档位于该 crate 的 `docs/` 文件夹中。
## 安装 (每个游戏)
每个游戏侧的 mod 都有自己的部署命令：
```
# Grounded 2 (UE5 / UE4SS)
cargo deploy install -p grounded2-mod
# Outworld Station (UE5 / UE4SS)
cargo deploy install -p outworld-station-mod
# Wild West Miner (Unity Mono / BepInEx)
wwm-mod/scripts/build_and_deploy.ps1
# Horsey Game (native PE / 注入)
cargo build -p horsey-mod --release
target/x86_64-pc-windows-msvc/release/horsey-inject.exe \
--dll target/x86_64-pc-windows-msvc/release/horsey.dll
```
`cargo deploy install -p `（针对 ueforge 模块）
通过 crate 的 `Cargo.toml` 中的
`[package.metadata.ueforge]` 配置自动检测 Steam 安装路径，
将 DLL + 默认的 `settings.json` 复制到
UE4SS 的 `Mods/` 目录中，并在
`mods.txt` 中注册该 mod。
对于 Vortex 打包：`cargo deploy package -p ` 会在 `dist/` 中生成
可供 Vortex 安装的 zip 文件。
### 热重载
每个 forge 都有自己的热重载机制：
- **ueforge**：在 UE4SS 内部按 Ctrl+R。框架会在 `on_shutdown` 期间替换
side-file（`main-new.dll`）；
UE4SS 重新加载新镜像。Hook 拆卸 + 线程 join +
vtable 还原均由框架端处理。磁盘上的
状态得以保留。
- **unityforge**：生成版本化。运行
`wwm-mod/scripts/build_and_deploy.ps1 -Hot` 以暂存一个新的
`*.unityforge.gen.dll`。C# shim 的每秒监视器
会检测到它并执行 `HotSwap`。旧生成进入静默状态（其
代码保持映射状态）；从不执行 `FreeLibrary`。
- **horsey-mod**：`horsey-inject.exe --reload`。POSTs
`_shutdown` 以释放监听器，对旧的 HMODULE `CreateRemoteThread` 调用
`FreeLibrary`，删除旧的暂存
文件，将新构建暂存到一个新的带时间戳的路径，
并加载它。
## 状态 (2026-05-14)
- **modforge**：基础 crate 稳定。具有
`SO_REUSEADDR` 的服务器（热重载交换绑定正常）、op 注册表、
选择器语法、RPG 原语、扫描器、关闭
注册表、设置。
- **ueforge**：发布了五个框架模块（rpg / stacks /
difficulty / inventory / damage），热重载（阶段 A + B）
完成，Pester 风格的测试 DSL 完成。
- **unityforge**：生成版本化的热重载已构建并
部署（阶段 4）。Mono + IL2CPP shim。
`HarmonyBridge.PatchPrefix/Postfix` 已知存在问题（已排入
修复计划）；Mono `MonoBridge.ListMethods` 已发布（+ ABI v4）。
- **horsey-mod** (Horsey Game mod，PE 注入)：注入器 +
HTTP 控制平面已发布，热重载正常工作，
默认的 `no_tire` 被拆分标志的疲劳
抑制器取代（在不破坏睡眠的情况下符合比赛条件）。
二进制补丁基础设施落地；第一个补丁
（`sleep_safe_no_tire`）开发中（特征码扫描消歧器
尚未解决）。
- **grounded2-mod**：13 项技能实装，包括伤害 hook 中的 Lifesteal。已针对 Grounded 2 Steam 构建
`++Augusta+release-0.4.0.2-CL-2673661` 进行测试。
- **outworld-station-mod**：堆叠调整已发布。
- **wwm-mod**：演示结束阻挡已发布（针对
`TutorialManager.CompleteDemo` 的 Harmony 前缀）；在
Harmony 桥接修复期间，RPG 侧暂停。
待办工作在 [`docs/todo.md`](docs/todo.md) 中按
影响力排序追踪。里程碑时间线记录在
[`docs/changelog.md`](docs/changelog.md) 中。
## 构建前提条件
- Windows 10/11 x64
- Rust 工具链（rustup；通过 `rust-toolchain.toml` 固定 stable 版本）
- Visual Studio Build Tools 2022+ 及 C++ 工作负载
- 对于 ueforge 模块：目标游戏的 UE4SS 安装
- 对于 unityforge 模块：目标游戏的 BepInEx 安装
- 对于框架开发：使用 `--recurse-submodules` 克隆。Dear
ImGui v1.92.1 位于一个子模块中。
## 文档
工作空间级别（待办工作 + 时间线）位于根目录：
- [`docs/README.md`](docs/README.md). 工作空间文档索引
- [`docs/todo.md`](docs/todo.md). 所有 crate 的待办工作
- [`docs/changelog.md`](docs/changelog.md). 里程碑，按最新排序
- [`docs/unityforge.md`](docs/unityforge-plan.md). unityforge
架构计划（阶段 1-4）
- [`docs/wild-west-miner-research.md`](docs/wild-west-miner-research.md).
Wild West Miner 托管侧研究日志
每个 crate 的文档：
- [`ueforge/README.md`](ueforge/README.md) + [`ueforge/docs/`](ueforge/docs/).
- [`unityforge/`](unityforge/).
- [`horsey-mod/README.md`](horsey-mod/README.md).
- [`grounded2-mod/docs/`](grounded2-mod/docs/).
- [`decomp/README.md`](decomp/README.md) + [`decomp/docs/`](decomp/docs/). 活跃的二进制到 Rust 逆向工程工具（基于 r2sleigh）。
- [`falcon-printer/`](falcon-printer/). 已停用的原型，被 decomp 取代；文档作为历史存档保留。
- [`horsey-mod/research/`](horsey-mod/research/). Horsey Game 研究笔记。
## 鸣谢
- **UE4SS-RE** 提供 [RE-UE4SS](https://github.com/UE4SS-RE/RE-UE4SS)，
这是此处每个 UE5 mod 所目标的 CPPMod 宿主。
- **BepInEx** 提供 unityforge 所附加的
Unity 插件加载器。
- **HarmonyX** 提供 unityforge
C# shim 所使用的运行时补丁库。
- **x0reaxeax** 提供 [Grounded2Minimal](https://github.com/x0reaxeax/Grounded2Minimal)
和 [G2Dumper](https://github.com/x0reaxeax/G2Dumper)。
- **Encryqed** 提供 [Dumper-7](https://github.com/Encryqed/Dumper-7)，
这是为我们所针对的每个 UE5 游戏生成
参考头文件的 SDK 生成器。
- **RLGingerBiscuit** 提供 [G2Utils](https://github.com/RLGingerBiscuit/G2Utils)，
它印证了 Grounded 2 上的类名 + 物品栏绑定。
- **Trumank** 提供 [retoc](https://github.com/trumank/retoc) 和
[repak](https://github.com/trumank/repak)，在早期的
pak 原型工作中使用。
- **4sval** 提供 [FModel](https://github.com/4sval/FModel)，用于
烘焙资产检查。
- **Caites** 提供 Nexus 上的 [Player Tweaks](https://www.nexusmods.com/grounded2/mods/13)
，其功能列表塑造了 Grounded 2 的目录。
- [Bigger Backpack](https://www.nexusmods.com/grounded2/mods/37) 的作者，
其 mod 的损坏促使了数据侧 + 可见侧
补丁模式的形成。
- Factorio 的 [**RPG System**](https://mods.factorio.com/mod/RPGsystem)
的作者。这是引人注目的 RPG 风格升级 mod，`grounded2-mod` 和 `wwm-mod` 直接借用了它的词汇。
- [**RimWorld RPG Mod / Combat Skills RPG**](https://steamcommunity.com/sharedfiles/filedetails/?id=2891939858) 的作者。
- [War3CS / War3FT](https://war3cs2.wiki.gg/)
反恐精英魔兽争霸 mod 系列的作者，其扁平技能目录模式塑造了 RPG 目录的布局。
- 我们制作 mod 的游戏工作室（负责 [Grounded 2](https://grounded2.obsidian.net/) 的
Obsidian Entertainment、
Outworld Station 团队、Wild West Miner 团队和
Horsey Game 团队）。我们仅在公平使用 mod 规范下修改官方游戏
发布的内容；不重新分发任何游戏资产。
标签：C++, DLL注入, Grounded 2, Hacker, hook, Horsey Game, IL2CPP, Mono, Outworld Station, PE注入, Rust, UE4SS, UE5, Unity, Wild West Miner, XML 请求, 内存修改, 内存读写, 可视化界面, 安全开发, 客户端加密, 插件开发, 数据擦除, 模组框架, 流量审计, 游戏Mod, 游戏修改器, 游戏逆向, 网络流量审计, 虚幻引擎5