🖥️ Server Function Reference

Learn about and how to use common core server functions!

RSGCore.Functions.GetCoords

• Get the coords of a passed entity

---@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 ped = GetPlayerPed(source)
local coords = RSGCore.Functions.GetCoords(ped)
print(coords)

RSGCore.Functions.GetIdentifier

• Get the identifier of a passed entity

---@param source any
---@param idtype string
---@return string?
function RSGCore.Functions.GetIdentifier(source, idtype)
    return GetPlayerIdentifierByType(source, idtype or 'license')
end

-- Example

local identifier = RSGCore.Functions.GetIdentifier(source, 'license')
print(identifier)

OR -- defaults to the identifier in the config of rsg-core

local identifier = RSGCore.Functions.GetIdentifier(source)
print(identifier)

RSGCore.Functions.GetSource

• Gets a players server id (source). Returns 0 if no player is found.

---@param identifier string
---@return number
function RSGCore.Functions.GetSource(identifier)
    for src, _ in pairs(RSGCore.Players) do
        local idens = GetPlayerIdentifiers(src)
        for _, id in pairs(idens) do
            if identifier == id then
                return src
            end
        end
    end
    return 0
end

-- Example

local identifier = RSGCore.Functions.GetIdentifier(source, 'license')
local playerSource = RSGCore.Functions.GetSource(identifier)
print(playerSource)

RSGCore.Functions.GetPlayer

• Get player with given server id (source)

---@param source any
---@return table
function RSGCore.Functions.GetPlayer(source)
    if type(source) == 'number' then
        return RSGCore.Players[source]
    else
        return RSGCore.Players[RSGCore.Functions.GetSource(source)]
    end
end

-- Example

local Player = RSGCore.Functions.GetPlayer(source)
print(RSGCore.Debug(Player))

OR -- access some player data

local Player = RSGCore.Functions.GetPlayer(source)
print(Player.PlayerData.citizenid)

RSGCore.Functions.GetPlayerByCitizenId

• Get player by citizen id

---@param citizenid string
---@return table?
function RSGCore.Functions.GetPlayerByCitizenId(citizenid)
    for src in pairs(RSGCore.Players) do
        if RSGCore.Players[src].PlayerData.citizenid == citizenid then
            return RSGCore.Players[src]
        end
    end
    return nil
end

-- Example

local Player = RSGCore.Functions.GetPlayerByCitizenId('ONZ55343')
print(RSGCore.Debug(Player))

OR -- access some player data

local Player = RSGCore.Functions.GetPlayerByCitizenId('ONZ55343')
print(Player.PlayerData.license)

RSGCore.Functions.GetPlayers

• Get all players. Returns the server ids of all players.

---@return table
function RSGCore.Functions.GetPlayers()
    local sources = {}
    for k in pairs(RSGCore.Players) do
        sources[#sources + 1] = k
    end
    return sources
end

-- Example

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

RSGCore.Functions.GetRSGPlayers

• Will return an array of RSG Player class instances unlike the GetPlayers() wrapper which only returns IDs

---@return table
function RSGCore.Functions.GetRSGPlayers()
    return RSGCore.Players
end

-- Example

local Players = RSGCore.Functions.GetRSGPlayers()
print(RSGCore.Debug(Players))

RSGCore.Functions.CreateCallBack

• Create Server Callback.

---@param name string
---@param cb function
function RSGCore.Functions.CreateCallback(name, cb)
    RSGCore.ServerCallbacks[name] = cb
end

-- Example

RSGCore.Functions.CreateCallback('callbackName', function(source, cb)
    cb('Ok')
end)

RSGCore.Functions.CreateUseableItem

• Create a usable item

---@param item string
---@param data function
function RSGCore.Functions.CreateUseableItem(item, data)
    RSGCore.UsableItems[item] = data
end

-- Example

RSGCore.Functions.CreateUseableItem('my_cool_item', function(source, item)
	local Player = RSGCore.Functions.GetPlayer(source)
	if not Player.Functions.GetItemByName(item.name) then return end
	-- Trigger code here for what item should do
end)

RSGCore.Functions.CanUseItem

• Check if a player can use an item

---@param item string
---@return any
function RSGCore.Functions.CanUseItem(item)
    return RSGCore.UsableItems[item]
end

-- Example

local canUse = RSGCore.Functions.CanUseItem('my_cool_item')
print(canUse)

OR

local canUse = RSGCore.Functions.CanUseItem('my_cool_item')
if not canUse then return end
-- Trigger code here

RSGCore.Functions.UseItem

• Use an item

---@param source any
---@param item string
function RSGCore.Functions.UseItem(source, item)
    if GetResourceState('rsg-inventory') == 'missing' then return end
    exports['rsg-inventory']:UseItem(source, item)
end

-- Example

local Player = RSGCore.Functions.GetPlayer(source)
if not Player.Functions.GetItemByName('my_cool_item') then return end
RSGCore.Functions.UseItem(source, 'my_cool_item')

RSGCore.Functions.GetOfflinePlayerByCitizenId

• Get offline player data by citizen id (pulls from database)

---@param citizenid string
---@return table?
function RSGCore.Functions.GetOfflinePlayerByCitizenId(citizenid)
    return RSGCore.Player.GetOfflinePlayer(citizenid)
end

-- Example

local OfflinePlayer = RSGCore.Functions.GetOfflinePlayerByCitizenId('ABC12345')
if OfflinePlayer then
    print(OfflinePlayer.PlayerData.charinfo.firstname)
end

RSGCore.Functions.GetPlayerByLicense

• Get player by license (checks online players first, then database)

---@param license string
---@return table?
function RSGCore.Functions.GetPlayerByLicense(license)
    return RSGCore.Player.GetPlayerByLicense(license)
end

-- Example

local license = 'license:1234567890abcdef'
local Player = RSGCore.Functions.GetPlayerByLicense(license)
if Player then
    print(Player.PlayerData.name)
end

RSGCore.Functions.GetPlayerByAccount

• Get player by account number

---@param account string
---@return table?
function RSGCore.Functions.GetPlayerByAccount(account)
    for src in pairs(RSGCore.Players) do
        if RSGCore.Players[src].PlayerData.charinfo.account == account then
            return RSGCore.Players[src]
        end
    end
    return nil
end

-- Example

local Player = RSGCore.Functions.GetPlayerByAccount('US04RSG1234567890')
if Player then
    print(Player.PlayerData.citizenid)
end

RSGCore.Functions.GetPlayerByCharInfo

• Get player by any character info property

---@param property string
---@param value string
---@return table?
function RSGCore.Functions.GetPlayerByCharInfo(property, value)
    for src in pairs(RSGCore.Players) do
        local charinfo = RSGCore.Players[src].PlayerData.charinfo
        if charinfo[property] ~= nil and charinfo[property] == value then
            return RSGCore.Players[src]
        end
    end
    return nil
end

-- Example

-- Find player by first name
local Player = RSGCore.Functions.GetPlayerByCharInfo('firstname', 'John')
if Player then
    print(Player.PlayerData.charinfo.lastname)
end

RSGCore.Functions.GetPlayersOnDuty

• Get all players on duty for a specific job

---@param job string
---@return table, number
function RSGCore.Functions.GetPlayersOnDuty(job)
    local players = {}
    local count = 0
    for src, Player in pairs(RSGCore.Players) do
        if Player.PlayerData.job.name == job then
            if Player.PlayerData.job.onduty then
                players[#players + 1] = src
                count += 1
            end
        end
    end
    return players, count
end

-- Example

local cops, copCount = RSGCore.Functions.GetPlayersOnDuty('vallaw')
print('There are '.. copCount ..' cops on duty')
for i = 1, #cops do
    print('Cop source: '.. cops[i])
end

RSGCore.Functions.GetDutyCount

• Get the count of players on duty for a specific job

---@param job string
---@return number
function RSGCore.Functions.GetDutyCount(job)
    local count = 0
    for _, Player in pairs(RSGCore.Players) do
        if Player.PlayerData.job.name == job then
            if Player.PlayerData.job.onduty then
                count += 1
            end
        end
    end
    return count
end

-- Example

local copCount = RSGCore.Functions.GetDutyCount('vallaw')
if copCount < 2 then
    print('Not enough cops online!')
end

RSGCore.Functions.GetClosestPlayer

• Get the closest player to a source player or coordinates

---@param source number
---@param coords vector
---@return number, number
function RSGCore.Functions.GetClosestPlayer(source, coords)
    -- Returns closestPlayer (server id), closestDistance
end

-- Example

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

RSGCore.Functions.SetPlayerBucket

• Set a player’s routing bucket (for instancing)

---@param source any
---@param bucket any
---@return boolean
function RSGCore.Functions.SetPlayerBucket(source, bucket)
    if source and bucket then
        local plicense = RSGCore.Functions.GetIdentifier(source, 'license')
        Player(source).state:set('instance', bucket, true)
        SetPlayerRoutingBucket(source, bucket)
        RSGCore.Player_Buckets[plicense] = { id = source, bucket = bucket }
        return true
    else
        return false
    end
end

-- Example

-- Put player in their own instance (bucket 1)
RSGCore.Functions.SetPlayerBucket(source, 1)

RSGCore.Functions.SetEntityBucket

• Set an entity’s routing bucket

---@param entity number
---@param bucket number
---@return boolean
function RSGCore.Functions.SetEntityBucket(entity, bucket)
    if entity and bucket then
        SetEntityRoutingBucket(entity, bucket)
        RSGCore.Entity_Buckets[entity] = { id = entity, bucket = bucket }
        return true
    else
        return false
    end
end

-- Example

local vehicle = GetVehiclePedIsIn(GetPlayerPed(source))
RSGCore.Functions.SetEntityBucket(vehicle, 1)

RSGCore.Functions.GetPlayersInBucket

• Get all players in a specific routing bucket

---@param bucket number
---@return table|boolean
function RSGCore.Functions.GetPlayersInBucket(bucket)
    local curr_bucket_pool = {}
    if RSGCore.Player_Buckets and next(RSGCore.Player_Buckets) then
        for _, v in pairs(RSGCore.Player_Buckets) do
            if v.bucket == bucket then
                curr_bucket_pool[#curr_bucket_pool + 1] = v.id
            end
        end
        return curr_bucket_pool
    else
        return false
    end
end

-- Example

local playersInBucket = RSGCore.Functions.GetPlayersInBucket(1)
if playersInBucket then
    for i = 1, #playersInBucket do
        print('Player in bucket: '.. playersInBucket[i])
    end
end

RSGCore.Functions.SpawnVehicle

• Server-side vehicle spawning

---@param source any
---@param model any
---@param coords vector
---@param warp boolean
---@return number
function RSGCore.Functions.SpawnVehicle(source, model, coords, warp)
    -- Spawns vehicle and returns vehicle handle
end

-- Example

local coords = GetEntityCoords(GetPlayerPed(source))
local veh = RSGCore.Functions.SpawnVehicle(source, 'CART01', coords, true)
print('Spawned vehicle: '.. veh)

RSGCore.Functions.Kick

• Kick a player from the server

---@param source any
---@param reason string
---@param setKickReason boolean
---@param deferrals boolean
function RSGCore.Functions.Kick(source, reason, setKickReason, deferrals)
    reason = '\n' .. reason .. '\n🔸 Check our Discord for further information: ' .. RSGCore.Config.Server.Discord
    -- Handles the kick with retries
end

-- Example

RSGCore.Functions.Kick(source, 'You have been kicked for: Cheating', false, false)

RSGCore.Functions.IsWhitelisted

• Check if a player is whitelisted

---@param source any
---@return boolean
function RSGCore.Functions.IsWhitelisted(source)
    if not RSGCore.Config.Server.Whitelist then return true end
    if RSGCore.Functions.HasPermission(source, RSGCore.Config.Server.WhitelistPermission) then return true end
    return false
end

-- Example

if not RSGCore.Functions.IsWhitelisted(source) then
    RSGCore.Functions.Kick(source, 'You are not whitelisted', false, false)
end

RSGCore.Functions.AddPermission

• Add a permission to a player

---@param source any
---@param permission string
function RSGCore.Functions.AddPermission(source, permission)
    if not IsPlayerAceAllowed(source, permission) then
        ExecuteCommand(('add_principal player.%s rsgcore.%s'):format(source, permission))
        RSGCore.Commands.Refresh(source)
    end
end

-- Example

RSGCore.Functions.AddPermission(source, 'admin')

RSGCore.Functions.RemovePermission

• Remove a permission from a player

---@param source any
---@param permission string
function RSGCore.Functions.RemovePermission(source, permission)
    if permission then
        if IsPlayerAceAllowed(source, permission) then
            ExecuteCommand(('remove_principal player.%s rsgcore.%s'):format(source, permission))
            RSGCore.Commands.Refresh(source)
        end
    end
end

-- Example

RSGCore.Functions.RemovePermission(source, 'admin')

RSGCore.Functions.HasPermission

• Check if a player has a specific permission

---@param source any
---@param permission string|table
---@return boolean
function RSGCore.Functions.HasPermission(source, permission)
    if type(permission) == 'string' then
        if IsPlayerAceAllowed(source, permission) then return true end
    elseif type(permission) == 'table' then
        for _, permLevel in pairs(permission) do
            if IsPlayerAceAllowed(source, permLevel) then return true end
        end
    end
    return false
end

-- Example

if RSGCore.Functions.HasPermission(source, 'admin') then
    print('Player is an admin')
end

-- Check multiple permissions
if RSGCore.Functions.HasPermission(source, {'admin', 'mod'}) then
    print('Player is admin or mod')
end

RSGCore.Functions.GetPermission

• Get all permissions for a player

---@param source any
---@return table
function RSGCore.Functions.GetPermission(source)
    local perms = {}
    for _, v in pairs(RSGCore.Config.Server.Permissions) do
        if IsPlayerAceAllowed(src, v) then
            perms[v] = true
        end
    end
    return perms
end

-- Example

local perms = RSGCore.Functions.GetPermission(source)
for perm, enabled in pairs(perms) do
    print(perm .. ': ' .. tostring(enabled))
end

RSGCore.Functions.IsPlayerBanned

• Check if a player is banned

---@param source any
---@return boolean, string?
function RSGCore.Functions.IsPlayerBanned(source)
    local plicense = RSGCore.Functions.GetIdentifier(source, 'license')
    local result = MySQL.single.await('SELECT id, reason, expire FROM bans WHERE license = ?', { plicense })
    if not result then return false end
    if os.time() < result.expire then
        -- Returns true and ban message
        return true, 'Ban message here...'
    else
        MySQL.query('DELETE FROM bans WHERE id = ?', { result.id })
    end
    return false
end

-- Example

local isBanned, reason = RSGCore.Functions.IsPlayerBanned(source)
if isBanned then
    RSGCore.Functions.Kick(source, reason, false, false)
end

RSGCore.Functions.IsLicenseInUse

• Check if a license is currently in use (duplicate check)

---@param license any
---@return boolean
function RSGCore.Functions.IsLicenseInUse(license)
    local players = GetPlayers()
    for _, player in pairs(players) do
        local playerLicense = RSGCore.Functions.GetIdentifier(player, 'license')
        if playerLicense == license then return true end
    end
    return false
end

-- Example

if RSGCore.Functions.IsLicenseInUse(license) then
    print('This license is already connected')
end