Documentation / Lost items

Lost items

Register items lost on death from FiveM and return them to the player from the web panel.

The Lost items system stores in the panel the items a player loses on death (or on any event you define). Staff can view the history on the player profile and return each item to the returns stash in ox_inventory, without the player needing to be online.

What do you need?

  • Adictos_WebLogs installed and synced with the panel (see installation)
  • ox_inventory with a returns stash per player (recommended; the panel sends the items there)
  • A death/respawn script that removes items from the player and calls the export (e.g. esx_ambulancejob, qb-ambulancejob, your own script…)

Minimal integration (any script)

When the player loses items, collect them in a table before removing them from the inventory and call the export. You only need three pieces of player data and the list of items:

local function registrarObjetosPerdidos(xPlayer, items)
    if #items == 0 then return end
    if GetResourceState('Adictos_WebLogs') ~= 'started' then return end

    exports['Adictos_WebLogs']:RegisterLostItems({
        license     = xPlayer.identifier,   -- hex, sin prefijo license:
        player_name = xPlayer.getName(),    -- nombre IC (ESX) o equivalente
        player_ooc  = GetPlayerName(xPlayer.source),
        items       = items,
    })
end

Format of each item in the array

FieldTypeDescription
namestringItem identifier in ox_inventory (e.g. bread, weapon_pistol)
labelstringDisplay name (optional; if missing, name is used)
countnumberAmount lost
metadatatableox_inventory metadata: durability, serial, components, etc. (optional)
local items = {
    {
        name = 'bread',
        label = 'Pan',
        count = 5,
        metadata = {},
    },
    {
        name = 'weapon_pistol',
        label = 'Pistola',
        count = 1,
        metadata = { durability = 72.5, serial = 'ABC-123' },
    },
}

registrarObjetosPerdidos(xPlayer, items)
RegisterLostItems has a 60-second cooldown per player to avoid duplicate records if your script fires the event twice in a row (respawn + callback, etc.). If the second call falls within that window, it is silently ignored.

Example with ox_inventory (ESX)

Common pattern on ESX: read the inventory with ox_inventory, exclude protected items, remove them from the player and register what was lost. Use the licence (xPlayer.identifier) as the panel identifier:

local ox_inventory = exports.ox_inventory
local SLOTS = GetConvarInt('inventory:slots', 50)

-- Items que NUNCA se pierden al morir (ajusta a tu servidor)
local EXCLUIDOS = {
    llavecayo = true,
    anillo = true,
    chapa = true,
    adicoins = true,
}

function PerderObjetosAlMorir(xPlayer)
    local src = xPlayer.source
    local playerItems = ox_inventory:GetInventoryItems(src)
    if not playerItems then return end

    local itemsParaWeb = {}

    for i = 1, SLOTS do
        local slot = playerItems[i]
        if slot and slot.count > 0 and not EXCLUIDOS[slot.name] then
            local meta = slot.metadata or {}
            table.insert(itemsParaWeb, {
                name = slot.name,
                label = slot.label or slot.name,
                count = slot.count,
                metadata = meta,
            })
            xPlayer.setInventoryItem(slot.name, 0)
        end
    end

    if #itemsParaWeb > 0 and GetResourceState('Adictos_WebLogs') == 'started' then
        exports['Adictos_WebLogs']:Log('death', 'items_lost', {
            license = xPlayer.identifier,
            playerName = xPlayer.name,
            playerOOC = GetPlayerName(src),
            items = itemsParaWeb,
            details = 'Objetos perdidos por muerte - Total: ' .. #itemsParaWeb .. ' items',
        })

        exports['Adictos_WebLogs']:RegisterLostItems({
            license = xPlayer.identifier,
            player_name = xPlayer.name,
            player_ooc = GetPlayerName(src),
            items = itemsParaWeb,
        })
    end
end

Call PerderObjetosAlMorir(xPlayer) from the death or respawn event. In esx_ambulancejob it is the BorrarObjetos function, invoked on respawn and in the removeItemsAfterRPDeath callback.

Example with ox_inventory (QBCore)

On QBCore the flow is the same, but you get the player with QBCore.Functions.GetPlayer(source) and remove items with ox_inventory:RemoveItem (don’t use setInventoryItem, which is ESX). Important: send the Rockstar licence (PlayerData.license without the license: prefix), not the citizenid — the panel indexes players by licence.

local QBCore = exports['qb-core']:GetCoreObject()
local ox_inventory = exports.ox_inventory
local SLOTS = GetConvarInt('inventory:slots', 50)

local EXCLUIDOS = {
    id_card = true,
    driver_license = true,
    -- añade los items protegidos de tu servidor
}

local function stripLicense(lic)
    if not lic then return nil end
    return lic:gsub('license:', '')
end

function PerderObjetosAlMorir(src)
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return end

    local pd = Player.PlayerData
    local license = stripLicense(pd.license)
    local charinfo = pd.charinfo or {}
    local playerName = ((charinfo.firstname or '') .. ' ' .. (charinfo.lastname or '')):match('^%s*(.-)%s*$')
    local playerOOC = GetPlayerName(src)

    local playerItems = ox_inventory:GetInventoryItems(src)
    if not playerItems then return end

    local itemsParaWeb = {}

    for i = 1, SLOTS do
        local slot = playerItems[i]
        if slot and slot.count > 0 and not EXCLUIDOS[slot.name] then
            local meta = slot.metadata or {}
            table.insert(itemsParaWeb, {
                name = slot.name,
                label = slot.label or slot.name,
                count = slot.count,
                metadata = meta,
            })
            ox_inventory:RemoveItem(src, slot.name, slot.count, meta, slot.slot)
        end
    end

    if #itemsParaWeb > 0 and GetResourceState('Adictos_WebLogs') == 'started' then
        exports['Adictos_WebLogs']:Log('death', 'items_lost', {
            license = license,
            playerName = playerName,
            playerOOC = playerOOC,
            items = itemsParaWeb,
            details = 'Objetos perdidos por muerte - Total: ' .. #itemsParaWeb .. ' items',
        })

        exports['Adictos_WebLogs']:RegisterLostItems({
            license = license,
            player_name = playerName,
            player_ooc = playerOOC,
            items = itemsParaWeb,
        })
    end
end

Call PerderObjetosAlMorir(source) from your hospital/death script (for example qb-ambulancejob, qb-hospital or your own resource) at the moment the player loses their inventory on respawn.

QBCore + qb-inventory (without ox_inventory): the registration pattern is identical — only how you read and remove items changes. Keep sending license (hex) and the items array with name, count and metadata where applicable.

Optional log (death category)

In addition to RegisterLostItems, you can log with Log() in the death category and the items_lost action. That leaves a record in Logs → GENERAL and in the player’s history, independent of the Lost items tab. The log’s items field accepts the same items table.

What the panel does

  • Stores each death as a record with date, expiry (30 days) and list of items
  • Shows metadata (durability, serial, components…) when present
  • Lets you return one item or all pending items of a record
  • Returned items go to the player’s returns stash in ox_inventory (not directly to the inventory)
  • Marks each item as returned and records which staff member did it

Where staff see it

  1. 1Panel → search for the player → open their profile.
  2. 2Logs tab → Lost items sub-tab.
  3. 3Requires the View logs permission (viewlogs).
Records expire after 30 days. A panel cron cleans up expired ones automatically. Already-returned ones may be deleted earlier according to the server’s retention policy.

Check that it works

  1. 1Die with a character carrying (non-excluded) items and respawn.
  2. 2In the server console (with DebugMode in WebLogs): message Objetos perdidos registrados: N items.
  3. 3Panel → player profile → Logs → Lost items: the record with the items should appear.
  4. 4Click Return on an item and check that it reaches the returns stash in game.

Troubleshooting

SymptomCommon cause
Nothing appears in the panelAdictos_WebLogs isn’t started, the server IP doesn’t match under My servers, or the items array was empty
It only appears in Logs GENERAL, not in Lost itemsYou called Log() but not RegisterLostItems()
Duplicate or incomplete recordTwo death events within 60 s; the second was ignored due to the cooldown
Error when returning from the panelFiveM server offline, ox_inventory unavailable, or returns stash misconfigured
Items without metadata when returnedYou didn’t send metadata in the array when registering the loss
QBCore: it doesn’t appear on the player profileYou sent citizenid instead of the Rockstar licence (PlayerData.license without prefix)
No extra configuration is needed in the panel to enable the system: the tables are created automatically the first time FiveM calls the API. You only need the export in your death script.