Skip to content

Lua API Reference (Custom Natives)

Display and Logging

log(msg)

Writes a message to the editor console and the mod loader's log file. (Useful for debugging.)

  • Parameters:
  • msg (string): The message to write.

print(...)

Similar to log, but accepts multiple arguments that will be separated by tabs in the log output.

  • Parameters:
  • ... (any): The values to display.

msgbox(msg)

Displays a blocking Windows dialog box over the game with an info icon.

  • Parameters:
  • msg (string): The text to display in the dialog box.

2D Rendering (DirectX)

draw_text(x, y, text, [color])

Draws text on the screen over the game.

  • Parameters:
  • x (int): X position on the screen.
  • y (int): Y position on the screen.
  • text (string): The text to draw.
  • color (int, optional): The color in ARGB format (e.g., 0xFFFFFFFF for white). Default: white.

draw_rect(x, y, w, h, [color])

Draws a colored rectangle on the screen.

  • Parameters:
  • x (int): X position (top-left corner).
  • y (int): Y position (top-left corner).
  • w (int): Width of the rectangle.
  • h (int): Height of the rectangle.
  • color (int, optional): Color in ARGB format (e.g., 0xFF000000 for opaque black). Default: opaque black.

Input and Controls

is_key_down(vk_code)

Asynchronously checks if a keyboard key is pressed, making sure the game window is in the foreground.

  • Parameters:
  • vk_code (int): The Windows Virtual-Key (VK) code for the key (e.g., 0x73 for F4).
  • Returns: true if the key is pressed, false otherwise.

set_menu_open(bool)

Tells the engine if your custom menu/interface is open. This cleanly blocks or manages game inputs in the background.

  • Parameters:
  • bool (boolean): true to indicate the menu is open.

Modding and Native Calls

declare_mod_file(relPath)

Adds a script to your mod's manifest.lua list, so it automatically loads on the next startup or during a hot-reload.

  • Parameters:
  • relPath (string): Relative path of the Lua file from the mod folder.
  • Returns: true if added successfully.

call_native(name, ...)

Dynamically calls a GTA IV engine native function by its string name.

  • Parameters:
  • name (string): The name of the native function (e.g., "SET_CHAR_HEALTH").
  • ... (any): The arguments required by the native.
  • Returns: The value returned by the native (format depends on the function, returns raw bytes for untyped ones).

call_native_out(name, outputCount, ...)

Calls a GTA IV native function that uses pointers/references to return multiple values.

  • Parameters:
  • name (string): The name of the native function.
  • outputCount (int): The number of output arguments (pointers) required (max 4).
  • ... (any): The standard input arguments for the native.
  • Returns: Returns the native's standard result followed by the values (as a 4-byte raw string) of each dereferenced output argument.

call_native_probe(name, ...)

Similar to call_native, but wraps the call in an exception block (SEH) to prevent the entire game from crashing if arguments are invalid or unstable.

  • Parameters: Same as call_native.
  • Returns: Returns two values: crashed (boolean, true if the call caused an intercepted crash) and rawResult (the 4-byte raw return buffer).

string_addr(s)

Gets the raw memory address pointing to a Lua string. Useful as a deep diagnostic tool.

  • Parameters:
  • s (string): The Lua string.
  • Returns: (int) The memory address pointing to the content.

native_info(name)

Gets the full metadata and signature known by the mod loader for a specific native.

  • Parameters:
  • name (string): Name of the native.
  • Returns: A table containing signature information (parameters with types like int, float, etc., and the return type), or nil if unknown.

native_available(name)

Checks if a native exists in the internal database and was correctly resolved by the game in memory.

  • Parameters:
  • name (string): Name of the native.
  • Returns: true if the function is fully usable, false otherwise.

is_script_tick_fallback()

Checks if the current execution is running through the render safety loop (EndScene fallback) because the game's native script thread is inactive or stuck for more than 3 seconds.

  • Returns: true if running in the fallback.

Events (Callbacks)

The LuaModLoader engine automatically calls certain global functions in your scripts if you define them.

onTick()

Called every game frame. This is where you should put your mod's main logic (checking keys, updating the UI, spawning entities, etc.).

  • Example: 
    function onTick()
    if is_key_down(0x73) then -- F4 Key
        -- Code executed every frame if F4 is pressed
    end
end

onUnload()

Called right before your mod is unloaded or stopped (for example, during a hot-reload or if the user stops it via the menu). Useful for cleaning up spawned entities or saving data.

  • Example: 
    function onUnload()
    log("Mod is stopping, cleaning up...")
end

Note: There is no specific onLoad() function to define. Loading (initialization) simply happens by writing your code in the file's global scope, outside of any function. This global code runs exactly once when the file is loaded.