Merge branch 'dev' into ssn

2026-08-29 01:08:54 +00:00 · 2025-08-19 21:55:18 +02:00
parent 9333c1e9e0 0805ac0f5b
commit ffd59464b8
3 changed files with 88 additions and 44 deletions
@@ -106,26 +106,56 @@ if not IsDuplicityVersion() then -- Only register this event for the client
        end
    end
 else
-    ESX.Player = setmetatable({}, {
-        __call = function(_, src)
-            if type(src) ~= "number" then
-                src = ESX.GetPlayerIdFromIdentifier(src)
-                if not src then
-                    return
+    ---@param src number
+    ---@return StaticPlayer
+    local function createStaticPlayer(src)
+        return setmetatable({ src = src }, {
+            __index = function(self, method)
+                return function(...)
+                    return exports.es_extended:RunStaticPlayerMethod(self.src, method, ...)
                end
-            elseif not ESX.IsPlayerLoaded(src) then
-                return
            end
+        })
+    end

-            return setmetatable({ src = src }, {
-                __index = function(self, method)
-                    return function(...)
-                        return exports.es_extended:RunStaticPlayerMethod(self.src, method, ...)
-                    end
-                end
-            })
+    ---@param src number|string
+    ---@return StaticPlayer?
+    function ESX.Player(src)
+        if type(src) ~= "number" then
+            src = ESX.GetPlayerIdFromIdentifier(src)
+            if not src then return end
+        elseif not ESX.IsPlayerLoaded(src) then
+            return
        end
-    })
+
+        return createStaticPlayer(src)
+    end
+
+    ---@param key? string
+    ---@param val? string|string[]
+    ---@return StaticPlayer[] | table<any, StaticPlayer[]>
+    function ESX.ExtendedPlayers(key, val)
+        local playerIds = ESX.GetExtendedPlayers(key, val, true)
+
+        if key and type(val) == "table" then
+            ---@cast playerIds table<any, number[]>
+            local retVal = {}
+            for group, ids in pairs(playerIds) do
+                retVal[group] = {}
+                for i = 1, #ids do
+                    retVal[group][i] = createStaticPlayer(ids[i])
+                end
+            end
+            return retVal
+        else
+            ---@cast playerIds number[]
+            local retVal = {}
+            for i = 1, #playerIds do
+                retVal[i] = createStaticPlayer(playerIds[i])
+            end
+            return retVal
+        end
+    end
 end

 if GetResourceState("ox_lib") == "missing" then
@@ -42,27 +42,7 @@
 ---@field label string              # Component display name.
 ---@field hash string|number        # Component hash or identifier.

---@class xPlayer
--- 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 ssn string                # Player's social security number.
---@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.
+---@class StaticPlayer
 --- Money Functions
 ---@field setMoney fun(money: number)                             # Set player's cash balance.
 ---@field getMoney fun(): number                                   # Get player's current cash balance.
@@ -132,6 +112,28 @@
 ---@field executeCommand fun(command: string)    # Execute a server command.
 ---@field triggerEvent fun(eventName: string, ...) # Trigger client event for this player.

+
+---@class xPlayer:StaticPlayer
+--- 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.
+
 ---@param playerId number
 ---@param identifier string
 ---@param ssn string
@@ -277,7 +277,7 @@ end

 ESX.GetPlayers = GetPlayers

-local function checkTable(key, val, xPlayer, xPlayers)
+local function checkTable(key, val, xPlayer, xPlayers, minimal)
    for valIndex = 1, #val do
        local value = val[valIndex]
        if not xPlayers[value] then
@@ -285,23 +285,35 @@ local function checkTable(key, val, xPlayer, xPlayers)
        end

        if (key == "job" and xPlayer.job.name == value) or xPlayer[key] == value then
-            xPlayers[value][#xPlayers[value] + 1] = xPlayer
+            xPlayers[value][#xPlayers[value] + 1] = (minimal and xPlayer.source or xPlayer)
        end
    end
 end

 ---@param key? string
 ---@param val? string|table
---@return xPlayer[]|table<any, xPlayer[]>
-function ESX.GetExtendedPlayers(key, val)
+---@param minimal? boolean
+---@return xPlayer[]|number[]|table<any, xPlayer[]>|table<any, number[]>
+function ESX.GetExtendedPlayers(key, val, minimal)
    if not key then
-        return ESX.Table.ToArray(ESX.Players)
+        if not minimal then
+            return ESX.Table.ToArray(ESX.Players)
+        end
+
+        local xPlayers = {}
+        local index = 1
+        for src, _ in pairs(ESX.Players) do
+            xPlayers[index] = src
+            index += 1
+        end
+
+        return xPlayers
    end

    local xPlayers = {}
    if type(val) == "table" then
        for _, xPlayer in pairs(ESX.Players) do
-            checkTable(key, val, xPlayer, xPlayers)
+            checkTable(key, val, xPlayer, xPlayers, minimal)
        end

        return xPlayers
@@ -309,7 +321,7 @@ function ESX.GetExtendedPlayers(key, val)

    for _, xPlayer in pairs(ESX.Players) do
        if (key == "job" and xPlayer.job.name == val) or xPlayer[key] == val then
-            xPlayers[#xPlayers + 1] = xPlayer
+            xPlayers[#xPlayers + 1] = (minimal and xPlayer.source or xPlayer)
        end
    end