安装指南

安装指南

核心目录概念

需要了解以下四个概念。

  1. 根目录（root directory）。
    • 存放 UE4SS DLL 文件的目录。
  2. 工作目录（working directory）。
    • 存放配置和 Mod 文件，位于根目录内。
  3. 游戏目录（game directory）。
    • 通常包含一个以游戏命名的小型可执行文件和一个同名文件夹。
    • 这个可执行文件并非真正的游戏程序，而是一个小型启动包装程序：先启动 Steam 等第三方启动器；如果没有第三方启动器，则启动真正的游戏可执行文件。
    • 示例：D:\Games\Epic Games\SatisfactoryEarlyAccess\。
  4. 游戏可执行文件目录（game executable directory）。
    • 存放真正的游戏可执行文件，不属于 UE4SS 的目录结构。
    • 其中的游戏可执行文件通常体积最大，远大于上述包装程序；游戏运行时，它作为包装程序的子进程运行。
    • 示例：D:\Games\Epic Games\SatisfactoryEarlyAccess\FactoryGame\Binaries\Win64\。

选择安装方式

UE4SS 有几种不同的安装方式。目标都是让游戏以某种方式加载 UE4SS 的 DLL，并把配置文件和 \Mods\ 目录放到 UE4SS 能找到的位置。

方式一：基础安装

使用方式一时，根目录和工作目录视为同一个目录，同时也是游戏可执行文件目录。

基础安装适合使用依赖 UE4SS 的 Mod、但不需要开发的最终用户。采用这种方式时，不应出现额外窗口。

推荐且最直接的做法是下载 UE4SS_v{version_number}（例如 UE4SS_v3.0.0），把所需文件全部拖放到游戏可执行文件目录。

随后启动游戏，UE4SS 就会自动注入。

方式二：开发者安装

使用方式二时，根目录和工作目录视为同一个目录，同时也是游戏可执行文件目录。

开发者安装适合 Mod 开发者，以及希望使用 UE4SS 进行调试、转储等操作的用户。与基础版相比，此版本包含一些额外文件，UE4SS-settings.ini 中的默认设置也略有不同，例如默认显示控制台和 GUI 控制台。

推荐且最直接的做法是下载 zDEV-UE4SS_v{version_number}（例如 zDEV-UE4SS_v3.0.0），把所需文件全部拖放到游戏可执行文件目录。

随后启动游戏，UE4SS 就会自动注入。

实验版安装

如果希望使用最新功能，并能接受比正式版更多的潜在问题，可以前往实验版发布页。该版本会随主分支的每次提交自动更新。

实验版发布中包含许多旧文件，需要根据发布日期寻找最新下载项。

主要有基础版（basic）和开发版（dev）两种包。命名格式与上面类似，但版本号末尾附加 -提交次数-提交哈希。例如基础版可能为 UE4SS_v3.0.0-5-ga5e818e.zip，开发版可能为 zDEV-UE4SS_v3.0.0-5-ga5e818e.zip。

注意： 使用实验版进行开发时，应阅读开发版文档。可以在 docs.ue4ss.com 后添加 /dev，例如本页的开发版地址为 https://docs.ue4ss.com/dev/installation-guide。

覆盖安装位置

可以在保持代理注入可用的同时覆盖根目录位置。

在游戏可执行文件目录中，与 dwmapi.dll 同级创建 override.txt，写入新 UE4SS.dll 位置的绝对路径或相对路径。

例如：

  • C:/ue4ss/
  • ../../Content/Paks

通过命令行覆盖路径

也可以使用命令行参数指定 UE4SS.dll 的自定义路径，其优先级高于 override.txt。

启动游戏时使用 --ue4ss-path 参数：

game.exe --ue4ss-path "C:\custom\path\to\UE4SS.dll"

支持绝对路径和相对路径。相对路径以游戏可执行文件目录为基准解析：

game.exe --ue4ss-path "dev\builds\UE4SS.dll"

特别适用于：

  • 开发者在不修改文件的情况下测试不同的 RE-UE4SS 构建。
  • 快速切换 RE-UE4SS 版本。
  • 使用不同配置进行自动化测试。

加载优先级：

  1. --ue4ss-path 命令行参数（最高）。
  2. override.txt 文件。
  3. <game executable directory>/ue4ss/UE4SS.dll。
  4. <game executable directory>/UE4SS.dll（最低）。

手动注入

手动注入时，根目录和工作目录视为同一个目录，也可以与游戏可执行文件目录相同，但实际可使用任意目录。

下载基础版或开发版（稳定版或实验版均可）后，删除 dwmapi.dll。随后启动游戏，使用自己选择的注入器手动注入 UE4SS.dll。

通过手动注入集中安装

这种方式可以让所有游戏共用同一个 UE4SS 安装位置。把所选 ZIP 包（基础版或开发版）解压到游戏目录以外的任意目录，该目录称为根目录。

然后在其中创建一个以游戏命名的文件夹，把 UE4SS-settings.ini 放入该文件夹；该文件夹就是工作目录。

假设游戏可执行文件路径为：

D:\Games\Epic Games\SatisfactoryEarlyAccess\FactoryGame\Binaries\Win64\FactoryGame-Win64-Shipping.exe

则工作目录名应为 SatisfactoryEarlyAccess。如果该目录存在，UE4SS 会自动找到并使用它。

工作目录包含以下文件和文件夹：

  • Mods
    • Mod 文件夹
    • mods.txt
  • UE4SS-settings.ini
  • UE4SS.log
  • UE4SS.dll
  • 其他可选的辅助文件；它们不是 UE4SS 正常运行的必需项。

dwmapi.dll 则位于游戏可执行文件目录中；它也可以使用游戏引擎或其依赖会加载的其他 DLL 名称。

随后启动游戏，并让所选注入器指向 <root directory>/UE4SS.dll。

使用这种方式时，可以在根目录保留一份 UE4SS-settings.ini。只要注入器仍指向根目录，对于没有单独工作目录的游戏，这份配置就会作为默认配置使用。

因此，大多数游戏可以采用集中安装，同时让其他游戏继续使用方式一或方式二。

验证 UE4SS 是否成功运行

可以尝试以下任意方式：

  • 按默认快捷键（例如 @ 或 F10），通过内置的 ConsoleEnablerMod 打开游戏内控制台。
  • 检查 UE4SS 主 DLL 所在文件夹中是否生成 UE4SS.log，并确认日志时间戳是最新的且没有错误。
  • 在 UE4SS-settings.ini 中启用 GUI 控制台，确认它以独立窗口出现（默认使用 OpenGL 渲染）。
  • 开发者在确认游戏可安全调试的前提下，可以在调试器中检查 UE4SS 库是否已加载，以及线程是否在目标游戏进程中创建并处于合理状态。

配置

安装后，通过 UE4SS-settings.ini 配置 RE-UE4SS。

命令行选项

通过代理 DLL 安装时，支持以下命令行选项：

  • --disable-ue4ss：使用此参数启动游戏，可临时禁用 RE-UE4SS，无需卸载。
  • --ue4ss-path <path>：指定 UE4SS.dll 的绝对或相对路径，适合在不修改安装文件的情况下测试不同构建。

多个 Mod 目录

可以在 UE4SS-settings.ini 中配置从多个目录加载 Mod：

[Overrides]
; Add additional mods directories with + prefix, remove with - prefix
+ModsFolderPaths = ../SharedMods
+ModsFolderPaths = C:/MyMods
-ModsFolderPaths = ../SharedMods

上述配置以 + 前缀添加目录，以 - 前缀移除目录。INI 路径按照出现顺序处理，最后一项优先级最高。

也可以使用 UE4SS_MODS_PATHS 环境变量，以分号分隔路径：

set UE4SS_MODS_PATHS=C:\SharedMods;D:\GameMods;E:\TestMods

环境变量路径按逆序处理，第一项优先级最高。INI 和环境变量中的路径均支持相对路径、绝对路径以及符号链接。

控制 Mod 列表

默认情况下，UE4SS 会解析每个 Mod 目录中的 mods.txt。可以改为只使用一个控制全局的 mods.txt：

[Overrides]
; Path to a specific mods.txt file to use as the controlling mod list.
; If set, ONLY this mods.txt will be parsed instead of mods.txt from all mod directories.
; Can be relative to working directory or an absolute path.
ControllingModsTxt = ../MyModsList/mods.txt

ControllingModsTxt 指定控制列表路径；一旦设置，就只解析此文件。路径可以是相对于工作目录的路径，也可以是绝对路径。

适用场景：

  • 集中管理多个 Mod 目录的加载顺序。
  • 多个游戏安装共用配置。
  • 将 Mod 列表与 Mod 文件分开纳入版本控制。

ControllingModsTxt 为空时（默认值），UE4SS 会解析所有已配置 Mod 目录中的 mods.txt。

原文：docs/installation-guide.md · 固定提交 560411f18512 · 来源与 MIT 许可