Lua scripting mod for RDR2/GTAV

RedLua is a AB's ScriptHook library that simplifies the game modding process.

Installation

Download the latest release and extract the archive contents into your game folder (must be writeable). Note that the RedLua won't work without the ScriptHookRDR2/V library!

Usage

In RDR2 press F7, in GTAV default bind is F4 (you can change the default hotkey in <Your game directory>\RedLua\Settings.json file, keycodes available here) to open the RedLua menu. Here you can load/reload/stop/unload scripts, reload the NativeDB and change library settings.

RedLua uses the Easylogging++ library, so if you want to configure the logger, just navigate to <Your game directory>\RedLua\ and create a file called Log.conf with following contents:

* GLOBAL:
FILENAME = "RedLua\Run.log"ENABLED = true
TO_FILE = false
TO_STANDARD_OUTPUT = true
SUBSECOND_PRECISION = 6
PERFORMANCE_TRACKING = true
MAX_LOG_FILE_SIZE = 2097152
LOG_FLUSH_THRESHOLD = 0
* INFO:
FORMAT = "%datetime INFO %msg"
* DEBUG:
FORMAT = "%datetime{%d/%M} DEBUG %func %msg"
* WARNING:
FORMAT = "%datetime WARN %msg"
* ERROR:
FORMAT = "%datetime ERROR %msg"
* FATAL:
FORMAT = "%datetime FATAL %msg"

Scripting

RedLua searches for scripts in the <Your game directory>\RedLua\Scripts\. Each script located in this folder will be loaded automatically (If the Autorun feature is enabled). Every script should return a table (can be empty) with functions OnLoad, OnTick, OnStop, OnReload. Almost every function of the RDR2's RAGE is described here.

Example:

localt= {}
functiont.OnLoad()
print('Yay!')
endfunctiont.OnTick()
print('Tick!')
endfunctiont.OnStop()
print('Goodbye!')
endreturnt

There are two ways to call native functions:

1. native.call('PLAYER', 'PLAYER_ID')
2. PLAYER:GET_PLAYER_PED(PLAYER:PLAYER_ID())

Note that the native functions can return RedLua's userdata called NativeObject. Each NativeObject has its own type (like const char *, Ped, Vehicle, Entity *, Vector, etc), as Lua-values, the native functions return (take) only the following types: boolean, int, float, Hash, Any and string (take only). Also, NativeObjects that are pointers, can be indexed.

Native functions that expect a parameter of type Any * as an argument can take a cdata value. Here is the example:

-- This script will display an in-game toast notification for 2 seconds when F8 key is releasedlocalt= {}
localffi=require'ffi'functiont.OnLoad()
t.me=PLAYER:PLAYER_ID()
t.me_ent=PLAYER:GET_PLAYER_PED(t.me)
t.ent_arr=native.new('Entity', 1024)
endfunctiont.OnTick()
ifmisc.iskeyjustup(VK_F8, true) thenlocalduration=ffi.new([[ struct { int duration; int some_weird_padding[14]; }]], {
2000-- 2000 milliseconds
})
localdata=ffi.new([[ struct { uint64_t weird_padding_again; const char *title; const char *text; uint64_t god_another_unknown_field; uint64_t iconDict; uint64_t icon; uint64_t iconColor; }]], {
0,
MISC:VAR_STRING(10, 'LITERAL_STRING', 'Hello, RedLua!'):topointer(),
MISC:VAR_STRING(10, 'LITERAL_STRING', jit.version):topointer(),
0,
MISC:GET_HASH_KEY('HUD_TOASTS'), MISC:GET_HASH_KEY('toast_player_deadeye'),
MISC:GET_HASH_KEY('COLOR_RED')
})
UIFEED:_UI_FEED_POST_SAMPLE_TOAST(duration, data, true, true)
end-- If you press F9 it will knock out all peds around youifmisc.iskeyjustup(VK_F9, true) thenlocalcnt=native.allpeds(t.ent_arr) -1fori=0, cntdoift.ent_arr[i] ~=t.me_entthenTASK:CLEAR_PED_TASKS(t.ent_arr[i], false, false)
TASK:TASK_KNOCKED_OUT(t.ent_arr[i], 10, false)
endendendendreturnt

Here is a list of all the Lua functions provided by RedLua:

--[[	Library: native]]-- Cast NativeObject to a pointer (useful for ffi)NativeObject:topointer()
-- Invoke the native functionnative.call('PLAYER', 'PLAYER_ID') -- FasterPLAYER:PLAYER_ID() -- Simpler, but uses a lot of metacalls-- Get the information about the functionnative.info('BUILTIN', 'WAIT') -- Returns: {hash = '0x4EDE34FBADD967A6', build = 1207, returns = 'void', params = {[1] = {type = 'int', name = 'ms'}}} or nothing if specified function does not exists-- Create new typed arraynative.new('Vehicle', 5) -- Returns: NativeObject of 5 Vehiclesnative.new('Vector3', 4) -- Returns: NativeVector, can be used in functions like ENTITY:GET_ENTITY_MATRIX(...)-- Get all world objectsnative.allobjects(objects_typed_array) -- Returns: number of objectsnative.allpeds(peds_typed_array)
native.allpickups(pickups_typed_array)
native.allvehicles(vehicles_typed_array)
--[[	Library: misc]]-- Is key down for the last 5 secondsmisc.iskeydown(VK_*)
-- Is key down for the last 30 secondsmisc.iskeydownlong(VK_*)
-- Is key just upmisc.iskeyjustup(VK_*, exclusive=false)
-- Reset key statemisc.resetkey(VK_*)
-- Get game versionmisc.gamever() -- Returns: number (getGameVersion() result) and string ("rdr3" or "gta5")-- Get RedLua versionmisc.libver() -- Returns: integer, e.g. 010, 020, etc.--[[	Library: menu]]-- Create a menu section for the script-- An example script is available here: examples/ScriptMenu.luamenu.set {...} -- Returns: nothing. Note that this function is NOT safe, it may throw an Lua error.-- Remove menu section for the script-- Note that the menu will only be removed after 1 or more (depends on the number of submenus) full garbage collection steps!menu.remove() -- Returns: nothing--[[	Library: lang]]-- Add locale strings-- Example script: examples/ScriptMenu.lualang.install {...} -- Returns: nothing-- Get localized string for the current languagelang.get(code) -- Returns: string

Contribution

This is my first project that uses C++, so I'm not really good at it. If you see some cursed code and you know how to improve it, PRs are welcome.

Thanks

Thanks to Mike Pall, Alexander Blade, alloc8or, Niels Lohmann and abumusamq for all their awesome work.

License

RedLua is released under The MIT License. This license excludes files in the src\thirdparty that may be distributed under another license. Please read the LICENSE file for more information.