REFramework 实战指南：5 分钟跑通游戏内菜单 + 第一个 Lua 脚本与 C++ 插件

【免费下载链接】REFrameworkMod loader, scripting platform, and VR support for all RE Engine games项目地址: https://gitcode.com/GitHub_Trending/re/REFramework

REFramework 是面向 RE 引擎游戏的 Mod 框架，集 mod 加载、Lua 脚本、C++ 插件与 VR 支持于一体。读完本文，你能按 Insert 呼出游戏内菜单、跑通第一个 Lua 脚本，并编译加载自己的 C++ 插件。唯一前提是 Windows 游戏客户端。

它到底是什么：RE 引擎游戏的一体化 Mod 加载器

• dinput8.dll 注入：本体是一个伪装成 DirectInput 的 DLL，丢进游戏目录即注入，DX11/DX12 均支持
• ImGui 游戏内菜单：注入后接管渲染钩子，所有内置 mod、脚本面板、插件都挂在同一菜单下
• Lua 脚本平台：内置 sol2 沙箱，re回调表 +sdk对象表，直接操作游戏托管对象
• C++ 插件与 VR：启动时扫描目录自动LoadLibrary插件 DLL，VR 用户解压整包即可用

支持范围覆盖《生化危机 2/3/4/7/Village/Requiem》《鬼泣 5》《街霸 6》《怪物猎人 Rise/Wilds/Stories 3》《龙之信条 2》等，完整列表见 README.md。

动手之前：dinput8.dll 该放哪

运行环境：Windows + Steam 游戏客户端，无需反编译、不修改游戏本体文件。

获取：从 Releases 页下载稳定版 zip（想要新特性用 Nightly 开发版）。

• 非 VR 用户：只解压dinput8.dll一个文件，放到游戏根目录（与主.exe同级）
• VR 用户：先装 SteamVR（OpenXR 设备除外），整个 zip 解压到对应游戏目录

确认装好：进游戏按Insert（默认菜单键，可在菜单里改），弹出覆盖窗口即成功。Linux/Proton 用户在 Steam 启动选项加WINEDLLOVERRIDES="dinput8.dll=n,b"。

5 分钟跑通游戏内菜单：最小可行体验

1. dinput8.dll放进游戏根目录，正常启动游戏
2. 进入主界面后按Insert
3. 观察弹出的覆盖窗口

成功判定：窗口分区列出 Script Runner、各内置 mod（Free Camera、Scene Timescale、FOV、First Person 等）与 VR 设置。看到即注入成功，这是后续一切操作的入口。

内置 mod 即装即用：Free Camera 全游戏通用；First Person、Manual Flashlight 限特定作品；开发者构建下还有 Game Objects Display 和 Object Explorer 两个工具。

核心工作流：从加载脚本到拿到游戏对象

跑通第一个 Lua 脚本

打开菜单里的 Script Runner 区块，Run script弹出文件选择框，选中任意.lua立即执行；Reset scripts卸载全部；Spawn Debug Console弹调试控制台。加载后 Known scripts 区列出复选框，可随时单独开关。

判定标准：面板 Last Script Error 为空，脚本出现在 Known scripts 勾选列表中。

仓库 scripts/ 是现成参考（按re2_xxx.lua、re4_xxx.lua区分游戏）。注意脚本有加载时机：框架等场景就绪才加载，日志出现Scene and scene manager found. Loading scripts...才算真正开始。

写一个自己的 re.on_frame 回调

re.on_frame注册每帧执行的函数，re.msg输出会显示在菜单里。新建my_first.lua放进reframework/autorun/持久目录（或手动Run script加载）：

-- 顶部缓存方法指针，别在每帧里重复查找 local get_go = sdk.find_type_definition("via.Component"):get_method("get_GameObject") re.on_frame(function() local cam = sdk.get_primary_camera() if cam then re.msg("找到主相机: " .. tostring(get_go(cam))) end end)

判定标准：菜单里每帧刷出相机信息，说明回调链路已挂上。

用 sdk 拿到游戏对象

sdk表是操作游戏托管对象的统一入口：find_type_definition("类型全名")拿类型，:get_method("方法名")拿方法再调用；sdk.game_namespace帮你补全游戏命名空间。scripts/re2_smooth_movement.lua 是完整范例——它获取角色 Transform 与 Joint 并改写，实现平滑移动：

local re2 = require("utility/RE2") -- 仓库自带工具库，直接拿玩家对象 local get_transform = sdk.find_type_definition("via.GameObject"):get_method("get_Transform") local get_position = sdk.find_type_definition("via.Transform"):get_method("get_Position") re.msg("玩家位置: " .. tostring(get_position(get_transform(re2.player))))

require能解析utility/RE2这类相对路径，工具库在 scripts/utility/，跨游戏通用。判定标准：日志打出三维坐标，"类型 → 方法 → 对象"整条链路即通。

进阶：编译并加载你的第一个 C++ 插件

想做 Lua 之外的事（自定义 hook、直连渲染后端、独立 Lua 沙箱），就写 C++ 插件。

1. 装 Visual Studio 2022（C++23）+ CMake，完整细节见 COMPILING.md
2. 拉取仓库与依赖：

git clone https://gitcode.com/GitHub_Trending/re/REFramework cd REFramework git submodule update --init --recursive

3. 只构建你玩的游戏目标，避免全量编译几十分钟：

cmake --build build --config Release --target RE2

4. 通读 examples/example_plugin/：Plugin.hpp声明版本与生命周期回调，Plugin.cpp实现 ImGui 初始化、D3D11/D3D12 双后端接入，并用API::get()->param()->functions->create_script_state()创建独立 Lua state 沙箱
5. 把编译出的 DLL 丢进持久目录下reframework/plugins/（文件名即插件名），重启游戏——启动时框架自动扫描该目录加载每一个.dll

判定标准：重启后菜单正常，日志无[Plugin] error，插件区列出 Loaded plugins。

C++ 插件 API 的准确定义看 include/reframework/ 头文件，另有一个更小的实战示例 examples/weapon_stay_big_plugin/ 可参考。

避坑：REFramework 脚本常见坑与性能调优

• 在线匹配下脚本整体卸载：面板提示Online match detected，单机模式才生效，这是设计行为不是 bug
• DLL 放错位置：dinput8.dll必须与主程序同级；VR 用户只放一个 dll 也会"看起来没生效"
• os库被沙箱裁剪：os.remove / execute / getenv等全部置空，删文件、跑命令改用fs绑定
• 误判脚本没生效：先看日志是否出现Loading scripts...，场景没就绪前脚本根本没跑

性能：re.on_frame回调只做增量计算，get_method方法指针在脚本顶部取一次并缓存，别每帧find_type_definition。Script Runner 面板的 Garbage Collection Stats 实时显示 MB 占用，数值稳定不再上涨，说明回收策略已调好。

资源索引与你的下一步

• C++ 插件骨架：examples/example_plugin/
• Lua 实战脚本：scripts/
• 跨游戏工具库：scripts/utility/
• 编译指南：COMPILING.md
• 插件 API 头文件：include/reframework/

下一步动手

1. 用 Script Runner 把 scripts/re2_smooth_movement.lua 加载进 RE2，移动角色观察画面，再Reset scripts卸载，对比两者差异
2. 照re.on_frame例子改一版：把主相机换成玩家对象，用计数器控制每 60 帧打印一次位置，体会"回调 + 节流"写法
3. 编译 examples/example_plugin/，产物丢进reframework/plugins/，重启确认菜单正常——你就完成了从源码到插件的完整闭环

【免费下载链接】REFrameworkMod loader, scripting platform, and VR support for all RE Engine games项目地址: https://gitcode.com/GitHub_Trending/re/REFramework