RDR2 Script Hook

RDR2 Script Hook loads isolated Rust, JavaScript, C#, and Lua WebAssembly mods, exposes a typed scripting API, and renders interactive browser interfaces directly in the game's post-HUD render path. It includes a launcher, in-process runtime, guest SDK, native-code generator, example trainers, and a headless integration-test host.

• Wasmtime-based mod isolation with ABI validation, memory limits, and per-call execution fuel.
• Typed Rust wrappers generated from the RDR3 native database, plus globals, timers, logging, metadata, and frame/key events.
• Rust, JavaScript/Javy, C# NativeAOT-LLVM, and Lua guest profiles, all executed by the same embedded Wasmtime runtime.
• Transparent WebView2 overlays composed after the game HUD without CPU texture readback.
• Synchronized shared-texture paths for both Direct3D 12 and Vulkan.
• Overlay visibility, focus, native game cursor control, and bidirectional JSON messaging.
• A first-class Script Bindings section in the game's Controls screen with primary/alternate keys, persistence, press/release events, and up to 2048 declared actions.
• Structured logging, full-memory minidumps, and a standalone WASM smoke-test executable.

flowchart LR
 Mods["Rust / Javy / .NET / Lua modules"] -->|stable host ABI| Host["Wasmtime host"]
 Host -->|natives, globals, timers| Rage["RAGE runtime"]
 Rage -->|Down / Up events| Bindings["Script Bindings"]
 Bindings --> Host
 Mods -->|HTML, JSON, focus| Browser["WebView2"]
 Browser -->|shared D3D11 texture| Interop["D3D12 / Vulkan interop"]
 Interop -->|post-HUD layer| Frame["Game frame"]

The game-facing hooks, browser controller, and WASM host remain separate. Mods only communicate through the versioned host ABI; they never receive direct access to WebView2 or renderer COM objects.

Graphics interop and RAGE hooks require live in-game testing. The headless test suite covers the host ABI, native marshalling, WebView imports, all four guest profiles, and repeated ticks.

Install Visual Studio C++ Build Tools, CMake 3.21+, Ninja, Python 3, Git, Rust, .NET SDK 10, and PowerShell. Run the following from a Visual Studio developer PowerShell:

git clone --recurse-submodules https://github.com/emcifuntik/rdr2scripthook.git
Set-Location rdr2scripthook
.\vcpkg\bootstrap-vcpkg.bat -disableMetrics
rustup target add wasm32-unknown-unknown wasm32-wasip1
cmake --preset windows-release
cmake --build --preset windows-release
& .\BIN\Release\wasmtest.exe

Build the bundled JavaScript example separately when needed:

.\scripts\javy-wasm\build.ps1
.\scripts\dotnet-wasm\build.ps1
.\scripts\lua-wasm\verify.ps1

Release output is written to BIN/Release. Keep launcher.exe, launcher-hook.dll, rdrhook.dll, crossmap.dat, and the mods/ directory together. Start launcher.exe; pass nolaunch when the Rockstar launcher or the game is already being started separately.

Every push and pull request also runs the Windows Release build and smoke tests in GitHub Actions. Successful runs publish a ready-to-extract runtime artifact for 14 days. Pushing a stable semantic-version tag such as v1.2.3 runs the same verified build and publishes a GitHub Release containing a versioned ZIP and its SHA-256 checksum.

The loader discovers mods/<directory>/mod.toml. A minimal manifest with a binding visible in the game's Controls settings looks like this:

[mod]
name = "Example Mod"
version = "1.0.0"
author = "Author"
description = "Example description"
entrypoint = "main.wasm"
runtime = "wasmtime"
[[input.bindings]]
id = "open_inventory"
description = "Open custom inventory"
mapper = "keyboard"
default = "F6"

The primary key comes from the manifest. Users can assign both the primary and alternate slots from the in-game Controls screen; both mappings feed the same Down/Up event stream.

Rust guests use scripts/rdr2-wasm as a path dependency and build as a cdylib for wasm32-unknown-unknown:

use rdr2_wasm::input::{self, BindingEvent};
fn initialize() {
 let binding = input::Binding::register_keyboard(
 "open_inventory",
 "Open custom inventory",
 "F6",
 ).expect("register binding");
 rdr2_wasm::event::add_tick_callback(move || {
 while let Ok(Some(event)) = binding.poll_event() {
 match event {
 BindingEvent::Down => rdr2_wasm::log::info("inventory opened"),
 BindingEvent::Up => rdr2_wasm::log::info("inventory key released"),
 }
 }
 });
}
rdr2_wasm::entrypoint!(initialize);

For an end-to-end implementation, see the Rust WebView trainer in scripts/example-wasm or the JavaScript trainer in scripts/javy-wasm. The C# AOT SDK and example live in scripts/dotnet-wasm; the synchronized Lua artifact and lifecycle example live in scripts/lua-wasm.

Distributed under the MIT License.