VOTV-MP/Multivoid
GitHub: VOTV-MP/Multivoid
为 Voices of the Void 游戏开发的非侵入式多人联机合作模组，通过独立 C++ DLL 层在 UE4.27 上实现完整的游戏状态同步。
Stars: 2 | Forks: 0
# Multivoid
| | |
|--|--|
| **当前构建** | `multivoid-0.9.0n-122.dll` — 游戏目标版本 **0.9.0n**，构建号 **b122** |
| **游戏目标版本** | Voices of the Void Alpha **0.9.0n** |
| **状态** | Alpha，预发布阶段 — 开发中可玩，尚无公开构建版本 |
| **玩家数** | 最多 **4** 人（房主 + 3 人） |
| **平台** | Windows · UE4.27 · 局域网 + 互联网 |
| **网站** | [multivoid.dev](https://multivoid.dev) |
## 当前阶段
该项目遵循一个 8 阶段的长期发展轨迹（MTA / gmod 轨迹 — 参见下方的
[路线图](#roadmap)）。我们目前处于 **阶段 1：功能性联机** — 这是一个深度同步阶段，在这个阶段，VOTV 的单人系统被逐一拆解，并在独立的引擎扩展底层架构上实现正确的多人游戏化。多人模式的基础设施（传输层、会话、主服务器、加入/保存 pipeline）已经构建并上线；剩余的阶段 1 工作主要是进行全面的实践验证，以及对剩余尚需同步的游戏系统进行收尾。
## 目前已实现的功能
### 多人模式基础
- **局域网和互联网会话** — 一个房主，最多三个客户端；支持直连 IP 或由官方主服务器支持的内置 **服务器浏览器**（通过信令 + TURN 进行 NAT 穿透）
- **版本标识 + 加入限制** — 大厅会标示其 `game + build`（例如 `0.9.0n b122`）；版本不匹配的端点会在连接前被拒绝并弹出明确提示，而不是在游戏进行中出现不同步。旧版本群组可以永远一起游玩 — 绝不强制更新
- **可见的远程玩家** — 完整的身体、腿部、IK 脚部、玩家专属皮肤、动画移动、布娃娃镜像
- **悬浮的名称标签**（包含昵称 + 实时 ping）、**聊天** 以及系统事件流（加入、离开、活动信息）
- **语音聊天** — 游戏世界内的 3D 空间音效
- **随时加入** — 连接的客户端会接收房主的完整世界状态（存档传输快照），并且 **在活动中途加入是设计上支持的正常情况**：在事件中途、下载中途、驾驶中途或任何中途加入都会由对应系统妥善处理，绝不是“禁止在 X 期间加入”
### 已同步的世界
- **物理道具** — 跨越约 540 种 `Aprop_C` 类别的拾取、拖拽、投掷，包括客户端生成的道具、单次抓取的权限转移，以及在存档和重连后依然存活的跨端点稳定身份标识
- **堆积物和垃圾收集** — 完整的拾取/携带/存放经济循环
- **NPC 和生物** — 由房主模拟，并将姿态流传输给客户端；包括 kerfur 在内的 prop⇄NPC 转换循环以及每个 kerfur 的专属皮肤
- **世界事件** — 计划/故事事件系统会在客户端重播房主观察到的事件，并采用基于单个事件的重复策略
- **天气** — 雨、雪、雾、风、闪电；由房主权威控制（客户端绝不自行生成自己的 RNG — 共享世界的随机性统一由房主拥有）
- **门、灯、开关、键盘密码锁、终端**、睡眠、伤害/危险、世界道具的发展变化（风干、固化、生长 — 由房主控制时间）
### 信号处理 pipeline（VOTV 的核心）
工作站的端到端同步：天线控制与校准 → ping →
信号捕捉 → 下载 → 解码 → 播放控制台 → 驱动器和机架 →
游戏内笔记本电脑（共享可编辑缓冲区、软盘、光盘） → 草地信号数据库。由 Presser 编写的状态、每个维度单一权限，并将控制台的音频反馈通过原生音频接口镜像给观察者。
### 基础设施
- **独立加载器** — `xinput1_3.dll` 代理 + 带版本号的 `multivoid--.dll` payload
- **官方主服务器** — 我们的 VPS 上的一个静态 Rust 二进制文件（大厅列表、更新检查、信令）；更新检查仅供参考，绝不作为强制限制条件
- **紧急停止开关** — 位于 ini 配置文件中，用于紧急锁定发布
## 运行原理
VOTV 运行在 Unreal Engine 4.27 上。该模组是一对单一的 DLL 文件：
```
xinput1_3.dll -- thin proxy loader (Windows auto-loads it next to the .exe)
multivoid-0.9.0n-122.dll -- the mod payload (versioned filename; highest build wins)
```
该 payload 通过 AOB 特征码解析引擎原语（`GUObjectArray` / `GNames` /
`ProcessEvent`），然后通过反射驱动 VOTV 自身的
`UClass` / `UFunction` 机制 — 无需修改资源，无需重新打包 `.pak`，运行时也不需要 UE4SS。在 ProcessEvent 无法察觉的地方（Blueprint 内部分发），字节码级别的 VM 拦截底层架构会捕获这些不可见的动作。
传输层使用 **GameNetworkingSockets**（Valve 的 UDP 库），承载着不可靠的姿态流以及用于事件和状态的可靠有序频道。每台机器本地的 UE 引擎会根据流传输的状态重新推导出动画、物理和渲染效果。房主对世界状态、RNG 和 NPC 模拟拥有绝对控制权；抓取中的道具权限可进行单次转移。
代码库严格按照双层原则进行划分：
- [`src/votv-coop/src/ue_wrap/`](src/votv-coop/src/ue_wrap/) — 引擎封装（反射、偏移量、hooks；不包含任何游戏逻辑）
- [`src/votv-coop/src/coop/`](src/votv-coop/src/coop/) — 游戏玩法/网络层（元素标识、同步通道、会话）
- [`src/votv-coop/src/harness/`](src/votv-coop/src/harness/) — 启动引导 + 自动化测试场景
## 版本控制
版本标识是一对组合：**(游戏版本, 构建号)** — 没有单独的模组 semver。
```
multivoid-0.9.0n-122.dll -> game target 0.9.0n, build 122
```
- **游戏目标版本** (`0.9.0n`) 会在我们适配新的 VOTV 版本时提升（反射偏移量和 BP 布局会随游戏版本而改变）。
- **构建号** (`b122`) 代表通信协议的修订版本 — 每次发布和每次通信格式更改时都会递增。
- **加入兼容性取决于每个大厅内此版本组合的字节级是否完全一致。** 当 VOTV 0.10.0 发布时，我们会立即进行适配，但 0.9.0n 的玩家群组仍可以继续使用旧的构建版本一起游玩 — 绝不强制更新。服务器浏览器会显示每个大厅的版本组合，并在你点击前标示出任何不匹配的情况。
事实来源：[`src/votv-coop/CMakeLists.txt`](src/votv-coop/CMakeLists.txt)
（`VOTVCOOP_GAME_TARGET` + 从 `protocol.h` 解析出的构建号）。
## 快速开始
### 面向玩家
1. 下载发布的文件对：`xinput1_3.dll` + `multivoid--.dll`。
2. 将这两个文件放入游戏可执行文件所在的目录：
`/WindowsNoEditor/VotV/Binaries/Win64/`。
3. 检查 DLL 名称中的游戏版本是否与你的 VOTV 版本相匹配（例如 `multivoid-0.9.0n-122.dll` 对应 VOTV `0.9.0n`）。
4. 正常启动游戏。主菜单中会出现一个 **Multiplayer** 按钮 — 建立一个大厅，或者通过服务器浏览器加入一个大厅（也支持直连 IP）。
无需进行端口转发。
若要卸载，只需删除这两个 DLL 文件。该模组绝对不会触碰游戏本身的文件。
### 面向开发者
要求：Windows 10+，Visual Studio 2019/2022 **Build Tools**（C++ 工作负载），CMake 3.20+，以及一份合法的 Voices of the Void 游戏副本，存放在仓库同级的 `Game_0.9.0n_HOST/` 目录下。
```
# 配置一次：
cmake -B build/votv-coop -S src/votv-coop -G "Visual Studio 16 2019" -A x64
# Build：
cmake --build build/votv-coop --config Release
```
仅供开发者使用的启动器（用于部署最新构建 + 以固定的 role/port 启动游戏 — 玩家绝不会以这种方式运行模组）：
```
./mp_host_game.bat # host, default port 47621
./mp_client_connect.bat # client
```
需要在同一台 PC 上进行测试？请使用同级的 `Game_0.9.0n_CLIENT_1/` 安装目录 — 启动器会自动检测到它。双端点自动化测试框架位于 `tools/` 目录中。
## 生态系统
| 仓库 / 位置 | 内容 |
|--|--|
| [`VOTV-MP/Multivoid`](https://github.com/VOTV-MP/Multivoid) | **当前仓库** — 模组本体 |
| [`VOTV-MP/Multivoid-server`](https://github.com/VOTV-MP/Multivoid-server) | 未来的专用服务器（长期规划 — 路线图第 8 阶段） |
| [`VOTV-MP/Multivoid-wiki`](https://github.com/VOTV-MP/Multivoid-wiki) | 面向用户的文档 |
| [multivoid.dev](https://multivoid.dev) | 项目网站 |
仓库布局：
| 路径 | 内容 |
|--|--|
| [`docs/`](docs/) | 架构、路线图、范围、系统级同步文档、经验记录 |
| [`research/findings/`](research/findings/) | 仅追加的带日期的逆向工程 / 反射 / 设计发现 |
| [`reference/`](reference/) | 内置的只读参考资料 (UE4SS, MTA:SA, MinHook, GNS) |
| [`src/votv-coop/`](src/votv-coop/) | 模组源码 (`ue_wrap` / `coop` / `harness` / `loader` / `ui`) |
| [`tools/`](tools/) | 构建 / 部署 / 启动 / 自动化测试辅助工具 + 主服务器源码 |
| `Game_0.9.0n_HOST*/` | 本地游戏安装目录。**已被 Gitignore 忽略** — 绝不提交 |
## 路线图
按顺序排列的长期发展轨迹（每个阶段都是下一阶段的前提 — 详见
[`docs/ROADMAP.md`](docs/ROADMAP.md))：
| # | 阶段 | 状态 |
|--|--|--|
| 1 | **功能性联机** — 在独立底层架构上对 VOTV 的系统进行深度同步 | **进行中（当前阶段）** |
| 2 | **沙盒模式** — 将 VOTV 的沙盒规则支持为一个显式的、可移植的“模式”层 | 已规划 |
| 3 | **LuaJIT 嵌入** — 覆盖引擎/联机 API 的脚本底层架构 | 已规划 |
| 4 | **Lua API** — 模式规则转移到 Lua；C++ 核心（传输、同步、标识）保持原生 | 已规划 |
| 5 | **资源系统** — 以统一机制实现自定义模式和插件（MTA 形式） | 已规划 |
| 6 | **专用服务器** — 24/7 托管：房主游戏以无头模式运行，无需在线玩家 | 已规划 |
| 7 | **资源基础设施** — 客户端资源下载、沙盒化、公共服务器浏览器 | 已规划 |
| 8 | **原生独立服务器** — MTA 的终极目标：服务器持有状态 + 规则，客户端负责模拟 | 长期规划 |
## 架构
建立在记录于 [`docs/COOP_METHODOLOGY.md`](docs/COOP_METHODOLOGY.md) 的 **八大架构原则** 之上：
1. **不修改原始游戏文件**
2. **引擎扩展范式** — 该模组是一个新的引擎层，而不是一个 patch
3. **并行的类层次结构** — 我们的 `RemotePlayer` 负责管理网络状态；UE 负责渲染
4. **针对性的崩溃修复，而非广泛的抑制**
5. **最小可行子集** — 范围界定是一份不断演进的文档
6. **增强单机版，绝不取而代之** — 联机合作是叠加在单机模式之上的
7. **引擎封装层 vs 游戏玩法/网络层** — 严格的子树划分
8. **妥善处理活动中途加入** — 每条同步通道都定义了其针对延迟加入的处理方案
三条“不妥协”规则指导着日常开发工作：
- **规则 1** — 没有权宜之计，没有快速修复。每次都要从根本上解决问题。
- **规则 2** — 没有迁移负担。旧代码在被替换时立即移除。
- **规则 3** — 独立模组。UE4SS 仅供开发使用；不会在运行时加载。
## 法律声明
这是一个 **仅基于 hook 的独立模组**。它 **不包含 Voices of the Void 的代码或资源**。您必须拥有合法的游戏副本才能使用它。
分发条款与其借用的上游参考资料相同：针对 MinHook 和源自 UE4SS 的反射算法使用 **MIT** 协议。与 VOTV 的作者无关。
### 作者寄语
这个项目是一项出于热爱的免费劳动。我在 2023 年发现了 VOTV，并如痴如醉地玩了它整整几周，从那以后每年我都会回来探索它的全新功能。每一次游玩都是极好的单人体验 — 最终，我希望能与人一起在多人模式下分享这份快乐。
坦白说：我不是一名程序员。或者更确切地说，我是一名程序员 — 只是对于这种规模的项目来说，我的包袱要少得多。我在这里担任的角色是协调员、总监、测试员和架构师。
我一直热衷于模组开发。我的第一批模组是在我 10 岁或 11 岁时为 GTA:SA 制作 — 就像在地图上添加新物体这样的简单内容。后来，我运行过一个带有自定义游戏模式的 SA-MP 服务器，以及几个 Minecraft 服务器，在这个过程中，我逐渐掌握了底层实际运行原理。在某个阶段，我使用 Cheat Engine 深入到了汇编级别的模组开发，在那里学到了一些东西 — 什么是操作码、内存扫描的工作原理等等 — 并以此方式为一些老游戏制作了基础模组。
我从未深入研究过，但事实证明，当我决定与 Fable-5 一起构建这个项目时，这些经验已经足够有用了。
在着手开发之前，我就已经了解了诸如 SA-MP 和 MTA 这样的项目，因此我有了可以借鉴原则和方法论的地方 — 而且我也确实这么做了。如今的 AI 工具确实了不起，将它们与通过 MCP 连接的 IDA 9、正确的方法论，以及分析 Kismet 字节码的 agents 结合在一起，为我提供了所需的开发环境和虚拟团队。
致那些讨厌 AI 或 AI 生成代码的人：如果您将 AI 用于编程并得到了糟糕的结果，那意味着要么是您的过程有问题，要么是您使用的工具太廉价了。换个更好的工具，尝试更好的方法论，并始终记录您的进度。不仅仅是进度 — 记录下一切，每一次会话。并且要规范地记录它们。
Multivoid 是 Alpha 阶段软件。测试前请备份您的存档。欢迎提交 Bug 报告。
标签：Bash脚本, C++, UE4, 可视化界面, 多人联机, 数据擦除, 游戏模组, 网络同步