docs: refine framework notes, params, and return documentation

This commit is contained in:
MrNewb committed 2025-05-30 03:21:32 -04:00
1 parent 38ce2e8f1e
commit 7fc9ee4956
6 files changed
+257 -80

No files matched your search

+97 -26
View File
@@ -7,10 +7,14 @@ ESX = exports["es_extended"]:getSharedObject()
Framework = Framework or {}
---This will return the name of the framework in use.
---@return string
Framework.GetFrameworkName = function()
return 'es_extended'
end
---This will get the players birth date
---@return string|nil
Framework.GetPlayerDob = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -18,9 +22,7 @@ Framework.GetPlayerDob = function(src)
return dob
end
--- This will return a table of the players data
---
--- This table is in the framework format and not converted to any standard.
--- Returns the player data of the specified source in the framework defualt format.
---@param src any
---@return table | nil
Framework.GetPlayer = function(src)
@@ -31,18 +33,24 @@ end
-- Framework.GetPlayerIdentifier(src)
-- Returns the citizen ID of the player.
---@param src number
---@return string | nil
Framework.GetPlayerIdentifier = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.getIdentifier()
end
---This will return the jobs registered in the framework in a table.
---Format of the table is:
---{name = jobName, label = jobLabel, grade = {name = gradeName, level = gradeLevel}}
---@return table
Framework.GetFrameworkJobs = function()
return ESX.GetJobs()
end
-- Framework.GetPlayerName(src)
-- Returns the first and last name of the player.
---@return string|nil, string|nil
Framework.GetPlayerName = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -60,9 +68,12 @@ Framework.GetPlayers = function()
return playerList
end
-- Framework.GetItem(src, item, metadata)
-- Returns a table of items matching the specified name and if passed metadata from the player's inventory.
-- returns {name = v.name, count = v.amount, metadata = v.info, slot = v.slot}
---Returns a table of items matching the specified name and if passed metadata from the player's inventory.
---returns {name = v.name, count = v.amount, metadata = v.info, slot = v.slot}
---@param src number
---@param item string
---@param _ table
---@return table|nil
Framework.GetItem = function(src, item, _)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -81,15 +92,19 @@ Framework.GetItem = function(src, item, _)
return repackedTable
end
-- Framework.GetItemCount(src, item, _)
-- Returns the count of items matching the specified name and if passed metadata from the player's inventory.
---This will return the count of the item in the players inventory, if not found will return 0.
---if metadata is passed it will find the matching items count (esx_core does not feature metadata items).
---@param src number
---@param item string
---@param _ table
---@return number
Framework.GetItemCount = function(src, item, _)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.getInventoryItem(item).count
end
---comment
---This will return a boolean if the player has the item.
---@param src number
---@param item string
---@return boolean
@@ -100,7 +115,9 @@ end
-- Framework.GetPlayerInventory(src)
-- Returns the entire inventory of the player as a table.
-- returns {name = v.name, count = v.amount, _, _}
-- returns {name = v.name, count = v.amount, metadata = v.info, slot = v.slot}
---@param src number
---@return table | nil
Framework.GetPlayerInventory = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -121,6 +138,7 @@ end
-- Framework.SetMetadata(src, metadata, value)
-- Adds the specified metadata key and number value to the player's data.
---@return boolean|nil
Framework.SetPlayerMetadata = function(src, metadata, value)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -129,7 +147,10 @@ Framework.SetPlayerMetadata = function(src, metadata, value)
end
-- Framework.GetMetadata(src, metadata)
-- Gets the specified metadata key and value to the player's data.
-- Gets the specified metadata key to the player's data.
---@param src number
---@param metadata string
---@return any|nil
Framework.GetPlayerMetadata = function(src, metadata)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -147,12 +168,18 @@ Framework.GetStatus = function(src, column)
return xPlayer.get(column) or nil
end
---This will return a boolean if the player is dead or in last stand.
---@param src number
---@return boolean|nil
Framework.GetIsPlayerDead = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.get("is_dead") or false
end
---This will revive a player, if the player is dead or in last stand.
---@param src number
---@return boolean
Framework.RevivePlayer = function(src)
src = tonumber(src)
if not src then return false end
@@ -162,6 +189,9 @@ end
-- Framework.AddThirst(src, value)
-- Adds the specified value from the player's thirst level.
---@param src number
---@param value number
---@return number | nil
Framework.AddThirst = function(src, value)
local clampIT = Math.Clamp(value, 0, 200000)
local levelForEsx = clampIT * 2000
@@ -171,6 +201,9 @@ end
-- Framework.AddHunger(src, value)
-- Adds the specified value from the player's hunger level.
---@param src number
---@param value number
---@return number | nil
Framework.AddHunger = function(src, value)
local clampIT = Math.Clamp(value, 0, 200000)
local levelForEsx = clampIT * 2000
@@ -178,12 +211,18 @@ Framework.AddHunger = function(src, value)
return levelForEsx
end
---This will get the hunger of a player
---@param src number
---@return number | nil
Framework.GetHunger = function(src)
local status = Framework.GetStatus(src, "status")
if not status then return 0 end
return status.hunger
end
---This will get the thirst of a player
---@param src any
---@return number | nil
Framework.GetThirst = function(src)
local status = Framework.GetStatus(src, "status")
if not status then return 0 end
@@ -192,6 +231,8 @@ end
-- Framework.GetPlayerPhone(src)
-- Returns the phone number of the player.
---@param src number
---@return string | nil
Framework.GetPlayerPhone = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -242,9 +283,9 @@ Framework.GetPlayerDuty = function(src)
return true
end
---Sets the players duty status.
---This will toggle a players duty status
---@param src number
---@param dutystatus boolean
---@param status boolean
---@return boolean
Framework.SetPlayerDuty = function(src, dutystatus)
local xPlayer = Framework.GetPlayer(src)
@@ -254,22 +295,26 @@ Framework.SetPlayerDuty = function(src, dutystatus)
return xPlayer.setJob(job.name, job.grade, dutystatus)
end
-- Framework.GetPlayersByJob(jobname)
-- returns a table of player sources that have the specified job name.
---This will get a table of player sources that have the specified job name.
---@param job any
---@return table
Framework.GetPlayersByJob = function(job)
local players = GetPlayers()
local playerList = {}
for _, src in pairs(players) do
local xPlayer = Framework.GetPlayer(src)
if xPlayer.getJob().name == job then
if xPlayer and xPlayer.getJob().name == job then
table.insert(playerList, src)
end
end
return playerList
end
-- Framework.SetPlayerJob(src, name, grade)
-- Sets the player's job to the specified name and grade.
---@param src number
---@param name string
---@param grade string
---@return nil
Framework.SetPlayerJob = function(src, name, grade)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -280,8 +325,11 @@ Framework.SetPlayerJob = function(src, name, grade)
return xPlayer.setJob(name, grade, true)
end
-- Framework.AddAccountBalance(src, _type, amount)
-- Adds the specified amount to the player's account balance of the specified type.
---This will add money based on the type of account (money/bank)
---@param src number
---@param _type string
---@param amount number
---@return boolean | nil
Framework.AddAccountBalance = function(src, _type, amount)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -289,8 +337,11 @@ Framework.AddAccountBalance = function(src, _type, amount)
return xPlayer.addAccountMoney(_type, amount)
end
-- Framework.RemoveAccountBalance(src, _type, amount)
-- Removes the specified amount from the player's account balance of the specified type.
---This will remove money based on the type of account (money/bank)
---@param src number
---@param _type string
---@param amount number
---@return boolean | nil
Framework.RemoveAccountBalance = function(src, _type, amount)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -299,8 +350,10 @@ Framework.RemoveAccountBalance = function(src, _type, amount)
return true
end
-- Framework.GetAccountBalance(src, _type)
-- Returns the player's account balance of the specified type.
---This will remove money based on the type of account (money/bank)
---@param src number
---@param _type string
---@return string | nil
Framework.GetAccountBalance = function(src, _type)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -308,22 +361,37 @@ Framework.GetAccountBalance = function(src, _type)
return xPlayer.getAccount(_type).money
end
-- Framework.AddItem(src, item, amount, _, _)
-- Framework.AddItem(src, item, amount, slot, metadata)
-- Adds the specified item to the player's inventory.
---@param src number
---@param item string
---@param amount number
---@param slot number
---@param metadata table
---@return boolean | nil
Framework.AddItem = function(src, item, amount, slot, metadata)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.addInventoryItem(item, amount)
end
-- Framework.RemoveItem(src, item, amount, _, _)
-- Framework.RemoveItem(src, item, amount, slot, metadata)
-- Removes the specified item from the player's inventory.
---@param src number
---@param item string
---@param amount number
---@param slot number
---@param metadata table
---@return boolean | nil
Framework.RemoveItem = function(src, item, amount, slot, metadata)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.removeInventoryItem(item, amount)
end
---This will get all owned vehicles for the player
---@param src number
---@return table
Framework.GetOwnedVehicles = function(src)
local citizenId = Framework.GetPlayerIdentifier(src)
local result = MySQL.Sync.fetchAll("SELECT vehicle, plate FROM owned_vehicles WHERE owner = '" .. citizenId .. "'")
@@ -337,8 +405,11 @@ Framework.GetOwnedVehicles = function(src)
return vehicles
end
-- Framework.RegisterUsableItem(item, cb)
-- Registers a usable item with a callback function.
---@param itemName string
---@param cb function
Framework.RegisterUsableItem = function(itemName, cb)
local func = function(src, item, itemData)
itemData = itemData or item