es_extended framework code cleanup

This commit is contained in:
solaire-fivem committed 2025-08-31 18:41:12 +01:00
1 parent 957e2e2ff6
commit f5017792e3
2 files changed
+196 -202

No files matched your search

+62 -61
View File
@@ -1,13 +1,14 @@
---@diagnostic disable: duplicate-set-field
if GetResourceState('es_extended') ~= 'started' then return end
ESX = exports["es_extended"]:getSharedObject()
ESX = exports.es_extended:getSharedObject()
Callback = Callback or Require("lib/utility/shared/callbacks.lua")
Framework = Framework or {}
local cachedItemList = nil
-- This is an internal function, its here to attempt to emulate qbs shared items mainly.
--- @description This is an internal function, its here to attempt to emulate qbs shared items mainly
Framework.ItemList = function()
if cachedItemList then return cachedItemList end
local items = Callback.Trigger('community_bridge:Callback:GetFrameworkItems', false)
@@ -15,98 +16,99 @@ Framework.ItemList = function()
return cachedItemList
end
---This will get the name of the framework being used (if a supported framework).
---@return string
--- @description This will get the name of the framework being used (if a supported framework).
--- @return string
Framework.GetFrameworkName = function()
return 'es_extended'
end
---This will return true if the player is loaded, false otherwise.
---This could be useful in scripts that rely on player loaded events and offer a debug mode to hit this function.
---@return boolean
--- @description This will return true if the player is loaded, false otherwise.
--- This could be useful in scripts that rely on player loaded events and offer a debug mode to hit this function
--- @return boolean
Framework.GetIsPlayerLoaded = function()
return ESX.IsPlayerLoaded()
end
---This will return a table of the player data, this will be in the framework format.
---This is mainly for internal bridge use and should be avoided.
---@return table
--- @description This will return a table of the player data, this will be in the framework format
--- This is mainly for internal bridge use and should be avoided.
--- @return table
Framework.GetPlayerData = function()
return ESX.GetPlayerData()
end
---This will return a table of all the jobs in the framework.
---@return table
--- @description This will return a table of all the jobs in the framework.
--- @return table
Framework.GetFrameworkJobs = function()
local jobs = Callback.Trigger('community_bridge:Callback:GetFrameworkJobs', false)
return jobs
end
---This will return the players birth date
---@return string
--- @description This will return the players birth date
--- @return string
Framework.GetPlayerDob = function()
local playerData = Framework.GetPlayerData()
local dob = playerData.dateofbirth
return dob
end
---This will return the players metadata for the specified metadata key.
---@param metadata table | string
--- @description This will return the players metadata for the specified metadata key.
--- @param metadata table | string
---@return table | string | number | boolean
Framework.GetPlayerMetaData = function(metadata)
return Framework.GetPlayerData().metadata[metadata]
end
---This will send a notification to the player.
---@param message string
---@param type string
---@param time number
---@return nil
--- @description This will send a notification to the player.
--- @param message string
--- @param type string
--- @param time number
--- @return nil
Framework.Notify = function(message, type, time)
return ESX.ShowNotification(message, type, time)
end
---Will Display the help text message on the screen
---@param message string
---@param _ unknown
---@return nil
--- @description This will display the help text message on the screen
--- @param message string
--- @param _ unknown
--- @return nil
Framework.ShowHelpText = function(message, _)
return exports['esx_textui']:TextUI(message, "info")
return exports.esx_textui:TextUI(message, "info")
end
---This will hide the help text message on the screen
---@return nil
--- @description This will hide the help text message on the screen
--- @return nil
Framework.HideHelpText = function()
return exports['esx_textui']:HideUI()
return exports.esx_textui:HideUI()
end
---This will get the players identifier (citizenid) etc.
--- @description This will get the players identifier (citizenid) etc.
---@return string
Framework.GetPlayerIdentifier = function()
local playerData = Framework.GetPlayerData()
return playerData.identifier
end
---This will get the players name (first and last).
---@return string
---@return string
--- @description This will get the players name (first and last).
--- @return string
--- @return string
Framework.GetPlayerName = function()
local playerData = Framework.GetPlayerData()
return playerData.firstName, playerData.lastName
end
---Depricated : This will return the players job name, job label, job grade label and job grade level
---@return string
---@return string
---@return string
---@return string
--- @deprecated This will return the players job name, job label, job grade label and job grade level
--- @return string returns job name
--- @return string returns job label
--- @return string returns job grade label
--- @return string returns job grade level
Framework.GetPlayerJob = function()
local playerData = Framework.GetPlayerData()
return playerData.job.name, playerData.job.label, playerData.job.grade_label, playerData.job.grade
end
---This will return the players job name, job label, job grade label job grade level, boss status, and duty status in a table
---@return table
--- @description This will return the players job name, job label, job grade label job grade level,
--- boss status, and duty status in a table
--- @return table
Framework.GetPlayerJobData = function()
local playerData = Framework.GetPlayerData()
local jobData = playerData.job
@@ -122,34 +124,33 @@ Framework.GetPlayerJobData = function()
}
end
---This will return if the player has the specified item in their inventory.
---@param item string
---@return boolean
--- @description This will return if the player has the specified item in their inventory
--- @param item string
--- @return boolean
Framework.HasItem = function(item)
local hasItem = ESX.SearchInventory(item, true)
return hasItem > 0 and true or false
end
---This will return the item count for the specified item in the players inventory.
---@param item string
---@return number
--- @description This will return the item count for the specified item in the players inventory
--- @param item string
--- @return number
Framework.GetItemCount = function(item)
local inventory = Framework.GetPlayerInventory()
if not inventory then return 0 end
return inventory[item].count or 0
end
---This will return a table of the players inventory
---@return table
--- @description This will return a table of the players inventory
--- @return table
Framework.GetPlayerInventory = function()
local playerData = Framework.GetPlayerData()
return playerData.inventory
end
---This will return the players money by type, I recommend not useing this as its the client and not secure or to be trusted.
---Use case is for a ui or a menu I guess.
---@param _type string
---@return number
--- @description This will return the players money by type, I recommend not using this as its the client and not secure or to be trusted
--- @param _type string
--- @return number
Framework.GetAccountBalance = function(_type)
local player = Framework.GetPlayerData()
if not player then return 0 end
@@ -163,19 +164,19 @@ Framework.GetAccountBalance = function(_type)
return 0
end
---This will return the vehicle properties for the specified vehicle.
---@param vehicle number
---@return table
--- @description This will return the vehicle properties for the specified vehicle
--- @param vehicle number
--- @return table
Framework.GetVehicleProperties = function(vehicle)
if not vehicle or not DoesEntityExist(vehicle) then return {} end
local vehicleProps = ESX.Game.GetVehicleProperties(vehicle)
return vehicleProps or {}
end
---This will set the vehicle properties for the specified vehicle.
---@param vehicle number
---@param properties table
---@return boolean
--- @description This will set the vehicle properties for the specified vehicle
--- @param vehicle number
--- @param properties table
--- @return boolean
Framework.SetVehicleProperties = function(vehicle, properties)
if not vehicle or not DoesEntityExist(vehicle) then return false end
if not properties then return false end
@@ -203,8 +204,8 @@ Framework.SetVehicleProperties = function(vehicle, properties)
return true, ESX.Game.SetVehicleProperties(vehicle, properties)
end
---This will get a players dead status.
---@return boolean
--- @description This will get a players dead status
--- @return boolean
Framework.GetIsPlayerDead = function()
local playerData = Framework.GetPlayerData()
return playerData.dead
+134 -141
View File
@@ -4,19 +4,19 @@ if GetResourceState('es_extended') ~= 'started' then return end
Prints = Prints or Require("lib/utility/shared/prints.lua")
Callback = Callback or Require("lib/utility/shared/callbacks.lua")
ESX = exports["es_extended"]:getSharedObject()
ESX = exports.es_extended:getSharedObject()
Framework = Framework or {}
local cachedItemList = nil
---This will return the name of the framework in use.
---@return string
--- @description This will return the name of the framework in use
--- @return string
Framework.GetFrameworkName = function()
return 'es_extended'
end
-- This is an internal function, its here to attempt to emulate qbs shared items mainly.
--- @description This is an internal function, its here to attempt to emulate qbs shared items mainly
Framework.ItemList = function()
if cachedItemList then return cachedItemList end
local items = ESX.Items
@@ -40,9 +40,9 @@ Framework.ItemList = function()
return cachedItemList
end
---This will return if the player is an admin in the framework.
---@param src any
---@return boolean
--- @description This will return if the player is an admin in the framework
--- @param src any
--- @return boolean
Framework.GetIsFrameworkAdmin = function(src)
if not src then return false end
local xPlayer = Framework.GetPlayer(src)
@@ -52,8 +52,8 @@ Framework.GetIsFrameworkAdmin = function(src)
return false
end
---This will get the players birth date
---@return string|nil
--- @description 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
@@ -61,43 +61,40 @@ Framework.GetPlayerDob = function(src)
return dob
end
--- Returns the player data of the specified source in the framework defualt format.
---@param src any
---@return table | nil
--- @description Returns the player data of the specified source in the framework defualt format
--- @param src any
--- @return table | nil
Framework.GetPlayer = function(src)
local xPlayer = ESX.GetPlayerFromId(src)
if not xPlayer then return end
return xPlayer
end
-- Framework.GetPlayerIdentifier(src)
-- Returns the citizen ID of the player.
---@param src number
---@return string | nil
--- @description Returns the citizen ID of the player.
--- @param src number
--- @return string | nil returns the citizen ID of the player if it exists
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
--- @description This will return the jobs registered in the framework in a table.
--- @return table in the format "{name = jobName, label = jobLabel, grade = {name = gradeName, level = gradeLevel}}"
Framework.GetFrameworkJobs = function()
return ESX.GetJobs()
end
-- Framework.GetPlayerName(src)
-- Returns the first and last name of the player.
---@return string|nil, string|nil
--- @description This will return the first and last name of the player.
--- @return string|nil, string|nil returns the first and last name of the player
Framework.GetPlayerName = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.variables.firstName, xPlayer.variables.lastName
end
---This will return a table of all logged in players
---@return table
--- @description This will return a table of all logged in players
--- @return table
Framework.GetPlayers = function()
local players = ESX.GetExtendedPlayers()
local playerList = {}
@@ -107,12 +104,11 @@ Framework.GetPlayers = function()
return playerList
end
---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
--- @description This will return a table of items matching the specified name and if passed metadata from the player's inventory
--- @param src number
--- @param item string
--- @param _ table
--- @return table|nil returns {name = v.name, count = v.amount, metadata = v.info, slot = v.slot}
Framework.GetItem = function(src, item, _)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -131,32 +127,29 @@ Framework.GetItem = function(src, item, _)
return repackedTable
end
---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
--- @param src number
--- @param item string
--- @param _ table
--- @return number returns 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)
Framework.GetItemCount = function(src, item, _)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.getInventoryItem(item).count
end
---This will return a boolean if the player has the item.
---@param src number
---@param item string
---@return boolean
--- @description This will return true if the player has the item, false otherwise
--- @param src number
--- @param item string
--- @return boolean returns true if the player has the item, false otherwise.
Framework.HasItem = function(src, item)
local getCount = Framework.GetItemCount(src, item, nil)
return getCount > 0
end
-- Framework.GetPlayerInventory(src)
-- Returns the entire inventory of the player as a table.
-- returns {name = v.name, count = v.amount, metadata = v.info, slot = v.slot}
---@param src number
---@return table | nil
--- @description This will return the player's inventory as a table
--- @param src number
--- @return table | nil returns the player's inventory as a table in format: {name = v.name, count = v.amount, metadata = v.info, slot = v.slot}
Framework.GetPlayerInventory = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -175,9 +168,11 @@ Framework.GetPlayerInventory = function(src)
return repackedTable
end
-- Framework.SetMetadata(src, metadata, value)
-- Adds the specified metadata key and number value to the player's data.
---@return boolean|nil
--- @description Adds the specified metadata key and number value to the player's data.
--- @param src number
--- @param metadata string
--- @param value any
--- @return boolean|nil returns true if the metadata was set successfully, otherwise it returns nil
Framework.SetPlayerMetadata = function(src, metadata, value)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -186,39 +181,44 @@ Framework.SetPlayerMetadata = function(src, metadata, value)
end
-- Framework.GetMetadata(src, metadata)
-- Gets the specified metadata key to the player's data.
---@param src number
---@param metadata string
---@return any|nil
--- @description 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
return xPlayer.getMeta(metadata) or false
end
-- defualt esx Available tables are
-- identifier, accounts, group, inventory, job, job_grade, loadout,
-- metadata, position, firstname, lastname, dateofbirth, sex, height,
-- skin, status, is_dead, id, disabled, last_property, created_at, last_seen,
-- phone_number, pincode
--- @description This will return the specified status column of the player.
--- @param src number
--- @param column string
--- @return string|nil
Framework.GetStatus = function(src, column)
--[[
defualt esx Available tables are:
identifier, accounts, group, inventory, job, job_grade, loadout, metadata, position,
firstname, lastname, dateofbirth, sex, height, skin, status, is_dead, id, disabled,
last_property, created_at, last_seen, phone_number, pincode
]]
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
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
--- @description 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
--- @description 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
@@ -226,11 +226,10 @@ Framework.RevivePlayer = function(src)
return true
end
-- Framework.AddThirst(src, value)
-- Adds the specified value from the player's thirst level.
---@param src number
---@param value number
---@return number | nil
--- @description 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
@@ -238,11 +237,10 @@ Framework.AddThirst = function(src, value)
return levelForEsx
end
-- Framework.AddHunger(src, value)
-- Adds the specified value from the player's hunger level.
---@param src number
---@param value number
---@return number | nil
--- @description 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
@@ -250,36 +248,34 @@ Framework.AddHunger = function(src, value)
return levelForEsx
end
---This will get the hunger of a player
---@param src number
---@return number | nil
--- @description 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
--- @description 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
return status.thirst
end
-- Framework.GetPlayerPhone(src)
-- Returns the phone number of the player.
---@param src number
---@return string | nil
--- @description This will get the phone number of a player
--- @param src number
--- @return string | nil return the phone number of the player
Framework.GetPlayerPhone = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
return xPlayer.get("phone_number")
end
---Depricated: Returns the job name, label, grade name, and grade level of the player.
---@deprecated This will return the job name, label, grade name, and grade level of the player.
---@param src number
---@return string | nil
---@return string | nil
@@ -292,9 +288,10 @@ Framework.GetPlayerJob = function(src)
return job.name, job.label, job.grade_label, job.grade
end
---This will return the players job name, job label, job grade label job grade level, boss status, and duty status in a table
---@param src number
---@return table | nil
--- @description This will return the players job name, job label, job grade label job grade level,
--- boss status, and duty status in a table
--- @param src number
--- @return table | nil
Framework.GetPlayerJobData = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return end
@@ -311,9 +308,9 @@ Framework.GetPlayerJobData = function(src)
}
end
---Returns the players duty status.
---@param src number
---@return boolean
--- @description This will return the players duty status, true if on duty false otherwise
--- @param src number
--- @return boolean return the players duty status
Framework.GetPlayerDuty = function(src)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return false end
@@ -322,10 +319,10 @@ Framework.GetPlayerDuty = function(src)
return true
end
---This will toggle a players duty status
---@param src number
---@param status boolean
---@return boolean
--- @description This will toggle a players duty status
--- @param src number
--- @param status boolean
--- @return boolean
Framework.SetPlayerDuty = function(src, status)
local xPlayer = Framework.GetPlayer(src)
if not xPlayer then return false end
@@ -335,18 +332,18 @@ Framework.SetPlayerDuty = function(src, status)
return true
end
---This will get a table of player sources that have the specified job name.
---@param job string
---@return table
--- @description This will get a table of player sources that have the specified job name
--- @param job string
--- @return table
Framework.GetPlayersByJob = function(job)
return Framework.GetPlayerSourcesByJob(job) or {}
end
-- Sets the player's job to the specified name and grade.
---@param src number
---@param name string
---@param grade string
---@return nil
--- @description This will set 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
@@ -358,11 +355,11 @@ Framework.SetPlayerJob = function(src, name, grade)
return true
end
---This will add money based on the type of account (money/bank)
---@param src number
---@param _type string
---@param amount number
---@return boolean | nil
--- @description 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
@@ -371,11 +368,11 @@ Framework.AddAccountBalance = function(src, _type, amount)
return true
end
---This will remove money based on the type of account (money/bank)
---@param src number
---@param _type string
---@param amount number
---@return boolean | nil
--- @description 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
@@ -384,10 +381,10 @@ Framework.RemoveAccountBalance = function(src, _type, amount)
return true
end
---This will remove money based on the type of account (money/bank)
---@param src number
---@param _type string
---@return string | nil
--- @description This will get the account balance 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
@@ -395,14 +392,13 @@ Framework.GetAccountBalance = function(src, _type)
return xPlayer.getAccount(_type).money
end
-- 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
--- @description 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
@@ -410,13 +406,12 @@ Framework.AddItem = function(src, item, amount, slot, metadata)
return true
end
-- 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
--- @description 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)
@@ -425,9 +420,9 @@ Framework.RemoveItem = function(src, item, amount, slot, metadata)
return true
end
---This will get all owned vehicles for the player
---@param src number
---@return table
--- @description 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 .. "'")
@@ -441,11 +436,9 @@ 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
--- @description 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