Within REFramework, Script Runner and Plugins are two separate extension layers. Both let you add functionality on top of a game, but they work at different levels of the engine and are built for different jobs. Understanding which one you actually need matters for stability, performance, and figuring out what broke after a game update.
Script Runner
Script Runner executes Lua based scripts. It is the system most people use for gameplay tweaks and UI overlays, mainly because it is the fastest way to test an idea.
Scripts live in reframework/autorun and use the .lua file extension. Anything placed in that folder loads automatically the next time the game starts, and you can also load a script manually from the REFramework menu if you just want to test it once.
Scripts are interpreted, not compiled. REFramework reads the Lua file and runs its logic continuously while the game is active, calling into the script’s registered callbacks each frame or on whatever event the script hooks into.
A few things define how Script Runner behaves in practice:
Hot reload support. You can edit a script while the game is running and reset it from the REFramework menu without restarting anything. This is the single biggest reason people prefer Lua for anything they are still tuning, since a restart every time you change a number gets old fast.
High compatibility. Scripts talk to the game through REFramework’s own API layer, not directly to game memory. That layer absorbs a lot of the changes that come with minor game patches, so a script written against one patch usually keeps working after the next one, at least for anything that does not depend on very specific internal values.
Performance cost. Because scripts are interpreted at runtime rather than compiled ahead of time, running several complex scripts at once can add noticeable CPU overhead and cost you frame rate, especially on lower end hardware or in already demanding scenes.
Script Runner is the right tool for UI overlays, gameplay adjustments, automation, and most visual tweaks. If you’re not sure which system a mod idea needs, it almost always needs this one first.
Plugins
Plugins sit at a lower level and get direct access to the engine and system resources that Lua scripts simply cannot reach.
Plugins live in reframework/plugins and are compiled .dll files written in native code, typically C++. REFramework loads them into the game process at startup, and from that point on they can interact directly with memory and hook into engine level callbacks, things like per frame rendering events or low level input, that are outside what the scripting API exposes. Under the hood, REFramework uses sol2 to bind its C++ functionality to the Lua environment, which is part of why the scripting API feels consistent even though the underlying engine work happens in C++.
Plugins behave differently from scripts in a few important ways:
Static loading. A plugin cannot be reloaded while the game is running. Any change to the code means recompiling the DLL and restarting the game to load the new version, which makes plugin development noticeably slower to iterate on than Lua scripting.
High performance. Since a plugin is compiled rather than interpreted, it runs with far less overhead than an equivalent Lua script would. For anything performance sensitive, like a rendering hook running every frame, this matters.
Lower stability across updates. Plugins often rely on specific memory layouts and internal structures inside the game. When a game update changes those structures, even slightly, a plugin built against the old layout can stop working or, in the worse case, crash the game outright. This is the trade-off for the deeper access plugins get.
Plugins are the right choice for VR integration, rendering modifications, advanced performance tools, and anything that genuinely needs engine level access rather than what the Lua API already exposes.
Key differences at a glance
| Script Runner | Plugins | |
|---|---|---|
| Location | reframework/autorun | reframework/plugins |
| File format | .lua | .dll |
| Reloading | Supported while the game runs | Requires a full restart |
| Complexity | Easier to write and modify | Requires native programming knowledge |
| Stability across updates | Generally stable | Sensitive to internal changes |
| Access level | Limited to the REFramework API | Direct access to game memory |
Which one should you actually use
Script Runner covers most modding needs. If you’re changing gameplay logic, building a UI overlay, or want something you can tune in real time without restarting the game every few minutes, write it in Lua.
Plugins make sense once you hit something Lua genuinely cannot do: a rendering hook that needs to run before or after a specific engine call, VR camera integration, or a performance tool that needs to sit close to the metal. If you can reach what you need through the sdk or re API that Lua exposes, there is rarely a good reason to compile a DLL for it instead. The faster iteration loop alone is usually worth staying in Lua as long as possible.
Troubleshooting a crash after a game update
When a game update breaks your setup, the fastest way to find out whether the problem is a script or a plugin is to isolate each layer one at a time.
- Remove every file from the
reframework/pluginsfolder and launch the game. - If the game runs correctly at this point, a plugin was the cause. Add plugins back one at a time to find the specific one that broke.
- If the problem is still there, close the game, remove every file from the
reframework/autorunfolder, and launch again. - If the game now runs correctly, a script was the cause. Add scripts back one at a time until the issue reappears.
This process works because it separates the two systems that are most likely to break after an update: plugins because their memory assumptions changed, and scripts because the REFramework API version they expect no longer matches. Testing them independently means you are not guessing which layer to fix.
Conclusion
Script Runner and Plugins solve different problems inside REFramework, and most modding work only ever needs the first one. Lua scripts in reframework/autorun give you a fast, reloadable, reasonably update proof way to change gameplay and UI. Native plugins in reframework/plugins trade that convenience for direct engine access, at the cost of needing a restart for every change and being more fragile when the underlying game updates. Knowing which layer a mod actually depends on makes troubleshooting after a patch far faster, since you already know where to start looking.