diff --git a/server/functions.lua b/server/functions.lua index 54218f0..5feac75 100644 --- a/server/functions.lua +++ b/server/functions.lua @@ -8,12 +8,19 @@ QBCore.UsableItems = {} -- ex: local player = QBCore.Functions.GetPlayer(source) -- ex: local example = player.Functions.functionname(parameter) +---Gets the coordinates of an entity +---@param entity number +---@return vector4 function QBCore.Functions.GetCoords(entity) local coords = GetEntityCoords(entity, false) local heading = GetEntityHeading(entity) return vector4(coords.x, coords.y, coords.z, heading) end +---Gets player identifier of the given type +---@param source any +---@param idtype string +---@return string? function QBCore.Functions.GetIdentifier(source, idtype) local identifiers = GetPlayerIdentifiers(source) for _, identifier in pairs(identifiers) do @@ -24,6 +31,9 @@ function QBCore.Functions.GetIdentifier(source, idtype) return nil end +---Gets a players server id (source). Returns 0 if no player is found. +---@param identifier string +---@return number function QBCore.Functions.GetSource(identifier) for src, _ in pairs(QBCore.Players) do local idens = GetPlayerIdentifiers(src) @@ -36,6 +46,9 @@ function QBCore.Functions.GetSource(identifier) return 0 end +---Get player with given server id (source) +---@param source any +---@return table function QBCore.Functions.GetPlayer(source) if type(source) == 'number' then return QBCore.Players[source] @@ -44,6 +57,9 @@ function QBCore.Functions.GetPlayer(source) end end +---Get player by citizen id +---@param citizenid string +---@return table|nil function QBCore.Functions.GetPlayerByCitizenId(citizenid) for src in pairs(QBCore.Players) do if QBCore.Players[src].PlayerData.citizenid == citizenid then @@ -53,10 +69,16 @@ function QBCore.Functions.GetPlayerByCitizenId(citizenid) return nil end +---Get offline player by citizen id +---@param citizenid string +---@return table|nil function QBCore.Functions.GetOfflinePlayerByCitizenId(citizenid) return QBCore.Player.GetOfflinePlayer(citizenid) end +---Get player by phone number +---@param number number +---@return table|nil function QBCore.Functions.GetPlayerByPhone(number) for src in pairs(QBCore.Players) do if QBCore.Players[src].PlayerData.charinfo.phone == number then @@ -66,6 +88,8 @@ function QBCore.Functions.GetPlayerByPhone(number) return nil end +---Get all players. Returns the server ids of all players. +---@return table function QBCore.Functions.GetPlayers() local sources = {} for k in pairs(QBCore.Players) do @@ -74,13 +98,16 @@ function QBCore.Functions.GetPlayers() return sources end --- Will return an array of QB Player class instances --- unlike the GetPlayers() wrapper which only returns IDs +---Will return an array of QB Player class instances +---unlike the GetPlayers() wrapper which only returns IDs +---@return table function QBCore.Functions.GetQBPlayers() return QBCore.Players end ---- Gets a list of all on duty players of a specified job and the number +---Gets a list of all on duty players of a specified job and the number +---@param job string +---@return table, number function QBCore.Functions.GetPlayersOnDuty(job) local players = {} local count = 0 @@ -95,7 +122,9 @@ function QBCore.Functions.GetPlayersOnDuty(job) return players, count end --- Returns only the amount of players on duty for the specified job +---Returns only the amount of players on duty for the specified job +---@param job any +---@return number function QBCore.Functions.GetDutyCount(job) local count = 0 for _, Player in pairs(QBCore.Players) do @@ -110,13 +139,17 @@ end -- Routing buckets (Only touch if you know what you are doing) --- Returns the objects related to buckets, first returned value is the player buckets, second one is entity buckets +---Returns the objects related to buckets, first returned value is the player buckets, second one is entity buckets +---@return table, table function QBCore.Functions.GetBucketObjects() return QBCore.Player_Buckets, QBCore.Entity_Buckets end --- Will set the provided player id / source into the provided bucket id -function QBCore.Functions.SetPlayerBucket(source --[[ int ]], bucket --[[ int ]]) +---Will set the provided player id / source into the provided bucket id +---@param source any +---@param bucket any +---@return boolean +function QBCore.Functions.SetPlayerBucket(source, bucket) if source and bucket then local plicense = QBCore.Functions.GetIdentifier(source, 'license') SetPlayerRoutingBucket(source, bucket) @@ -127,8 +160,11 @@ function QBCore.Functions.SetPlayerBucket(source --[[ int ]], bucket --[[ int ]] end end --- Will set any entity into the provided bucket, for example peds / vehicles / props / etc. -function QBCore.Functions.SetEntityBucket(entity --[[ int ]], bucket --[[ int ]]) +---Will set any entity into the provided bucket, for example peds / vehicles / props / etc. +---@param entity number +---@param bucket number +---@return boolean +function QBCore.Functions.SetEntityBucket(entity, bucket) if entity and bucket then SetEntityRoutingBucket(entity, bucket) QBCore.Entity_Buckets[entity] = {id = entity, bucket = bucket} @@ -138,8 +174,10 @@ function QBCore.Functions.SetEntityBucket(entity --[[ int ]], bucket --[[ int ]] end end --- Will return an array of all the player ids inside the current bucket -function QBCore.Functions.GetPlayersInBucket(bucket --[[ int ]]) +---Will return an array of all the player ids inside the current bucket +---@param bucket number +---@return table|boolean +function QBCore.Functions.GetPlayersInBucket(bucket) local curr_bucket_pool = {} if QBCore.Player_Buckets and next(QBCore.Player_Buckets) then for _, v in pairs(QBCore.Player_Buckets) do @@ -153,8 +191,11 @@ function QBCore.Functions.GetPlayersInBucket(bucket --[[ int ]]) end end --- Will return an array of all the entities inside the current bucket (not for player entities, use GetPlayersInBucket for that) -function QBCore.Functions.GetEntitiesInBucket(bucket --[[ int ]]) +---Will return an array of all the entities inside the current bucket +---(not for player entities, use GetPlayersInBucket for that) +---@param bucket number +---@return table|boolean +function QBCore.Functions.GetEntitiesInBucket(bucket) local curr_bucket_pool = {} if QBCore.Entity_Buckets and next(QBCore.Entity_Buckets) then for _, v in pairs(QBCore.Entity_Buckets) do @@ -168,8 +209,13 @@ function QBCore.Functions.GetEntitiesInBucket(bucket --[[ int ]]) end end --- Server side vehicle creation with optional callback --- the CreateVehicle RPC still uses the client for creation so players must be near +---Server side vehicle creation with optional callback +---the CreateVehicle RPC still uses the client for creation so players must be near +---@param source any +---@param model any +---@param coords vector +---@param warp boolean +---@return number function QBCore.Functions.SpawnVehicle(source, model, coords, warp) local ped = GetPlayerPed(source) model = type(model) == 'string' and joaat(model) or model @@ -186,9 +232,15 @@ function QBCore.Functions.SpawnVehicle(source, model, coords, warp) return veh end --- Server side vehicle creation with optional callback --- the CreateAutomobile native is still experimental but doesn't use client for creation --- doesn't work for all vehicles! +---Server side vehicle creation with optional callback +---the CreateAutomobile native is still experimental but doesn't use client for creation +---doesn't work for all vehicles! +---comment +---@param source any +---@param model any +---@param coords vector +---@param warp boolean +---@return number function QBCore.Functions.CreateVehicle(source, model, coords, warp) model = type(model) == 'string' and joaat(model) or model if not coords then coords = GetEntityCoords(GetPlayerPed(source)) end @@ -199,7 +251,7 @@ function QBCore.Functions.CreateVehicle(source, model, coords, warp) return veh end --- Paychecks (standalone - don't touch) +---Paychecks (standalone - don't touch) function PaycheckInterval() if next(QBCore.Players) then for _, Player in pairs(QBCore.Players) do @@ -234,17 +286,28 @@ end -- Callback Functions -- --- Client Callback +---Trigger Client Callback +---@param name string +---@param source any +---@param cb function +---@param ... any function QBCore.Functions.TriggerClientCallback(name, source, cb, ...) QBCore.ClientCallbacks[name] = cb TriggerClientEvent('QBCore:Client:TriggerClientCallback', source, name, ...) end --- Server Callback +---Create Server Callback +---@param name string +---@param cb function function QBCore.Functions.CreateCallback(name, cb) QBCore.ServerCallbacks[name] = cb end +---Trigger Serv er Callback +---@param name string +---@param source any +---@param cb function +---@param ... any function QBCore.Functions.TriggerCallback(name, source, cb, ...) if not QBCore.ServerCallbacks[name] then return end QBCore.ServerCallbacks[name](source, cb, ...) @@ -252,21 +315,33 @@ end -- Items +---Create a usable item +---@param item string +---@param data function function QBCore.Functions.CreateUseableItem(item, data) QBCore.UsableItems[item] = data end +---Checks if the given item is usable +---@param item string +---@return any function QBCore.Functions.CanUseItem(item) return QBCore.UsableItems[item] end +---Use item +---@param source any +---@param item string function QBCore.Functions.UseItem(source, item) if GetResourceState('qb-inventory') == 'missing' then return end exports['qb-inventory']:UseItem(source, item) end --- Kick Player - +---Kick Player +---@param source any +---@param reason string +---@param setKickReason boolean +---@param deferrals boolean function QBCore.Functions.Kick(source, reason, setKickReason, deferrals) reason = '\n' .. reason .. '\n🔸 Check our Discord for further information: ' .. QBCore.Config.Server.Discord if setKickReason then @@ -297,8 +372,9 @@ function QBCore.Functions.Kick(source, reason, setKickReason, deferrals) end) end --- Check if player is whitelisted, kept like this for backwards compatibility or future plans - +---Check if player is whitelisted, kept like this for backwards compatibility or future plans +---@param source any +---@return boolean function QBCore.Functions.IsWhitelisted(source) if not QBCore.Config.Server.Whitelist then return true end if QBCore.Functions.HasPermission(source, QBCore.Config.Server.WhitelistPermission) then return true end @@ -307,6 +383,9 @@ end -- Setting & Removing Permissions +---Add permission for player +---@param source any +---@param permission string function QBCore.Functions.AddPermission(source, permission) if not IsPlayerAceAllowed(source, permission) then ExecuteCommand(('add_principal player.%s qbcore.%s'):format(source, permission)) @@ -314,6 +393,9 @@ function QBCore.Functions.AddPermission(source, permission) end end +---Remove permission from player +---@param source any +---@param permission string function QBCore.Functions.RemovePermission(source, permission) if permission then if IsPlayerAceAllowed(source, permission) then @@ -332,6 +414,10 @@ end -- Checking for Permission Level +---Check if player has permission +---@param source any +---@param permission string +---@return boolean function QBCore.Functions.HasPermission(source, permission) if type(permission) == "string" then if IsPlayerAceAllowed(source, permission) then return true end @@ -344,6 +430,9 @@ function QBCore.Functions.HasPermission(source, permission) return false end +---Get the players permissions +---@param source any +---@return table function QBCore.Functions.GetPermission(source) local src = source local perms = {} @@ -355,8 +444,9 @@ function QBCore.Functions.GetPermission(source) return perms end --- Opt in or out of admin reports - +---Get admin messages opt-in state for player +---@param source any +---@return boolean function QBCore.Functions.IsOptin(source) local license = QBCore.Functions.GetIdentifier(source, 'license') if not license or not QBCore.Functions.HasPermission(source, 'admin') then return false end @@ -364,6 +454,8 @@ function QBCore.Functions.IsOptin(source) return Player.PlayerData.optin end +---Toggle opt-in to admin messages +---@param source any function QBCore.Functions.ToggleOptin(source) local license = QBCore.Functions.GetIdentifier(source, 'license') if not license or not QBCore.Functions.HasPermission(source, 'admin') then return end @@ -372,8 +464,9 @@ function QBCore.Functions.ToggleOptin(source) Player.Functions.SetPlayerData('optin', Player.PlayerData.optin) end --- Check if player is banned - +---Check if player is banned +---@param source any +---@return boolean, string? function QBCore.Functions.IsPlayerBanned(source) local plicense = QBCore.Functions.GetIdentifier(source, 'license') local result = MySQL.single.await('SELECT * FROM bans WHERE license = ?', { plicense }) @@ -387,8 +480,9 @@ function QBCore.Functions.IsPlayerBanned(source) return false end --- Check for duplicate license - +---Check for duplicate license +---@param license any +---@return boolean function QBCore.Functions.IsLicenseInUse(license) local players = GetPlayers() for _, player in pairs(players) do @@ -406,17 +500,31 @@ end -- Utility functions +---Check if a player has an item [deprecated] +---@param source any +---@param items table|string +---@param amount number +---@return boolean function QBCore.Functions.HasItem(source, items, amount) if GetResourceState('qb-inventory') == 'missing' then return end return exports['qb-inventory']:HasItem(source, items, amount) end +---Notify +---@param source any +---@param text string +---@param type string +---@param length number function QBCore.Functions.Notify(source, text, type, length) TriggerClientEvent('QBCore:Notify', source, text, type, length) end ---- SQL Pattern Matching -function QBCore.Functions.PrepForSQL(source,data,pattern) +---???? ... ok +---@param source any +---@param data any +---@param pattern any +---@return boolean +function QBCore.Functions.PrepForSQL(source, data, pattern) data = tostring(data) local src = source local player = QBCore.Functions.GetPlayer(src)