Getting Started with Lua Modding

Welcome to GTA IV modding with LuaModLoader! This guide is designed for beginners. You don't need any prior C++ or reverse engineering experience.

---

How Does a Lua Mod Work?

A mod is simply a .lua text file placed inside your game directory. LuaModLoader reads this file and executes its code directly inside GTA IV.

📁 Grand Theft Auto IV/ (Game Root Folder)
├── 📁 mods/
│   └── 📁 MyFirstMod/
│       ├── 📄 manifest.lua   <-- declares the mod (required)
│       └── 📄 main.lua       <-- Your mod's code goes here!
├── 📄 dinput8.dll
└── 📄 LuaModLoader.dll

---

The editor can do steps 1 to 3 for you

With the game running, press F6, right-click in the mod list and pick New mod. You get the folder, a commented manifest.lua and a main.lua ready to fill in. The steps below are the same thing done by hand.

Step 1: Create Your First Mod

1. Open your GTA IV installation folder (where GTAIV.exe is located).
2. Open or create the mods/ folder.
3. Inside mods/, create a new folder named MyFirstMod.
4. Inside MyFirstMod, create a new text file named main.lua.

---

Step 2: Write Your First Code

Open main.lua with Notepad, VS Code, or any text editor and paste the following:

-- When the game loads, show a welcome message
Console.MsgBox("Hello from LuaModLoader!")

-- This function runs automatically every frame
Thread.Create(function()
    while true do
        -- Check if the player presses the F4 key (0x73)
        if Input.IsKeyDown(0x73) then
            local playerPed = GetPlayerChar(GetPlayerId())

            -- Restore player health to 200 (max)
            SetCharHealth(playerPed, 200)

            -- Give body armour
            AddArmourToChar(playerPed, 100)

            Log.Print("Health and armor restored!")
        end
        Thread.Wait(0)
    end
end)

---

Step 3: Declare the Mod (manifest.lua)

The manifest is what makes the folder a mod: without it the loader walks past the folder and your script never shows up. Put a manifest.lua next to main.lua:

name 'My First Mod'
author 'You'
description 'Heals the player on F4.'
version '1.0.0'
autostart = true

client_scripts {
    'main.lua',
}

Each line is a plain Lua call, which is why the strings need no =. The exception is autostart, a boolean, and f true is not valid Lua: write autostart = true or autostart(true). It defaults to false, so this is the line that decides whether the mod starts by itself.

The Mod structure page carries the full manifest reference, covering multi-file mods, MOD_DIR and the legacy formats.

---

Step 4: Test and Edit Live in Game (F6 Key)

You don't need to restart GTA IV every time you modify your code!

1. Start GTA IV.
2. Press F6 at any time to open the In-Game Code Editor.
3. You can edit your code live or test small snippets immediately.
4. Close the editor with F6 or Escape to return to gameplay.

---

💡 Naming: natives are PascalCase

Every GTA IV native is a global function under its PascalCase name:

SetCharHealth(ped, 200)
GetPlayerChar(GetPlayerId())

These are the same names ScriptHookDotNet scripts and classic trainers use, so ported code needs no renaming.

The canonical SNAKE_CASE name is not a global function. It stays reachable in two places:

• the natives table, as in natives.SET_CHAR_HEALTH(ped, 200).
• Native.Call("SET_CHAR_HEALTH", ped, 200). There the name must be SNAKE_CASE, since the lookup is an exact match on the canonical name.

Everything the loader itself provides lives in a namespace instead: Thread, Console, Log, Draw, Color, Input, Gamepad, Native, Memory, Vehicle, Script. See the API reference.