Documentation / Objets perdus

Objets perdus

Enregistrez les objets perdus à la mort depuis FiveM et rendez-les au joueur depuis le panneau web.

Le système d’Objets perdus enregistre dans le panneau les objets qu’un joueur perd à sa mort (ou lors de tout événement que vous définissez). Le staff peut consulter l’historique sur le profil du joueur et rendre chaque objet dans l’entrepôt de retours d’ox_inventory, sans que le joueur ait besoin d’être connecté.

De quoi avez-vous besoin ?

  • Adictos_WebLogs installé et synchronisé avec le panneau (voir l’installation)
  • ox_inventory avec un stash de retours par joueur (recommandé ; le panneau y envoie les objets)
  • Un script de mort/respawn qui retire les objets du joueur et appelle l’export (ex. esx_ambulancejob, qb-ambulancejob, script personnel…)

Intégration minimale (n’importe quel script)

Lorsque le joueur perd des objets, regroupez-les dans une table avant de les retirer de l’inventaire et appelez l’export. Il vous suffit de trois données du joueur et de la liste des objets :

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 de chaque objet du tableau

ChampTypeDescription
namestringIdentifiant de l’objet dans ox_inventory (ex. bread, weapon_pistol)
labelstringNom affiché (optionnel ; à défaut, name est utilisé)
countnumberQuantité perdue
metadatatableMétadonnées ox_inventory : durabilité, numéro de série, composants, etc. (optionnel)
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 a un délai de 60 secondes par joueur pour éviter les doublons si votre script déclenche l’événement deux fois de suite (respawn + callback, etc.). Si le second appel tombe dans cette fenêtre, il est ignoré silencieusement.

Exemple avec ox_inventory (ESX)

Schéma courant sous ESX : lire l’inventaire avec ox_inventory, exclure les objets protégés, les retirer au joueur et enregistrer ce qui a été perdu. Utilisez la licence (xPlayer.identifier) comme identifiant du panneau :

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

Appelez PerderObjetosAlMorir(xPlayer) depuis l’événement de mort ou de respawn. Dans esx_ambulancejob, il s’agit de la fonction BorrarObjetos, appelée au respawn et dans le callback removeItemsAfterRPDeath.

Exemple avec ox_inventory (QBCore)

Sous QBCore, le flux est le même, mais vous obtenez le joueur avec QBCore.Functions.GetPlayer(source) et retirez les objets avec ox_inventory:RemoveItem (n’utilisez pas setInventoryItem, propre à ESX). Important : envoyez la licence Rockstar (PlayerData.license sans le préfixe license:), pas le citizenid — le panneau indexe les joueurs par 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

Appelez PerderObjetosAlMorir(source) depuis votre script d’hôpital/de mort (par exemple qb-ambulancejob, qb-hospital ou une ressource personnelle) au moment où le joueur perd son inventaire au respawn.

QBCore + qb-inventory (sans ox_inventory) : le schéma d’enregistrement est identique — seule la façon de lire et de retirer les objets change. Continuez à envoyer license (hex) et le tableau items avec name, count et metadata le cas échéant.

Log optionnel (catégorie death)

En plus de RegisterLostItems, vous pouvez enregistrer un log avec Log() dans la catégorie death et l’action items_lost. Cela laisse une trace dans Logs → GENERAL et dans l’historique du joueur, indépendamment de l’onglet Objets perdus. Le champ items du log accepte la même table d’objets.

Ce que fait le panneau

  • Enregistre chaque mort comme un registre avec date, expiration (30 jours) et liste d’objets
  • Affiche les métadonnées (durabilité, numéro de série, composants…) lorsqu’elles existent
  • Permet de rendre un objet ou tous les objets en attente d’un registre
  • Les objets rendus vont dans le stash retours du joueur dans ox_inventory (pas directement dans l’inventaire)
  • Marque chaque objet comme rendu et enregistre quel membre du staff l’a fait

Où le staff le voit

  1. 1Panneau → rechercher le joueur → ouvrir son profil.
  2. 2Onglet Logs → sous-onglet Objets perdus.
  3. 3Nécessite la permission Voir les logs (viewlogs).
Les registres expirent au bout de 30 jours. Un cron du panneau supprime automatiquement ceux qui ont expiré. Ceux déjà rendus peuvent être supprimés plus tôt selon la politique de rétention du serveur.

Vérifier que tout fonctionne

  1. 1Mourez avec un personnage portant des objets (non exclus) et réapparaissez.
  2. 2Dans la console du serveur (avec DebugMode dans WebLogs) : message Objetos perdidos registrados: N items.
  3. 3Panneau → profil du joueur → Logs → Objets perdus : le registre avec les objets doit apparaître.
  4. 4Cliquez sur Rendre sur un objet et vérifiez qu’il arrive dans le stash de retours en jeu.

Dépannage

SymptômeCause habituelle
Rien n’apparaît dans le panneauAdictos_WebLogs n’est pas démarré, l’IP du serveur ne correspond pas dans Mes serveurs, ou le tableau items était vide
N’apparaît que dans Logs GENERAL, pas dans Objets perdusVous avez appelé Log() mais pas RegisterLostItems()
Registre en double ou incompletDeux événements de mort en moins de 60 s ; le second a été ignoré à cause du délai
Erreur lors du retour depuis le panneauServeur FiveM hors ligne, ox_inventory indisponible ou stash de retours mal configuré
Objets sans métadonnées lors du retourVous n’avez pas envoyé metadata dans le tableau lors de l’enregistrement de la perte
QBCore : n’apparaît pas sur le profil du joueurVous avez envoyé citizenid au lieu de la licence Rockstar (PlayerData.license sans préfixe)
Aucune configuration supplémentaire n’est nécessaire dans le panneau pour activer le système : les tables se créent automatiquement la première fois que FiveM appelle l’API. Il vous suffit de l’export dans votre script de mort.