GTA IV Native Functions Reference¶
In LuaModLoader, you can call any native GTA IV function directly by its name in Lua. This reference lists the most common and useful native functions, categorized by feature with copy-paste Lua examples.
💡 How Calling Natives Works in Lua¶
In LuaModLoader, you don't need complicated C++ code. You simply call the native by its PascalCase name:
-- Example: Get your character and set health to 200
local playerPed = GetPlayerChar(GetPlayerId())
SetCharHealth(playerPed, 200)
👤 Player & Character Functions (CHAR / PED)¶
Player Identity & Health¶
| Function | Parameters | Description |
|---|---|---|
GetPlayerId() |
none | Returns the local player's ID integer. |
GetPlayerChar(playerId) |
playerId |
Returns the Ped handle of the player character. |
SetCharHealth(ped, health) |
ped, health (int) |
Sets health (default: 100 to 200). |
GetCharHealth(ped) |
ped |
Returns current health: local hp = GetCharHealth(ped). |
AddArmourToChar(ped, armour) |
ped, armour (int) |
Adds body armour points (max: 100). |
SetCharInvincible(ped, enable) |
ped, bool |
Enables or disables god mode. |
SetCharNeverTargetted(ped, enable) |
ped, bool |
Stops enemies from targeting this ped. |
Position & Movement¶
| Function | Parameters | Description |
|---|---|---|
SetCharCoordinates(ped, x, y, z) |
ped, x, y, z |
Teleports character to 3D coordinates. |
SetCharHeading(ped, angle) |
ped, angle (float) |
Sets character facing direction (0-360°). |
SetCharVelocity(ped, vx, vy, vz) |
ped, vx, vy, vz |
Applies physical velocity vector. |
GetCharCoordinates(ped) |
ped |
Returns the 3D position as three values: local x, y, z = GetCharCoordinates(ped). |
Police & Wanted Level¶
| Function | Parameters | Description |
|---|---|---|
AlterWantedLevel(playerId, stars) |
playerId, stars (0-6) |
Sets police wanted level. |
ApplyWantedLevelChangeNow(playerId) |
playerId |
Instantly updates police behavior. |
ClearCharLastDamageEntity(ped) |
ped |
Resets damage state with police. |
-- Example: Full Heal & Clear Wanted Level
local ped = GetPlayerChar(GetPlayerId())
SetCharHealth(ped, 200)
AddArmourToChar(ped, 100)
AlterWantedLevel(GetPlayerId(), 0)
ApplyWantedLevelChangeNow(GetPlayerId())
🚗 Vehicle Functions (CAR / VEHICLE)¶
Spawning & Repairing¶
| Function | Parameters | Description |
|---|---|---|
CreateCar(modelHash, x, y, z, createdByScript) |
hash, x, y, z, bool |
Spawns a vehicle and returns its handle. |
DeleteCar(veh) |
veh |
Deletes a vehicle. |
FixCar(veh) |
veh |
Fully repairs visual and mechanical vehicle damage. |
SetCarEngineOn(veh, engineOn, silent) |
veh, bool, bool |
Starts or shuts down the vehicle engine. |
WarpCharIntoCar(ped, veh) |
ped, veh |
Teleports character into driver's seat. |
Speed & Handling¶
| Function | Parameters | Description |
|---|---|---|
GetCarSpeed(veh) |
veh |
Returns vehicle speed in meters per second (m/s). Multiply by 3.6 for km/h. |
SetCarForwardSpeed(veh, speed) |
veh, speed (float) |
Sets forward speed vector in m/s. |
IsCharInAnyCar(ped) |
ped |
Returns true if character is in a vehicle. |
GetCarCharIsUsing(ped) |
ped |
Returns handle of vehicle character is currently in. |
-- Example: Repair and Boost Current Vehicle
local ped = GetPlayerChar(GetPlayerId())
if IsCharInAnyCar(ped) then
local veh = GetCarCharIsUsing(ped)
FixCar(veh)
SetCarForwardSpeed(veh, 50.0) -- Boost to ~180 km/h
end
🔫 Weapons & Inventory Functions (WEAPON)¶
| Function | Parameters | Description |
|---|---|---|
GiveWeaponToChar(ped, weaponId, ammo, show) |
ped, weaponId, ammo, bool |
Gives weapon and ammunition. |
RemoveAllCharWeapons(ped) |
ped |
Strips all weapons from character. |
SetCharAccuracy(ped, accuracy) |
ped, accuracy (0-100) |
Sets shooting accuracy percentage. |
SetCharAmmo(ped, weaponId, ammo) |
ped, weaponId, ammo |
Sets ammo count for specific weapon. |
-- Example: Give Desert Eagle (ID 9) and M4 (ID 15) with ammo
local ped = GetPlayerChar(GetPlayerId())
GiveWeaponToChar(ped, 9, 100, false)
GiveWeaponToChar(ped, 15, 300, true)
🧠 AI & Tasks (TASK)¶
| Function | Parameters | Description |
|---|---|---|
TaskWanderStandard(ped) |
ped |
Makes pedestrian wander randomly on foot. |
TaskCombat(ped, targetPed) |
ped, targetPed |
Makes ped attack target character. |
TaskCarDriveWander(ped, veh, speed, drivingStyle) |
ped, veh, speed, style |
Makes ped drive around randomly. |
TaskHandsUp(ped, duration) |
ped, duration (ms) |
Makes ped raise hands in surrender. |
ClearCharTasks(ped) |
ped |
Cancels all current AI actions. |
🌍 World & Environment Functions¶
| Function | Parameters | Description |
|---|---|---|
SetTimeOfDay(hours, minutes) |
hours (0-23), minutes (0-59) |
Sets game world time. |
ForceWeatherNow(weatherId) |
weatherId (0-7) |
Changes weather immediately. |
AddExplosion(x, y, z, type, radius, sound, visual, camShake) |
x, y, z, type, radius, bool, bool, float |
Triggers an explosion in the world. |
DrawLightWithRange(x, y, z, r, g, b, range, intensity) |
x, y, z, r, g, b, range, intensity |
Renders dynamic point light at coordinates. |
📍 Blips & Map Markers (BLIP)¶
| Function | Parameters | Description |
|---|---|---|
AddBlipForCoord(x, y, z) |
x, y, z |
Creates a map marker at position. |
AddBlipForChar(ped) |
ped |
Attaches a map icon to a character. Returns the blip handle. |
AddBlipForCar(veh) |
veh |
Attaches a map icon to vehicle. |
ChangeBlipColour(blip, colorId) |
blip, colorId (0-4) |
Changes marker color (0=White, 1=Red, 2=Green, 3=Blue, 4=Yellow). |
RemoveBlip(blip) |
blip |
Removes map marker. |
Natives that used to need a workaround¶
Three shapes of native were once uncallable, or callable but silently wrong,
through their typed PascalCase global. All three now work normally. If you are
reading older mod code that routes them through Native.Call /
Native.CallOut, that detour is no longer needed.
Natives taking a handle by pointer¶
DELETE_CAR, DELETE_CHAR, DELETE_OBJECT, MARK_CAR_AS_NO_LONGER_NEEDED,
MARK_CHAR_AS_NO_LONGER_NEEDED, MARK_OBJECT_AS_NO_LONGER_NEEDED and their
CREATE_GROUP / CREATE_VIEWPORT / COPY_*_DECISION_MAKER relatives all take
a pointer to a handle: the game reads the handle through it, then zeroes it.
Those parameters used to be registered as pure outputs, so the typed global
handed the game an empty buffer and never read your argument -- DeleteCar(veh)
ran without touching veh. They now carry a third role, isInputPointer: the
thunk boxes your argument, hands the native its address, and decodes the
rewritten buffer back to Lua.
AddBlipForChar(ped)¶
Both of its parameters used to be registered as outputs, so the global took no
input and never saw your ped -- every blip landed on ped 0. Only the second
one is an output (the Blip* the native writes), so the global now takes the
ped and returns the blip:
AddBlipForCar(veh) and AddBlipForCoord(x, y, z) were always correct.
Natives returning a Vector3¶
GET_BLIP_COORDS and its family hand the game one pointer for three
floats. Two things were missing: NativeContext::SetVectorResults(), which
copies the engine's temporary vector back to the buffer the caller supplied
(without it these natives always read as 0, 0, 0), and a signature -- the
scrapers skip any declaration carrying a Vector3 *.
Both are in place, and a Vector3 output is written as three consecutive
float outputs, because the thunk's output buffers are contiguous:
A blip attached to an entity still reads as 0, 0, 0 -- it tracks the
entity and carries no coordinate of its own. That is the game's behaviour, not
a signature problem.
How to check any native yourself
Native.Info("SOME_NATIVE") returns the registered signature, including a
confidence field saying where it came from. Anything that is not
x32dbg_live_verified_* is worth double-checking. The same information is
in the Native Database, where a parameter marked out
means the value comes back to Lua instead of being passed in.