Merge branch 'dev' into ssn

[core]/es_extended/client/functions.lua

@@ -1,4 +1,5 @@
 ---@return boolean
+---@diagnostic disable-next-line: duplicate-set-field
 function ESX.IsPlayerLoaded()
     return ESX.PlayerLoaded
 end
@@ -559,7 +560,8 @@ function ESX.Game.SpawnVehicle(vehicleModel, coords, heading, cb, networked)
         local modelHash = ESX.Streaming.RequestModel(model)
         if not modelHash then
             if promise then
-                return promise:reject(("Tried to spawn invalid vehicle - ^5%s^7!"):format(model))
+                promise:reject(("Tried to spawn invalid vehicle - ^5%s^7!"):format(model))
+                return
             end
            error(("Tried to spawn invalid vehicle - ^5%s^7!"):format(model))
         end

[core]/es_extended/client/imports/point.lua

@@ -1,6 +1,6 @@
 local Point = ESX.Class()
 
-local nearby, loop = {}
+local nearby, loop = {}, nil
 
 function Point:constructor(properties)
 	self.coords = properties.coords
@@ -18,12 +18,12 @@ function Point:constructor(properties)
 			CreateThread(function()
 				while loop do
 					local coords = GetEntityCoords(ESX.PlayerData.ped)
-					for handle, point in pairs(nearby) do
+					for _, point in pairs(nearby) do
 						if point.inside then
 							point:inside(#(coords - point.coords))
 						end
 					end
-					Wait()
+					Wait(0)
 				end
 			end)
 		end

[core]/es_extended/client/modules/callback.lua

@@ -92,7 +92,7 @@ end
 
 ---@param eventName string
 ---@param ... any
----@return any
+---@return ...
 function ESX.AwaitServerCallback(eventName, ...)
     local invokingResource = GetInvokingResource()
     local invoker = (invokingResource and invokingResource ~= "unknown") and invokingResource or "es_extended"

[core]/es_extended/client/modules/scaleform.lua

@@ -73,7 +73,7 @@ function ESX.Scaleform.Utils.RunMethod(scaleform, methodName, returnValue, ...)
     BeginScaleformMovieMethod(scaleform, methodName)
 
     local args = { ... }
-    for i, arg in ipairs(args) do
+    for _, arg in ipairs(args) do
         local typeArg = type(arg)
 
         if typeArg == "number" then

[core]/es_extended/imports.lua

@@ -218,9 +218,10 @@ if GetResourceState("ox_lib") == "missing" then
         return nil, err or 'unknown error'
     end
 
+    ---@diagnostic disable-next-line: duplicate-doc-alias
     ---@alias PackageSearcher
     ---| fun(modName: string): function loader
-    ---| fun(modName: string): nil, string errmsg
+    ---| fun(modName: string): nil|false, string errmsg
 
     ---@type PackageSearcher[]
     package.searchers = {

[core]/es_extended/locales/es.lua

@@ -4,7 +4,7 @@ return {
     ["received_help"] = "Has cobrado tu subsidio: $%s",
     ["company_nomoney"] = "La empresa para la que trabajas es demasiado pobre para pagarte el sueldo",
     ["received_paycheck"] = "Nómina recibida",
-    ["bank"] = "Maze Bank", 
+    ["bank"] = "Maze Bank",
     ["account_bank"] = "Banco",
     ["account_black_money"] = "Dinero negro",
     ["account_money"] = "Efectivo",
@@ -86,7 +86,7 @@ return {
     ["disabled"] = "~r~desactivado~s~",
 
     -- Locale settings
-    ["locale_digit_grouping_symbol"] = ".", 
+    ["locale_digit_grouping_symbol"] = ".",
     ["locale_currency"] = "%s€",
 
     -- Weapons
@@ -128,7 +128,7 @@ return {
     ["weapon_snspistol"] = "Pistola SNS",
     ["weapon_snspistol_mk2"] = "Pistola SNS Mk2",
     ["weapon_stungun"] = "Pistola eléctrica",
-    ["weapon_raypistol"] = "Pistola de Rayos", 
+    ["weapon_raypistol"] = "Pistola de Rayos",
     ["weapon_vintagepistol"] = "Pistola vintage",
 
     -- Shotguns
@@ -156,7 +156,7 @@ return {
     ["weapon_smg"] = "Subfusil",
     ["weapon_smg_mk2"] = "Subfusil Mk2",
     ["weapon_raycarbine"] = "Carabina de Rayos",
-    ["weapon_tecpistol"] = "Subfusil táctico", 
+    ["weapon_tecpistol"] = "Subfusil táctico",
 
     -- Rifles
     ["weapon_advancedrifle"] = "Fusil avanzado",
@@ -196,9 +196,9 @@ return {
     ["weapon_tactilerifle"] = "Carabina de servicio",
 
     -- Drug wars dlc
-    ["weapon_candycane"] = "Bastón de caramelo", 
-    ["weapon_acidpackage"] = "Paquete de ácido", 
-    ["weapon_pistolxm3"] = "Pistola WM 29", 
+    ["weapon_candycane"] = "Bastón de caramelo",
+    ["weapon_acidpackage"] = "Paquete de ácido",
+    ["weapon_pistolxm3"] = "Pistola WM 29",
     ["weapon_railgunxm3"] = "Cañón de riel",
 
     -- Chop Shop DLC
@@ -220,7 +220,7 @@ return {
     ["weapon_pipebomb"] = "Bomba casera",
     ["weapon_snowball"] = "Bola de nieve",
     ["weapon_stickybomb"] = "Bomba lapa",
-    ["weapon_smokegrenade"] = "Granada de humo", 
+    ["weapon_smokegrenade"] = "Granada de humo",
 
     -- Special
     ["weapon_fireextinguisher"] = "Extintor",
@@ -309,7 +309,7 @@ return {
     ["component_ammo_tracer"] = "Munición trazadora",
     ["component_ammo_incendiary"] = "Munición incendiaria",
     ["component_ammo_hollowpoint"] = "Munición de punta hueca",
-    ["component_ammo_fmj"] = "Munición FMJ", 
+    ["component_ammo_fmj"] = "Munición FMJ",
     ["component_ammo_armor"] = "Munición perforante",
     ["component_ammo_explosive"] = "Munición explosiva perforante",
 

[core]/es_extended/server/classes/player.lua

@@ -1,37 +1,151 @@
+---@class ESXAccount
+---@field name string               # Account name (e.g., "bank", "money").
+---@field money number              # Current balance in this account.
+---@field label string              # Human-readable label for the account.
+---@field round boolean             # Whether amounts are rounded for display.
+---@field index number              # Index of the account in the player's accounts list.
+
+---@class ESXItem
+---@field name string               # Item identifier (internal name).
+---@field label string              # Display name of the item.
+---@field weight number             # Weight of a single unit of the item.
+---@field usable boolean            # Whether the item can be used.
+---@field rare boolean              # Whether the item is rare.
+---@field canRemove boolean         # Whether the item can be removed from inventory.
+
+---@class ESXInventoryItem:ESXItem
+---@field count number              # Number of this item in the player's inventory.
+
+---@class ESXJob
+---@field id number                 # Job ID.
+---@field name string               # Job internal name.
+---@field label string              # Job display label.
+---@field grade number              # Current grade/rank number.
+---@field grade_name string         # Name of the current grade.
+---@field grade_label string        # Label of the current grade.
+---@field grade_salary number       # Salary for the current grade.
+---@field skin_male table           # Skin configuration for male characters.
+---@field skin_female table         # Skin configuration for female characters.
+---@field onDuty boolean?           # Whether the player is currently on duty.
+
+---@class ESXWeapon
+---@field name string               # Weapon identifier (internal name).
+---@field label string              # Weapon display name.
+
+---@class ESXInventoryWeapon:ESXWeapon
+---@field ammo number               # Amount of ammo in the weapon.
+---@field components string[]       # List of components attached to the weapon.
+---@field tintIndex number          # Current weapon tint index.
+
+---@class ESXWeaponComponent
+---@field name string               # Component identifier (internal name).
+---@field label string              # Component display name.
+---@field hash string|number        # Component hash or identifier.
+
 ---@class xPlayer
----@field accounts table
----@field coords table
----@field group string
----@field identifier string
----@field inventory table
----@field job table
----@field loadout table
----@field name string
----@field playerId number
----@field source number
----@field variables table
----@field weight number
----@field maxWeight number
----@field metadata table
----@field lastPlaytime number
----@field admin boolean
----@field license string
+--- Properties
+---@field accounts ESXAccount[]     # Array of the player's accounts.
+---@field coords table              # Player's coordinates {x, y, z, heading}.
+---@field group string              # Player permission group.
+---@field identifier string         # Unique identifier (usually Steam or license).
+---@field license string            # Player license string.
+---@field inventory ESXInventoryItem[] # Player's inventory items.
+---@field job ESXJob                # Player's current job.
+---@field loadout ESXInventoryWeapon[] # Player's current weapons.
+---@field name string               # Player's display name.
+---@field playerId number           # Player's ID (server ID).
+---@field source number             # Player's source (alias for playerId).
+---@field variables table           # Custom player variables.
+---@field weight number             # Current carried weight.
+---@field maxWeight number          # Maximum carry weight.
+---@field metadata table            # Custom metadata table.
+---@field lastPlaytime number       # Last recorded playtime in seconds.
+---@field paycheckEnabled boolean   # Whether paycheck is enabled.
+---@field admin boolean             # Whether the player is an admin.
+--- Money Functions
+---@field setMoney fun(money: number)                             # Set player's cash balance.
+---@field getMoney fun(): number                                   # Get player's current cash balance.
+---@field addMoney fun(money: number, reason: string)             # Add money to the player's cash balance.
+---@field removeMoney fun(money: number, reason: string)          # Remove money from the player's cash balance.
+---@field setAccountMoney fun(accountName: string, money: number, reason?: string)  # Set specific account balance.
+---@field addAccountMoney fun(accountName: string, money: number, reason?: string)  # Add money to an account.
+---@field removeAccountMoney fun(accountName: string, money: number, reason?: string) # Remove money from an account.
+---@field getAccount fun(account: string): ESXAccount?            # Get account data by name.
+---@field getAccounts fun(minimal?: boolean): ESXAccount[]|table<string,number>  # Get all accounts, optionally minimal.
+--- Inventory Functions
+---@field getInventory fun(minimal?: boolean): ESXInventoryItem[]|table<string,number>  # Get inventory, optionally minimal.
+---@field getInventoryItem fun(itemName: string): ESXInventoryItem? # Get a specific item from inventory.
+---@field addInventoryItem fun(itemName: string, count: number)     # Add items to inventory.
+---@field removeInventoryItem fun(itemName: string, count: number)  # Remove items from inventory.
+---@field setInventoryItem fun(itemName: string, count: number)     # Set item count in inventory.
+---@field getWeight fun(): number                                   # Get current carried weight.
+---@field getMaxWeight fun(): number                                # Get maximum carry weight.
+---@field setMaxWeight fun(newWeight: number)                       # Set maximum carry weight.
+---@field canCarryItem fun(itemName: string, count: number): boolean # Check if player can carry more of an item.
+---@field canSwapItem fun(firstItem: string, firstItemCount: number, testItem: string, testItemCount: number): boolean # Check if items can be swapped.
+---@field hasItem fun(item: string): ESXInventoryItem|false, number? # Check if player has an item.
+---@field getLoadout fun(minimal?: boolean): ESXInventoryWeapon[]|table<string, {ammo:number, tintIndex?:number, components?:string[]}> # Get player's weapon loadout.
+--- Job Functions
+---@field getJob fun(): ESXJob                                         # Get player's current job.
+---@field setJob fun(newJob: string, grade: string, onDuty?: boolean)  # Set player's job and grade.
+---@field setGroup fun(newGroup: string)                               # Set player's permission group.
+---@field getGroup fun(): string                                       # Get player's permission group.
+--- Weapon Functions
+---@field addWeapon fun(weaponName: string, ammo: number)                 # Give player a weapon.
+---@field removeWeapon fun(weaponName: string)                             # Remove weapon from player.
+---@field hasWeapon fun(weaponName: string): boolean                       # Check if player has a weapon.
+---@field getWeapon fun(weaponName: string): number?, table?               # Get weapon ammo & components.
+---@field addWeaponAmmo fun(weaponName: string, ammoCount: number)        # Add ammo to a weapon.
+---@field removeWeaponAmmo fun(weaponName: string, ammoCount: number)     # Remove ammo from a weapon.
+---@field updateWeaponAmmo fun(weaponName: string, ammoCount: number)     # Update ammo count for a weapon.
+---@field addWeaponComponent fun(weaponName: string, weaponComponent: string)    # Add component to weapon.
+---@field removeWeaponComponent fun(weaponName: string, weaponComponent: string) # Remove component from weapon.
+---@field hasWeaponComponent fun(weaponName: string, weaponComponent: string): boolean # Check if weapon has component.
+---@field setWeaponTint fun(weaponName: string, weaponTintIndex: number) # Set weapon tint.
+---@field getWeaponTint fun(weaponName: string): number                  # Get weapon tint.
+--- Player State Functions
+---@field getIdentifier fun(): string                              # Get player's unique identifier.
+---@field getSource fun(): number                                  # Get player source/server ID.
+---@field getPlayerId fun(): number                                # Alias for getSource.
+---@field getName fun(): string                                     # Get player's name.
+---@field setName fun(newName: string)                              # Set player's name.
+---@field setCoords fun(coordinates: vector4|vector3|table)        # Teleport player to coordinates.
+---@field getCoords fun(vector?: boolean, heading?: boolean): vector3|vector4|table # Get player's coordinates.
+---@field isAdmin fun(): boolean                                    # Check if player is admin.
+---@field kick fun(reason: string)                                  # Kick player from server.
+---@field getPlayTime fun(): number                                  # Get total playtime in seconds.
+---@field set fun(k: string, v: any)                                # Set custom variable.
+---@field get fun(k: string): any                                    # Get custom variable.
+--- Metadata Functions
+---@field getMeta fun(index?: string, subIndex?: string|table): any   # Get metadata value(s).
+---@field setMeta fun(index: string, value: any, subValue?: any)      # Set metadata value(s).
+---@field clearMeta fun(index: string, subValues?: string|table)      # Clear metadata value(s).
+--- Notification Functions
+---@field showNotification fun(msg: string, notifyType?: string, length?: number) # Show a simple notification.
+---@field showAdvancedNotification fun(sender: string, subject: string, msg: string, textureDict: string, iconType: string, flash: boolean, saveToBrief: boolean, hudColorIndex: number) # Show advanced notification.
+---@field showHelpNotification fun(msg: string, thisFrame?: boolean, beep?: boolean, duration?: number) # Show help notification.
+--- Misc Functions
+---@field togglePaycheck fun(toggle: boolean)     # Enable/disable paycheck.
+---@field isPaycheckEnabled fun(): boolean       # Check if paycheck is enabled.
+---@field executeCommand fun(command: string)    # Execute a server command.
+---@field triggerEvent fun(eventName: string, ...) # Trigger client event for this player.
 
 ---@param playerId number
 ---@param identifier string
 ---@param ssn string
 ---@param group string
----@param accounts table
+---@param accounts ESXAccount[]
 ---@param inventory table
 ---@param weight number
----@param job table
----@param loadout table
+---@param job ESXJob
+---@param loadout ESXInventoryWeapon[]
 ---@param name string
----@param coords table | vector4
+---@param coords vector4|{x: number, y: number, z: number, heading: number}
 ---@param metadata table
+---@return xPlayer
 function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, inventory, weight, job, loadout, name, coords, metadata)
-    ---@class xPlayer
-    local self = {}
+    ---@diagnostic disable-next-line: missing-fields
+    local self = {} ---@type xPlayer
 
     self.accounts = accounts
     self.coords = coords
@@ -74,32 +188,23 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
     stateBag:set("group", self.group, true)
     stateBag:set("name", self.name, true)
 
-    ---@param eventName string
-    ---@param ... any
-    ---@return nil
     function self.triggerEvent(eventName, ...)
         assert(type(eventName) == "string", "eventName should be string!")
         TriggerClientEvent(eventName, self.source, ...)
     end
 
-    ---@param toggle boolean
-    ---@return nil
     function self.togglePaycheck(toggle)
         self.paycheckEnabled = toggle
     end
 
-    ---@return boolean
     function self.isPaycheckEnabled()
         return self.paycheckEnabled
     end
 
-    ---@return boolean
     function self.isAdmin()
         return Core.IsPlayerAdmin(self.source)
     end
 
-    ---@param coordinates vector4 | vector3 | table
-    ---@return nil
     function self.setCoords(coordinates)
         local ped <const> = GetPlayerPed(self.source)
 
@@ -107,9 +212,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         SetEntityHeading(ped, coordinates.w or coordinates.heading or 0.0)
     end
 
-    ---@param vector boolean
-    ---@param heading boolean
-    ---@return vector3 | vector4 | table
     function self.getCoords(vector, heading)
         local ped <const> = GetPlayerPed(self.source)
         local entityCoords <const> = GetEntityCoords(ped)
@@ -128,49 +230,35 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return coordinates
     end
 
-    ---@param reason string
-    ---@return nil
     function self.kick(reason)
-        local source <const> = tostring(self.source)
-        DropPlayer(source, reason)
+        DropPlayer(self.source --[[@as string]], reason)
     end
 
-      ---@return number
     function self.getPlayTime()
         -- luacheck: ignore
-        return self.lastPlaytime + GetPlayerTimeOnline(self.source)
+        return self.lastPlaytime + GetPlayerTimeOnline(self.source --[[@as string]])
     end
 
-    ---@param money number
-    ---@return nil
     function self.setMoney(money)
         assert(type(money) == "number", "money should be number!")
         money = ESX.Math.Round(money)
         self.setAccountMoney("money", money)
     end
 
-    ---@return number
     function self.getMoney()
         return self.getAccount("money").money
     end
 
-    ---@param money number
-    ---@param reason string
-    ---@return nil
     function self.addMoney(money, reason)
         money = ESX.Math.Round(money)
         self.addAccountMoney("money", money, reason)
     end
 
-    ---@param money number
-    ---@param reason string
-    ---@return nil
     function self.removeMoney(money, reason)
         money = ESX.Math.Round(money)
         self.removeAccountMoney("money", money, reason)
     end
 
-    ---@return string
     function self.getIdentifier()
         return self.identifier
     end
@@ -179,9 +267,7 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
     function self.getSSN()
         return self.ssn
     end
-
-    ---@param newGroup string
-    ---@return nil
+  
     function self.setGroup(newGroup)
         local lastGroup = self.group
 
@@ -196,28 +282,20 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         ExecuteCommand(("add_principal identifier.%s group.%s"):format(self.license, self.group))
     end
 
-    ---@return string
     function self.getGroup()
         return self.group
     end
 
-    ---@param k string
-    ---@param v any
-    ---@return nil
     function self.set(k, v)
         self.variables[k] = v
-        
+
         self.triggerEvent('esx:updatePlayerData', 'variables', self.variables)
     end
 
-    ---@param k string
-    ---@return any
     function self.get(k)
         return self.variables[k]
     end
 
-    ---@param minimal boolean
-    ---@return table
     function self.getAccounts(minimal)
         if not minimal then
             return self.accounts
@@ -232,8 +310,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return minimalAccounts
     end
 
-    ---@param account string
-    ---@return table | nil
     function self.getAccount(account)
         account = string.lower(account)
         for i = 1, #self.accounts do
@@ -245,8 +321,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return nil
     end
 
-    ---@param minimal boolean
-    ---@return table
     function self.getInventory(minimal)
         if minimal then
             local minimalInventory = {}
@@ -263,13 +337,10 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return self.inventory
     end
 
-    ---@return table
     function self.getJob()
         return self.job
     end
 
-    ---@param minimal boolean
-    ---@return table
     function self.getLoadout(minimal)
         if not minimal then
             return self.loadout
@@ -300,22 +371,15 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return minimalLoadout
     end
 
-    ---@return string
     function self.getName()
         return self.name
     end
 
-    ---@param newName string
-    ---@return nil
     function self.setName(newName)
         self.name = newName
         Player(self.source).state:set("name", self.name, true)
     end
 
-    ---@param accountName string
-    ---@param money number
-    ---@param reason string | nil
-    ---@return nil
     function self.setAccountMoney(accountName, money, reason)
         reason = reason or "unknown"
         if not tonumber(money) then
@@ -339,10 +403,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param accountName string
-    ---@param money number
-    ---@param reason string | nil
-    ---@return nil
     function self.addAccountMoney(accountName, money, reason)
         reason = reason or "Unknown"
         if not tonumber(money) then
@@ -365,10 +425,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param accountName string
-    ---@param money number
-    ---@param reason string | nil
-    ---@return nil
     function self.removeAccountMoney(accountName, money, reason)
         reason = reason or "Unknown"
         if not tonumber(money) then
@@ -396,8 +452,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param itemName string
-    ---@return table | nil
     function self.getInventoryItem(itemName)
         for _, v in ipairs(self.inventory) do
             if v.name == itemName then
@@ -407,9 +461,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return nil
     end
 
-    ---@param itemName string
-    ---@param count number
-    ---@return nil
     function self.addInventoryItem(itemName, count)
         local item = self.getInventoryItem(itemName)
 
@@ -423,9 +474,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param itemName string
-    ---@param count number
-    ---@return nil
     function self.removeInventoryItem(itemName, count)
         local item = self.getInventoryItem(itemName)
 
@@ -447,9 +495,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param itemName string
-    ---@param count number
-    ---@return nil
     function self.setInventoryItem(itemName, count)
         local item = self.getInventoryItem(itemName)
 
@@ -464,25 +509,19 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@return number
     function self.getWeight()
         return self.weight
     end
 
-    ---@return number
     function self.getSource()
         return self.source
     end
     self.getPlayerId = self.getSource
 
-    ---@return number
     function self.getMaxWeight()
         return self.maxWeight
     end
 
-    ---@param itemName string
-    ---@param count number
-    ---@return boolean
     function self.canCarryItem(itemName, count)
         if ESX.Items[itemName] then
             local currentWeight, itemWeight = self.weight, ESX.Items[itemName].weight
@@ -495,11 +534,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param firstItem string
-    ---@param firstItemCount number
-    ---@param testItem string
-    ---@param testItemCount number
-    ---@return boolean
     function self.canSwapItem(firstItem, firstItemCount, testItem, testItemCount)
         local firstItemObject = self.getInventoryItem(firstItem)
         if not firstItemObject then
@@ -520,17 +554,11 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return false
     end
 
-    ---@param newWeight number
-    ---@return nil
     function self.setMaxWeight(newWeight)
         self.maxWeight = newWeight
         self.triggerEvent("esx:setMaxWeight", self.maxWeight)
     end
 
-    ---@param newJob string
-    ---@param grade string
-    ---@param onDuty? boolean
-    ---@return nil
     function self.setJob(newJob, grade, onDuty)
         grade = tostring(grade)
         local lastJob = self.job
@@ -555,7 +583,7 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
             label = jobObject.label,
             onDuty = onDuty,
 
-            grade = tonumber(grade),
+            grade = tonumber(grade) or 0,
             grade_name = gradeObject.name,
             grade_label = gradeObject.label,
             grade_salary = gradeObject.salary,
@@ -570,9 +598,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         Player(self.source).state:set("job", self.job, true)
     end
 
-    ---@param weaponName string
-    ---@param ammo number
-    ---@return nil
     function self.addWeapon(weaponName, ammo)
         if not self.hasWeapon(weaponName) then
             local weaponLabel <const> = ESX.GetWeaponLabel(weaponName)
@@ -591,9 +616,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@param weaponComponent string
-    ---@return nil
     function self.addWeaponComponent(weaponName, weaponComponent)
         local loadoutNum <const>, weapon <const> = self.getWeapon(weaponName)
 
@@ -611,9 +633,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@param ammoCount number
-    ---@return nil
     function self.addWeaponAmmo(weaponName, ammoCount)
         local _, weapon = self.getWeapon(weaponName)
 
@@ -623,9 +642,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@param ammoCount number
-    ---@return nil
     function self.updateWeaponAmmo(weaponName, ammoCount)
         local _, weapon = self.getWeapon(weaponName)
 
@@ -643,9 +659,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@param weaponTintIndex number
-    ---@return nil
     function self.setWeaponTint(weaponName, weaponTintIndex)
         local loadoutNum <const>, weapon <const> = self.getWeapon(weaponName)
 
@@ -660,8 +673,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@return number
     function self.getWeaponTint(weaponName)
         local _, weapon <const> = self.getWeapon(weaponName)
 
@@ -672,8 +683,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return 0
     end
 
-    ---@param weaponName string
-    ---@return nil
     function self.removeWeapon(weaponName)
         local weaponLabel, playerPed <const> = nil, GetPlayerPed(self.source)
 
@@ -704,9 +713,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@param weaponComponent string
-    ---@return nil
     function self.removeWeaponComponent(weaponName, weaponComponent)
         local loadoutNum <const>, weapon <const> = self.getWeapon(weaponName)
 
@@ -729,9 +735,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@param ammoCount number
-    ---@return nil
     function self.removeWeaponAmmo(weaponName, ammoCount)
         local _, weapon = self.getWeapon(weaponName)
 
@@ -741,9 +744,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         end
     end
 
-    ---@param weaponName string
-    ---@param weaponComponent string
-    ---@return boolean
     function self.hasWeaponComponent(weaponName, weaponComponent)
         local _, weapon <const> = self.getWeapon(weaponName)
 
@@ -760,8 +760,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return false
     end
 
-    ---@param weaponName string
-    ---@return boolean
     function self.hasWeapon(weaponName)
         for _, v in ipairs(self.loadout) do
             if v.name == weaponName then
@@ -772,8 +770,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return false
     end
 
-    ---@param item string
-    ---@return table | false, number | nil
     function self.hasItem(item)
         for _, v in ipairs(self.inventory) do
             if v.name == item and v.count >= 1 then
@@ -784,8 +780,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return false
     end
 
-    ---@param weaponName string
-    ---@return number | nil, table | nil
     function self.getWeapon(weaponName)
         for k, v in ipairs(self.loadout) do
             if v.name == weaponName then
@@ -796,39 +790,19 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return nil, nil
     end
 
-    ---@param msg string
-    ---@param notifyType string
-    ---@param length number
-    ---@return nil
     function self.showNotification(msg, notifyType, length)
         self.triggerEvent("esx:showNotification", msg, notifyType, length)
     end
 
-    ---@param sender string
-    ---@param subject string
-    ---@param msg string
-    ---@param textureDict string
-    ---@param iconType string
-    ---@param flash boolean
-    ---@param saveToBrief boolean
-    ---@param hudColorIndex number
-    ---@return nil
+
     function self.showAdvancedNotification(sender, subject, msg, textureDict, iconType, flash, saveToBrief, hudColorIndex)
         self.triggerEvent("esx:showAdvancedNotification", sender, subject, msg, textureDict, iconType, flash, saveToBrief, hudColorIndex)
     end
 
-    ---@param msg string
-    ---@param thisFrame boolean
-    ---@param beep boolean
-    ---@param duration number
-    ---@return nil
     function self.showHelpNotification(msg, thisFrame, beep, duration)
         self.triggerEvent("esx:showHelpNotification", msg, thisFrame, beep, duration)
     end
 
-    ---@param index any
-    ---@param subIndex any
-    ---@return table | nil
     function self.getMeta(index, subIndex)
         if not index then
             return self.metadata
@@ -874,10 +848,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         return metaData
     end
 
-    ---@param index any
-    ---@param value any
-    ---@param subValue any
-    ---@return nil
     function self.setMeta(index, value, subValue)
         if not index then
             return error("xPlayer.setMeta ^5index^1 is Missing!")
@@ -925,7 +895,11 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
 
         local metaData = self.metadata[index]
         if metaData == nil then
-            return Config.EnableDebug and error(("xPlayer.clearMeta ^5%s^1 does not exist!"):format(index)) or nil
+            if Config.EnableDebug then
+                error(("xPlayer.clearMeta ^5%s^1 does not exist!"):format(index))
+            end
+
+            return
         end
 
         if not subValues then
@@ -958,8 +932,6 @@ function CreateExtendedPlayer(playerId, identifier, ssn, group, accounts, invent
         self.triggerEvent('esx:updatePlayerData', 'metadata', self.metadata)
     end
 
-    ---@param command string
-    ---@return nil
     function self.executeCommand(command)
         if type(command) ~= "string" then
             error("xPlayer.executeCommand must be of type string!")

[core]/es_extended/server/functions.lua

@@ -292,7 +292,7 @@ end
 
 ---@param key? string
 ---@param val? string|table
----@return table
+---@return xPlayer[]|table<any, xPlayer[]>
 function ESX.GetExtendedPlayers(key, val)
     if not key then
         return ESX.Table.ToArray(ESX.Players)
@@ -348,13 +348,13 @@ function ESX.GetNumPlayers(key, val)
 end
 
 ---@param source number
----@return table
+---@return xPlayer?
 function ESX.GetPlayerFromId(source)
     return ESX.Players[tonumber(source)]
 end
 
 ---@param identifier string
----@return table
+---@return xPlayer?
 function ESX.GetPlayerFromIdentifier(identifier)
     return Core.playersByIdentifier[identifier]
 end
@@ -367,16 +367,17 @@ end
 
 ---@param source number
 ---@return boolean
+---@diagnostic disable-next-line: duplicate-set-field
 function ESX.IsPlayerLoaded(source)
     return ESX.Players[source] ~= nil
 end
 
 ---@param playerId number | string
----@return string
+---@return string, number
 function ESX.GetIdentifier(playerId)
     local fxDk = GetConvarInt("sv_fxdkMode", 0)
     if fxDk == 1 then
-        return "ESX-DEBUG-LICENCE"
+        return "ESX-DEBUG-LICENCE", 0
     end
 
     playerId = tostring(playerId)
@@ -662,7 +663,7 @@ if not Config.CustomInventory then
             local xPlayer = xPlayers[i]
             local minimalInv = xPlayer.getInventory(true)
 
-            for itemName, itemCount in pairs(minimalInv) do
+            for itemName, _ in pairs(minimalInv) do
                 if not ESX.Items[itemName] then
                     xPlayer.setInventoryItem(itemName, 0)
                     minimalInv[itemName] = nil

[core]/es_extended/server/main.lua

@@ -421,6 +421,10 @@ if not Config.CustomInventory then
         if itemType == "item_standard" then
             local sourceItem = sourceXPlayer.getInventoryItem(itemName)
 
+            if not sourceItem then
+                return
+            end
+
             if itemCount < 1 or sourceItem.count < itemCount then
                 return sourceXPlayer.showNotification(TranslateCap("imp_invalid_quantity"))
             end
@@ -457,6 +461,10 @@ if not Config.CustomInventory then
             end
 
             local _, weapon = sourceXPlayer.getWeapon(itemName)
+            if not weapon then
+                return
+            end
+
             local _, weaponObject = ESX.GetWeapon(itemName)
             itemCount = weapon.ammo
             local weaponComponents = ESX.Table.Clone(weapon.components)
@@ -489,6 +497,9 @@ if not Config.CustomInventory then
             end
 
             local _, weapon = sourceXPlayer.getWeapon(itemName)
+            if not weapon then
+                return
+            end
 
             if not targetXPlayer.hasWeapon(itemName) then
                 sourceXPlayer.showNotification(TranslateCap("gave_weapon_noweapon", targetXPlayer.name))
@@ -515,12 +526,19 @@ if not Config.CustomInventory then
         local playerId = source
         local xPlayer = ESX.GetPlayerFromId(playerId)
 
+        if not xPlayer then
+            return
+        end
+
         if itemType == "item_standard" then
             if not itemCount or itemCount < 1 then
                 return xPlayer.showNotification(TranslateCap("imp_invalid_quantity"))
             end
 
             local xItem = xPlayer.getInventoryItem(itemName)
+            if not xItem then
+                return
+            end
 
             if itemCount > xItem.count or xItem.count < 1 then
                 return xPlayer.showNotification(TranslateCap("imp_invalid_quantity"))
@@ -536,6 +554,9 @@ if not Config.CustomInventory then
             end
 
             local account = xPlayer.getAccount(itemName)
+            if not account then
+                return
+            end
 
             if itemCount > account.money or account.money < 1 then
                 return xPlayer.showNotification(TranslateCap("imp_invalid_amount"))
@@ -551,6 +572,10 @@ if not Config.CustomInventory then
             if not xPlayer.hasWeapon(itemName) then return end
 
             local _, weapon = xPlayer.getWeapon(itemName)
+            if not weapon then
+                return
+            end
+
             local _, weaponObject = ESX.GetWeapon(itemName)
             -- luacheck: ignore weaponPickupLabel
             local weaponPickupLabel = ""
@@ -573,6 +598,11 @@ if not Config.CustomInventory then
     RegisterNetEvent("esx:useItem", function(itemName)
         local source = source
         local xPlayer = ESX.GetPlayerFromId(source)
+
+        if not xPlayer then
+            return
+        end
+
         local count = xPlayer.getInventoryItem(itemName).count
 
         if count < 1 then
@@ -585,6 +615,10 @@ if not Config.CustomInventory then
     RegisterNetEvent("esx:onPickup", function(pickupId)
         local pickup, xPlayer, success = Core.Pickups[pickupId], ESX.GetPlayerFromId(source)
 
+        if not xPlayer then
+            return
+        end
+
         if not pickup then return end
 
         local playerPickupDistance = #(pickup.coords - xPlayer.getCoords(true))
@@ -627,6 +661,10 @@ end
 ESX.RegisterServerCallback("esx:getPlayerData", function(source, cb)
     local xPlayer = ESX.GetPlayerFromId(source)
 
+    if not xPlayer then
+        return
+    end
+
     cb({
         identifier = xPlayer.identifier,
         accounts = xPlayer.getAccounts(),
@@ -650,6 +688,10 @@ end)
 ESX.RegisterServerCallback("esx:getOtherPlayerData", function(_, cb, target)
     local xPlayer = ESX.GetPlayerFromId(target)
 
+    if not xPlayer then
+        return
+    end
+
     cb({
         identifier = xPlayer.identifier,
         accounts = xPlayer.getAccounts(),

[core]/es_extended/server/modules/callback.lua

@@ -98,7 +98,7 @@ end
 ---@param player number playerId
 ---@param eventName string
 ---@param ... any
----@return any
+---@return ...
 function ESX.AwaitClientCallback(player, eventName, ...)
     local invokingResource = GetInvokingResource()
     local invoker = (invokingResource and invokingResource ~= "Unknown") and invokingResource or "es_extended"

[core]/es_extended/shared/functions.lua

@@ -76,7 +76,7 @@ end
 
 ---@param weaponName string
 ---@param weaponComponent string
----@return table | nil
+---@return ESXWeaponComponent?
 function ESX.GetWeaponComponent(weaponName, weaponComponent)
     weaponName = string.upper(weaponName)
 
@@ -84,6 +84,7 @@ function ESX.GetWeaponComponent(weaponName, weaponComponent)
     local weapon = Config.Weapons[weaponsByName[weaponName]]
 
     for _, component in ipairs(weapon.components) do
+        ---@cast component ESXWeaponComponent
         if component.name == weaponComponent then
             return component
         end

[core]/esx_identity/server/main.lua

@@ -245,7 +245,7 @@ end
     end
 
     ESX.RegisterServerCallback("esx_identity:registerIdentity", function(source, cb, data)
-        local xPlayer = ESX.GetPlayerFromId(source)
+        local xPlayer = ESX.Player(source)
 
         if not checkNameFormat(data.firstname) then
             TriggerClientEvent("esx:showNotification", source, TranslateCap("invalid_firstname_format"), "error")
@@ -269,12 +269,13 @@ end
         end
 
         if xPlayer then
-            if alreadyRegistered[xPlayer.identifier] then
+            local identifier = xPlayer.getIdentifier()
+            if alreadyRegistered[identifier] then
                 xPlayer.showNotification(TranslateCap("already_registered"), "error")
                 return cb(false)
             end
 
-            playerIdentity[xPlayer.identifier] = {
+            playerIdentity[identifier] = {
                 firstName = formatName(data.firstname),
                 lastName = formatName(data.lastname),
                 dateOfBirth = formatDate(data.dateofbirth),
@@ -282,14 +283,14 @@ end
                 height = data.height,
             }
 
-            local currentIdentity = playerIdentity[xPlayer.identifier]
+            local currentIdentity = playerIdentity[identifier]
 
             SetPlayerData(xPlayer, currentIdentity)
 
-            TriggerClientEvent("esx_identity:setPlayerData", xPlayer.source, currentIdentity)
-            saveIdentityToDatabase(xPlayer.identifier, currentIdentity)
-            alreadyRegistered[xPlayer.identifier] = true
-            playerIdentity[xPlayer.identifier] = nil
+            TriggerClientEvent("esx_identity:setPlayerData", xPlayer.src, currentIdentity)
+            saveIdentityToDatabase(identifier, currentIdentity)
+            alreadyRegistered[identifier] = true
+            playerIdentity[identifier] = nil
             return cb(true)
         end
 
@@ -329,18 +330,19 @@ if Config.EnableCommands then
 
     ESX.RegisterCommand("chardel", "user", function(xPlayer)
         if xPlayer and xPlayer.getName() then
+            local identifier = xPlayer.getIdentifier()
             if Config.UseDeferrals then
                 xPlayer.kick(TranslateCap("deleted_identity"))
                 Wait(1500)
                 deleteIdentity(xPlayer)
                 xPlayer.showNotification(TranslateCap("deleted_character"))
-                playerIdentity[xPlayer.identifier] = nil
-                alreadyRegistered[xPlayer.identifier] = false
+                playerIdentity[identifier] = nil
+                alreadyRegistered[identifier] = false
             else
                 deleteIdentity(xPlayer)
                 xPlayer.showNotification(TranslateCap("deleted_character"))
-                playerIdentity[xPlayer.identifier] = nil
-                alreadyRegistered[xPlayer.identifier] = false
+                playerIdentity[identifier] = nil
+                alreadyRegistered[identifier] = false
                 TriggerClientEvent("esx_identity:showRegisterIdentity", xPlayer.source)
             end
         else

[core]/esx_notify/Config.lua

@@ -1,3 +1,3 @@
 Config = {}
 
-Config.notificationSoundEnabled = true 
+Config.notificationSoundEnabled = true

[core]/esx_skin/server/main.lua

@@ -2,7 +2,7 @@ RegisterNetEvent("esx_skin:save", function(skin)
     if not skin or type(skin) ~= "table" then
         return
     end
-    local xPlayer = ESX.GetPlayerFromId(source)
+    local xPlayer = ESX.Player(source)
 
     if not ESX.GetConfig().CustomInventory then
         local defaultMaxWeight = ESX.GetConfig().MaxWeight
@@ -17,12 +17,12 @@ RegisterNetEvent("esx_skin:save", function(skin)
 
     MySQL.update("UPDATE users SET skin = @skin WHERE identifier = @identifier", {
         ["@skin"] = json.encode(skin),
-        ["@identifier"] = xPlayer.identifier,
+        ["@identifier"] = xPlayer.getIdentifier(),
     })
 end)
 
 RegisterNetEvent("esx_skin:setWeight", function(skin)
-    local xPlayer = ESX.GetPlayerFromId(source)
+    local xPlayer = ESX.Player(source)
 
     if not ESX.GetConfig().CustomInventory then
         local defaultMaxWeight = ESX.GetConfig().MaxWeight
@@ -37,16 +37,16 @@ RegisterNetEvent("esx_skin:setWeight", function(skin)
 end)
 
 ESX.RegisterServerCallback("esx_skin:getPlayerSkin", function(source, cb)
-    local xPlayer = ESX.GetPlayerFromId(source)
+    local xPlayer = ESX.Player(source)
 
     MySQL.query("SELECT skin FROM users WHERE identifier = @identifier", {
-        ["@identifier"] = xPlayer.identifier,
+        ["@identifier"] = xPlayer.getIdentifier(),
     }, function(users)
         local user, skin = users[1], nil
 
         local jobSkin = {
-            skin_male = xPlayer.job.skin_male,
-            skin_female = xPlayer.job.skin_female,
+            skin_male = xPlayer.getJob().skin_male,
+            skin_female = xPlayer.getJob().skin_female,
         }
 
         if user.skin then