REFramework: Comprehensive Guide & Documentation

Welcome to the REFramework Dev, your complete resource for learning, troubleshooting, and developing with the REFramework scripting and plugin system.
This documentation is designed to help both new and advanced users make the most of the REFramework tools, APIs, and scripting capabilities.

🧩 Overview

REFramework provides an advanced scripting and plugin environment built around the RE Engine’s IL2CPP implementation, enabling developers to extend and customize game behavior dynamically through Lua scripts and native plugins.

⚙️ Troubleshooting & Support

Reporting Bugs or Crashes

If you encounter technical issues or crashes, please report them on the Issues Page.
To ensure quick and accurate support, always include the following files from your game directory:

re2_framework_log.txt — Upload the entire log file, not just snippets.
reframework_crash.dmp — Include this file if the game is crashing.

Common Issues

My pirated copy doesn’t work

REFramework does not include any anti-piracy measures. However, pirated copies are not supported.
If your version happens to work — great. If not, no additional support or compatibility fixes will be provided.

📜 Lua Scripting System

REFramework includes a powerful Lua scripting system, giving modders and developers fine-grained control over the RE Engine.

Loading Scripts

Manual Loading

Open ScriptRunner from the main REFramework menu.
Click Run Script and select the .lua file you wish to load.

Automatic Loading

Ensure there’s a folder named reframework/autorun in your game directory.
(This is automatically created when REFramework loads.)
Place any .lua scripts inside this folder.
These will automatically load during REFramework initialization.

Handling Lua Errors

During Script Startup

If an error occurs during startup, REFramework displays a MessageBox describing the issue.

During Callback Execution

Runtime Lua errors are logged to the debug log.
You can view them using DebugView, or directly within ScriptRunner in newer nightly builds.

(No MessageBoxes appear here to prevent game lock-ups.)

Finding Game Functions & Fields

The Object Explorer (found under DeveloperTools in the REFramework menu) is your gateway to the game’s internals.

Using ObjectExplorer

Explore the Singletons to find objects and methods of interest.
Obtain them using:
- sdk.get_managed_singleton("name") for Managed Singletons (C#)
- sdk.get_native_singleton("name") for Native Singletons (C++)

Notes

Managed Singletons offer more exposed functionality.
Native Singletons have limited, hand-picked fields and methods.
You can interact with TDB Methods and TDB Fields using the supported getter/setter methods.

Important: Reflection-based methods and properties are not yet supported without direct memory access.

Recommended Starting Points

Start with the sdk and re APIs to get comfortable with the environment.

📚 See Also:

🔌 Plugin System

REFramework supports native DLL plugins, enabling deeper customization beyond Lua’s limitations.
Plugins can access core SDK features and respond to engine callbacks for rendering, input, and game logic.

Loading a Plugin

Simply drop your .dll file into the reframework/plugins directory.
REFramework automatically detects and loads it at startup.

Using the Plugin API

To integrate the REFramework SDK into your plugin:

Include the include directory from the REFramework root project.
For C++ development, include API.hpp for a C++-friendly interface.

You can then export specific functions for versioning, initialization, and callbacks.

Example: Plugin Initialization

extern “C” __declspec(dllexport)
void reframework_plugin_required_version(REFrameworkPluginVersion* version) {
version->major = REFRAMEWORK_PLUGIN_VERSION_MAJOR;
version->minor = REFRAMEWORK_PLUGIN_VERSION_MINOR;
version->patch = REFRAMEWORK_PLUGIN_VERSION_PATCH;
// Optionally restrict compatibility to a specific game
// version->game_name = “MHRISE”;
}

extern “C” __declspec(dllexport)
bool reframework_plugin_initialize(const REFrameworkPluginInitializeParam* param) {
API::initialize(param);
const auto functions = param->functions;

functions->on_lua_state_created(on_lua_state_created);
functions->on_lua_state_destroyed(on_lua_state_destroyed);
functions->on_frame(on_frame);
functions->on_pre_application_entry(“BeginRendering”, on_pre_begin_rendering);
functions->on_post_application_entry(“EndRendering”, on_post_end_rendering);
functions->on_device_reset(on_device_reset);
functions->on_message((REFOnMessageCb)on_message);

API::get()->log_info(“Plugin initialized successfully!”);
return true;
}

Example: Using Native SDK Functionality

auto& api = API::get();
const auto tdb = api->tdb();
auto vm_context = api->get_vm_context();

const auto scene_manager = api->get_native_singleton(“via.SceneManager”);
const auto scene_type = tdb->find_type(“via.SceneManager”);

const auto get_main_view = scene_type->find_method(“get_MainView”);
const auto main_view = get_main_view->call<API::ManagedObject*>(vm_context, scene_manager);

if (main_view) {
float size[3]{};
main_view->call(“get_Size”, &size, vm_context, main_view);
}

Example Plugins

Plugin Headers

REFramework Plugin API Headers

💡 Additional Notes & Best Practices

REFramework APIs are subject to change as the framework evolves.
Lua shares a single state across all scripts — use local variables to avoid conflicts.
Lua scripts can also require native DLLs for extended functionality.
The RE Engine’s IL2CPP differs from Unity’s — Unity tools or IL2CPP utilities will not work here.
Future support for C# scripting may be explored, but is not currently planned.
For object or data-level edits, consider RE_RSZ — it’s more suitable for:
- Adding or cloning game objects
- Making static or startup-time edits
- Layering runtime scripts for extended behavior

🌙 Nightly Builds

Stay up to date with the latest improvements, experimental features, and bug fixes.
You can download nightly builds from the official nightly builds page.

Summary

Feature	Description
Scripting	Lua-based, flexible, engine-integrated scripting
Plugins	Native DLL plugins with SDK access
Error Handling	In-engine logging and debugging support
Tools	ObjectExplorer, ScriptRunner, DebugView integration
Extensibility	API hooks, callbacks, and native access