🎮Client Function Reference

Learn about and how to use common core client functions!!

RSGCore.Functions.GetPlayerData

• Perhaps the most used function in the framework. This function returns the players data of the current source which, since its used client side, is automatically the client or player. It can be used with modifiers on the end starting with a ”.” (period)

function RSGCore.Functions.GetPlayerData(cb)
    if not cb then return RSGCore.PlayerData end
    cb(RSGCore.PlayerData)
end

-- Example

local Player = RSGCore.Functions.GetPlayerData()
print(RSGCore.Debug(Player))

OR

local Player = RSGCore.Functions.GetPlayerData()
local jobName = Player.job.name
print(jobName)

RSGCore.Functions.GetCoords

• This function operates very similarly to how the native GetEntityCoords does, but it returns the heading as well

---@param entity number
---@return vector4
function RSGCore.Functions.GetCoords(entity)
    local coords = GetEntityCoords(entity, false)
    local heading = GetEntityHeading(entity)
    return vector4(coords.x, coords.y, coords.z, heading)
end

-- Example

local coords = RSGCore.Functions.GetCoords(PlayerPedId())
print(coords)

RSGCore.Functions.HasItem

• Returns whether a player has a certain item

function RSGCore.Functions.HasItem(items, amount)
    return exports['rsg-inventory']:HasItem(items, amount)
end

local hasItem = RSGCore.Functions.HasItem('my_cool_item', 1)
print(hasItem)

RSGCore.Functions.TriggerCaback

• Function used to cal from the client to the server anbd receive a value back

function RSGCore.Functions.TriggerCallback(name, cb, ...)
    RSGCore.ServerCallbacks[name] = cb
    TriggerServerEvent('RSGCore:Server:TriggerCallback', name, ...)
end

-- Example

RSGCore.Functions.TriggerCallback('callbackName', function(result)
    print('I got this from the CreateCallBack -->  '..result)
end, 'my_parameter_name')

RSGCore.Functions.GetVehicles

• Returns a vehice game pool (for backwards compatibility) - Not worth using

function RSGCore.Functions.GetVehicles()
    return GetGamePool('CVehicle')
end

-- Example

local vehicles = RSGCore.Functions.GetVehicles()
print(RSGCore.Debug(vehicles))

OR -- preferred method

local vehicles = GetGamePool('CVehicle')
print(RSGCore.Debug(vehicles))

RSGCore.Function.GetCoreObject

• Returns the core object of the game

exports('GetCoreObject', function()
    return RSGCore
end)

local RSGCore = exports['rsg-core']:GetCoreObject()

OR -- call the core in a single file that loads before the others

RSGCore = exports['rsg-core']:GetCoreObject()

RSGCore.Function.GetPlayers

• Returns a table of all players in the game - not worth using

function RSGCore.Functions.GetPlayers()
    return GetActivePlayers()
end

-- Example

local players = RSGCore.Functions.GetPlayers()
print(RSGCore.Debug(players))

OR -- preferred method

local players = GetActivePlayers()
print(RSGCore.Debug(players))

RSGCore.Function.GetPeds

• Returns a model hash filtered ped game pool

function RSGCore.Functions.GetPeds(ignoreList)
    local pedPool = GetGamePool('CPed')
    local peds = {}
    local ignoreTable = {}
    ignoreList = ignoreList or {}
    for i = 1, #ignoreList do
        ignoreTable[ignoreList[i]] = true
    end
    for i = 1, #pedPool do
        if not ignoreTable[pedPool[i]] then
            peds[#peds + 1] = pedPool[i]
        end
    end
    return peds
end

-- Example

local peds = RSGCore.Functions.GetPeds({`mp_m_freemode_01`})
print(RSGCore.Debug(peds))

RSGCore.Function.GetClosestPed

• Returns the closest ped to the player’s position

function RSGCore.Functions.GetClosestPed(coords, ignoreList)
    local ped = PlayerPedId()
    if coords then
        coords = type(coords) == 'table' and vec3(coords.x, coords.y, coords.z) or coords
    else
        coords = GetEntityCoords(ped)
    end
    ignoreList = ignoreList or {}
    local peds = RSGCore.Functions.GetPeds(ignoreList)
    local closestDistance = -1
    local closestPed = -1
    for i = 1, #peds, 1 do
        local pedCoords = GetEntityCoords(peds[i])
        local distance = #(pedCoords - coords)

        if closestDistance == -1 or closestDistance > distance then
            closestPed = peds[i]
            closestDistance = distance
        end
    end
    return closestPed, closestDistance
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local closestPed, distance = RSGCore.Functions.GetClosestPed(coords)
print(closestPed, distance)

RSGCore.Functions.GetClosestVehicle

• Returns the closest vehicle to the player

function RSGCore.Functions.GetClosestVehicle(coords)
    local ped = PlayerPedId()
    local vehicles = GetGamePool('CVehicle')
    local closestDistance = -1
    local closestVehicle = -1
    if coords then
        coords = type(coords) == 'table' and vec3(coords.x, coords.y, coords.z) or coords
    else
        coords = GetEntityCoords(ped)
    end
    for i = 1, #vehicles, 1 do
        local vehicleCoords = GetEntityCoords(vehicles[i])
        local distance = #(vehicleCoords - coords)

        if closestDistance == -1 or closestDistance > distance then
            closestVehicle = vehicles[i]
            closestDistance = distance
        end
    end
    return closestVehicle, closestDistance
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local closestVehicle, distance = RSGCore.Functions.GetClosestVehicle(coords)
print(closestVehicle, distance)

RSGCore.Functions.GetClosestObject

• Returns the closest player to the client

function RSGCore.Functions.GetClosestObject(coords)
    local ped = PlayerPedId()
    local objects = GetGamePool('CObject')
    local closestDistance = -1
    local closestObject = -1
    if coords then
        coords = type(coords) == 'table' and vec3(coords.x, coords.y, coords.z) or coords
    else
        coords = GetEntityCoords(ped)
    end
    for i = 1, #objects, 1 do
        local objectCoords = GetEntityCoords(objects[i])
        local distance = #(objectCoords - coords)
        if closestDistance == -1 or closestDistance > distance then
            closestObject = objects[i]
            closestDistance = distance
        end
    end
    return closestObject, closestDistance
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local closestObject, distance = RSGCore.Functions.GetClosestObject(coords)
print(closestObject, distance)

RSGCore.Functions.GetPlayersFromCoords

• Returns a list of players within a certain radius from the given coordinates

function RSGCore.Functions.GetPlayersFromCoords(coords, distance)
    local players = GetActivePlayers()
    local ped = PlayerPedId()
    if coords then
        coords = type(coords) == 'table' and vec3(coords.x, coords.y, coords.z) or coords
    else
        coords = GetEntityCoords(ped)
    end
    distance = distance or 5
    local closePlayers = {}
    for _, player in ipairs(players) do
        local targetCoords = GetEntityCoords(GetPlayerPed(player))
        local targetdistance = #(targetCoords - coords)
        if targetdistance <= distance then
            closePlayers[#closePlayers + 1] = player
        end
    end
    return closePlayers
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local radius = 5.0
local closestPlayers = RSGCore.Functions.GetPlayersFromCoords(coords, radius)
print(RSGCore.Debug(closestPlayers))

RSGCore.Functions.SpawnVehicle

• Spawns a vehicle at the given coordinates with the given model and color

---@param model string|number
---@param cb? fun(vehicle: number)
---@param coords? vector4 player position if not specified
---@param isnetworked? boolean defaults to true
---@param teleportInto boolean teleport player to driver seat if true
function RSGCore.Functions.SpawnVehicle(model, cb, coords, isnetworked, teleportInto)
    local playerCoords = GetEntityCoords(cache.ped)
    local combinedCoords = vec4(playerCoords.x, playerCoords.y, playerCoords.z, GetEntityHeading(cache.ped))
    coords = type(coords) == 'table' and vec4(coords.x, coords.y, coords.z, coords.w or combinedCoords.w) or coords or combinedCoords
    model = type(model) == 'string' and joaat(model) or model
    if not IsModelInCdimage(model) then return end

    isnetworked = isnetworked == nil or isnetworked
    lib.requestModel(model)
    local veh = CreateVehicle(model, coords.x, coords.y, coords.z, coords.w, isnetworked, false)
    local netid = NetworkGetNetworkIdFromEntity(veh)
    SetVehicleHasBeenOwnedByPlayer(veh, true)
    SetNetworkIdCanMigrate(netid, true)
    SetModelAsNoLongerNeeded(model)
    if teleportInto then TaskWarpPedIntoVehicle(cache.ped, veh, -1) end
    if cb then cb(veh) end
end

--- Example

local coords = RSGCore.Functions.GetCoords(PlayerPedId()) -- Ensure `coords` is vector4 with a heading value
coords = vec4(coords.x, coords.y, coords.z, coords.w or GetEntityHeading(PlayerPedId()))

RSGCore.Functions.SpawnVehicle('CART01', function(veh)
    SetEntityHeading(veh, coords.w) -- Set the heading of the vehicle
    TaskWarpPedIntoVehicle(PlayerPedId(), veh, -1) -- Teleport player into the vehicle
end, coords, true)

RSGCore.Functions.DeleteVehicle

• Deletes a vehicle at the given entity ID

function RSGCore.Functions.DeleteVehicle(vehicle)
    SetEntityAsMissionEntity(vehicle, true, true)
    DeleteVehicle(vehicle)
end

-- Example

local ped = PlayerPedId()
local veh = GetVehiclePedIsUsing(ped)
if veh ~= 0 then
    RSGCore.Functions.DeleteVehicle(veh)
else
    local pcoords = GetEntityCoords(ped)
    local vehicles = GetGamePool('CVehicle')
    for k, v in pairs(vehicles) do
        if #(pcoords - GetEntityCoords(v)) <= 5.0 then
            RSGCore.Functions.DeleteVehicle(v)
        end
    end
end

OR -- preferred method

local ped = PlayerPedId()
local veh = GetVehiclePedIsUsing(ped)
if veh ~= 0 then
    SetEntityAsMissionEntity(veh, true, true)
    DeleteVehicle(veh)
else
    local pcoords = GetEntityCoords(ped)
    local vehicles = GetGamePool('CVehicle')
    for k, v in pairs(vehicles) do
        if #(pcoords - GetEntityCoords(v)) <= 5.0 then
            SetEntityAsMissionEntity(v, true, true)
            DeleteVehicle(v)
        end
    end
end

RSGCore.Functions.GetPlate

• Get the license plate of a vehicle

function RSGCore.Functions.GetPlate(vehicle)
    if vehicle == 0 then return end
    return RSGCore.Shared.Trim(GetVehicleNumberPlateText(vehicle))
end

-- Example

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
local plate = RSGCore.Functions.GetPlate(vehicle)
print('Vehicle plate: ' .. plate)

RSGCore.Functions.GetVehicleLabel

• Get the display label/name of a vehicle

function RSGCore.Functions.GetVehicleLabel(vehicle)
    if vehicle == nil or vehicle == 0 then return end
    return GetLabelText(GetDisplayNameFromVehicleModel(GetEntityModel(vehicle)))
end

-- Example

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
local label = RSGCore.Functions.GetVehicleLabel(vehicle)
print('Vehicle name: ' .. label)

RSGCore.Functions.GetVehicleProperties

• Get all properties of a vehicle (used for saving vehicle data)

function RSGCore.Functions.GetVehicleProperties(vehicle)
    if DoesEntityExist(vehicle) then
        -- Returns table with all vehicle properties
        return {
            model = GetEntityModel(vehicle),
            plate = RSGCore.Functions.GetPlate(vehicle),
            bodyHealth = GetVehicleBodyHealth(vehicle),
            engineHealth = GetVehicleEngineHealth(vehicle),
            fuelLevel = GetVehicleFuelLevel(vehicle),
            dirtLevel = GetVehicleDirtLevel(vehicle),
            color1 = colorPrimary,
            color2 = colorSecondary,
            -- and many more...
        }
    end
end

-- Example

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
local props = RSGCore.Functions.GetVehicleProperties(vehicle)
print(json.encode(props))

RSGCore.Functions.SetVehicleProperties

• Set all properties of a vehicle (used for loading saved vehicle data)

function RSGCore.Functions.SetVehicleProperties(vehicle, props)
    if DoesEntityExist(vehicle) then
        -- Sets all vehicle properties from the props table
    end
end

-- Example

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
local props = {
    plate = 'NEWPLATE',
    bodyHealth = 1000.0,
    engineHealth = 1000.0,
    color1 = 12,
    color2 = 0
}
RSGCore.Functions.SetVehicleProperties(vehicle, props)

RSGCore.Functions.LookAtEntity

• Make the player ped look at an entity

---@param entity number - The entity to look at
---@param timeout number - The time in milliseconds before the function times out
---@param speed number - The speed at which the entity should turn
---@return number - The time at which the entity was looked at
function RSGCore.Functions.LookAtEntity(entity, timeout, speed)
    -- Smoothly turns player to face entity
end

-- Example

local targetPed = GetClosestPed(coords)
RSGCore.Functions.LookAtEntity(targetPed, 3000, 2.0)

RSGCore.Functions.PlayAnim

• Play an animation on the player (deprecated - use ox_lib)

---@param animDict string - The name of the animation dictionary
---@param animName string - The name of the animation within the dictionary
---@param duration number - The duration of the animation in milliseconds. -1 will play indefinitely
---@param upperbodyOnly boolean - If true, only affects the upper body
function RSGCore.Functions.PlayAnim(animDict, animName, upperbodyOnly, duration)
    local flags = upperbodyOnly and 16 or 0
    local runTime = duration or -1
    lib.playAnim(cache.ped, animDict, animName, 8.0, 3.0, runTime, flags, 0.0, false, false, true)
end

-- Example

RSGCore.Functions.PlayAnim('amb_misc@world_human_smoke@male@male_b@idle_a', 'idle_a', false, -1)

RSGCore.Functions.IsWearingGloves

• Check if the player is wearing gloves

function RSGCore.Functions.IsWearingGloves()
    local ped = PlayerPedId()
    local armIndex = GetPedDrawableVariation(ped, 3)
    local model = GetEntityModel(ped)
    if model == `mp_m_freemode_01` then
        if RSGCore.Shared.MaleNoGloves[armIndex] then
            return false
        end
    else
        if RSGCore.Shared.FemaleNoGloves[armIndex] then
            return false
        end
    end
    return true
end

-- Example

if RSGCore.Functions.IsWearingGloves() then
    print('Player is wearing gloves - no fingerprints left')
else
    print('Player is not wearing gloves - fingerprints left behind')
end

RSGCore.Functions.GetObjects

• Get all objects in the game world

function RSGCore.Functions.GetObjects()
    return GetGamePool('CObject')
end

-- Example

local objects = RSGCore.Functions.GetObjects()
for i = 1, #objects do
    local objCoords = GetEntityCoords(objects[i])
    print('Object ' .. i .. ' at: ' .. objCoords)
end

RSGCore.Functions.GetClosestPlayer

• Get the closest player to the local player or coordinates

function RSGCore.Functions.GetClosestPlayer(coords)
    -- Returns closestPlayer (id), closestDistance
end

-- Example

local closestPlayer, distance = RSGCore.Functions.GetClosestPlayer()
if closestPlayer ~= -1 and distance < 3.0 then
    print('Closest player is ' .. distance .. ' units away')
end

RSGCore.Functions.GetPeds

• Get all peds in the game world with optional ignore list

function RSGCore.Functions.GetPeds(ignoreList)
    local pedPool = GetGamePool('CPed')
    local peds = {}
    local ignoreTable = {}
    ignoreList = ignoreList or {}
    for i = 1, #ignoreList do
        ignoreTable[ignoreList[i]] = true
    end
    for i = 1, #pedPool do
        if not ignoreTable[pedPool[i]] then
            peds[#peds + 1] = pedPool[i]
        end
    end
    return peds
end

-- Example

local peds = RSGCore.Functions.GetPeds({PlayerPedId()}) -- Get all peds except player
for i = 1, #peds do
    print('Ped ' .. i .. ': ' .. peds[i])
end

RSGCore.Functions.GetClosestPed

• Get the closest ped to player or coordinates

function RSGCore.Functions.GetClosestPed(coords, ignoreList)
    -- Returns closestPed, closestDistance
end

-- Example

local closestPed, distance = RSGCore.Functions.GetClosestPed(nil, {PlayerPedId()})
if closestPed ~= -1 then
    print('Closest ped is ' .. distance .. ' units away')
end

RSGCore.Functions.GetClosestObject

• Get the closest object to player or coordinates

function RSGCore.Functions.GetClosestObject(coords)
    -- Returns closestObject, closestDistance
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local closestObject, distance = RSGCore.Functions.GetClosestObject(coords)
if closestObject ~= -1 then
    print('Closest object is ' .. distance .. ' units away')
end

RSGCore.Functions.SpawnClear

• Check if an area is clear of vehicles for spawning

function RSGCore.Functions.SpawnClear(coords, radius)
    if coords then
        coords = type(coords) == 'table' and vec3(coords.x, coords.y, coords.z) or coords
    else
        coords = GetEntityCoords(PlayerPedId())
    end
    local vehicles = GetGamePool('CVehicle')
    local closeVeh = {}
    for i = 1, #vehicles, 1 do
        local vehicleCoords = GetEntityCoords(vehicles[i])
        local distance = #(vehicleCoords - coords)
        if distance <= radius then
            closeVeh[#closeVeh + 1] = vehicles[i]
        end
    end
    if #closeVeh > 0 then return false end
    return true
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
if RSGCore.Functions.SpawnClear(coords, 5.0) then
    print('Area is clear for spawning')
else
    print('Area has vehicles blocking spawn')
end

RSGCore.Functions.GetCardinalDirection

• Get the cardinal direction an entity is facing

function RSGCore.Functions.GetCardinalDirection(entity)
    entity = DoesEntityExist(entity) and entity or PlayerPedId()
    if DoesEntityExist(entity) then
        local heading = GetEntityHeading(entity)
        if ((heading >= 0 and heading < 45) or (heading >= 315 and heading < 360)) then
            return 'North'
        elseif (heading >= 45 and heading < 135) then
            return 'West'
        elseif (heading >= 135 and heading < 225) then
            return 'South'
        elseif (heading >= 225 and heading < 315) then
            return 'East'
        end
    else
        return 'Cardinal Direction Error'
    end
end

-- Example

local direction = RSGCore.Functions.GetCardinalDirection(PlayerPedId())
print('You are facing: ' .. direction)

RSGCore.Functions.GetStreetNametAtCoords

• Get street names at coordinates

function RSGCore.Functions.GetStreetNametAtCoords(coords)
    local streetname1, streetname2 = GetStreetNameAtCoord(coords.x, coords.y, coords.z)
    return { main = GetStreetNameFromHashKey(streetname1), cross = GetStreetNameFromHashKey(streetname2) }
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local streets = RSGCore.Functions.GetStreetNametAtCoords(coords)
print('Main street: ' .. streets.main)
print('Cross street: ' .. streets.cross)

RSGCore.Functions.GetZoneAtCoords

• Get the zone/area name at coordinates

function RSGCore.Functions.GetZoneAtCoords(coords)
    return GetLabelText(GetNameOfZone(coords))
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local zone = RSGCore.Functions.GetZoneAtCoords(coords)
print('Current zone: ' .. zone)

RSGCore.Functions.GetCurrentTime

• Get the current in-game time

function RSGCore.Functions.GetCurrentTime()
    local obj = {}
    obj.min = GetClockMinutes()
    obj.hour = GetClockHours()
    if obj.hour <= 12 then
        obj.ampm = 'AM'
    elseif obj.hour >= 13 then
        obj.ampm = 'PM'
        obj.formattedHour = obj.hour - 12
    end
    if obj.min <= 9 then
        obj.formattedMin = '0' .. obj.min
    end
    return obj
end

-- Example

local time = RSGCore.Functions.GetCurrentTime()
print('Time: ' .. (time.formattedHour or time.hour) .. ':' .. (time.formattedMin or time.min) .. ' ' .. time.ampm)

RSGCore.Functions.GetGroundZCoord

• Get the ground Z coordinate at given coordinates

function RSGCore.Functions.GetGroundZCoord(coords)
    if not coords then return end
    local retval, groundZ = GetGroundZFor_3dCoord(coords.x, coords.y, coords.z, 0)
    if retval then
        return vector3(coords.x, coords.y, groundZ)
    else
        return coords
    end
end

-- Example

local coords = GetEntityCoords(PlayerPedId())
local groundCoords = RSGCore.Functions.GetGroundZCoord(coords)
print('Ground Z: ' .. groundCoords.z)