diff --git a/modules/framework/es_extended/client.lua b/modules/framework/es_extended/client.lua index 38a2125..21b22a5 100644 --- a/modules/framework/es_extended/client.lua +++ b/modules/framework/es_extended/client.lua @@ -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 diff --git a/modules/framework/es_extended/server.lua b/modules/framework/es_extended/server.lua index d0adad1..6daf30f 100644 --- a/modules/framework/es_extended/server.lua +++ b/modules/framework/es_extended/server.lua @@ -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