Skip to Content

Native Functions

Native functions (or “natives”) are the built-in functions provided by GTA V and FiveM to interact with the game engine. They allow you to manipulate entities, control the camera, manage UI, and much more.

Core Concepts

Common Natives

Player & Ped

-- Get the current player's local ped
local ped = PlayerPedId()
 
-- Get Entity Coordinates (Vector3)
local coords = GetEntityCoords(ped)
 
-- Heal the player
SetEntityHealth(ped, 200)
 
-- Give Weapon
GiveWeaponToPed(ped, `WEAPON_PISTOL`, 100, false, true)

Vehicle

-- Spawn a vehicle (Client)
local model = `adder`
RequestModel(model)
while not HasModelLoaded(model) do Wait(0) end
 
local veh = CreateVehicle(model, x, y, z, heading, true, false)
SetPedIntoVehicle(PlayerPedId(), veh, -1)
 
-- Repair Vehicle
SetVehicleFixed(veh)

UI & Visuals

-- Draw 3D Text
DrawText3D(x, y, z, "Press ~g~E~w~ to Interact") -- (Custom helper usually required)
 
-- Notifications (Native)
BeginTextCommandThefeedPost("STRING")
AddTextComponentSubstringPlayerName("Hello World")
EndTextCommandThefeedPostTicker(false, true)

Common Patterns

The “Main Loop”

Used for per-frame logic like markers or interactions.

CreateThread(function()
    while true do
        local sleep = 1000 -- Default sleep (1 second)
        local ped = PlayerPedId()
        local coords = GetEntityCoords(ped)
        local dist = #(coords - targetCoords) -- Fast vector distance check
 
        if dist < 5.0 then
            sleep = 0 -- Run every frame when close
            DrawMarker(1, targetCoords, ...)
            
            if dist < 1.5 then
                -- Handle Input
                if IsControlJustReleased(0, 38) then -- E Key
                    print("Interacted!")
                end
            end
        end
        
        Wait(sleep) -- Dynamic wait time saves performance
    end
end)

Raycasting

Checking for entities in front of the player.

local function GetEntityInFront()
    local ped = PlayerPedId()
    local coords = GetEntityCoords(ped)
    local offset = GetOffsetFromEntityInWorldCoords(ped, 0.0, 5.0, 0.0)
    local ray = StartShapeTestCapsule(coords.x, coords.y, coords.z, offset.x, offset.y, offset.z, 0.5, 10, ped, 7)
    local _, hit, _, _, entity = GetShapeTestResult(ray)
    return hit, entity
end

Framework Integration

Frameworks often wrap natives to provide easier APIs or handle networking automatically.

QBCore

-- Notification
QBCore.Functions.Notify('This is a notification', 'success')
 
-- Spawning Vehicle (Server-side callback often used)
QBCore.Functions.SpawnVehicle('adder', function(veh)
    SetEntityHeading(veh, 90.0)
end, coords, true)

ESX

-- Notification
ESX.ShowNotification('This is a notification')
 
-- Spawning Vehicle
ESX.Game.SpawnVehicle('adder', coords, 90.0, function(veh)
    -- callback
end)

Performance Notes

  1. Avoid String Operations in Loops: Natives taking strings (like GetHashKey) are slow. Use the backtick syntax `model_name` for compile-time hashing.
  2. Vector Math: Use Lua’s built-in vector math (e.g., #(vec1 - vec2)) instead of GetDistanceBetweenCoords or Vdist. It is significantly faster.
  3. Dynamic Waits: Always use variable Wait() times in loops. Only run code every frame (Wait(0)) when absolutely necessary (e.g., drawing markers or checking input).
  4. Global Namespace: Avoid Citizen.Wait or Citizen.CreateThread. Use the direct global aliases Wait and CreateThread.

Reference