Métadonnées d'éléments ox_inventory : AddItem, Search, SetMetadata et éléments uniques

Un élément dans ox_inventory est un nom et un nombre. Lorsque deux éléments portant le même nom doivent être différents, comme une clé de voiture pour une plaque et une clé pour une autre, vous utilisez les métadonnées : une table stockée avec l'élément. Cet article montre comment ajouter un élément avec des métadonnées, le trouver à nouveau, le lire et le mettre à jour, l'afficher, et construire des éléments uniques comme les identifiants et les clés.

#Ajouter un élément avec des métadonnées

Le quatrième argument de AddItem est la table de métadonnées :

exports.ox_inventory:AddItem(source, 'car_key', 1, {
    plate = 'ABC 123',
    label = 'Key ABC 123',
    description = 'Opens the car with plate ABC 123.',
})

La signature est AddItem(inventory, item, count, metadata). inventory est l'id du joueur pour un inventaire de joueur. Toute clé que vous ajoutez est stockée avec l'emplacement, et vous pouvez la lire à nouveau plus tard. Gardez les métadonnées petites et faites de données simples : chaînes, nombres, booléens et tables simples.

Astuce : l'élément doit exister dans data/items.lua, par exemple car_key. Voir adding items to ox_inventory.

#L'afficher au joueur

Quelques clés de métadonnées changent ce que l'inventaire affiche :

exports.ox_inventory:AddItem(source, 'id_card', 1, {
    label = 'ID card: Jane Doe',
    description = 'Born 1994-05-12',
    image = 'id_card',
})

Tout ce que vous mettez d'autre dans la table est stocké, mais ne s'affiche pas, à moins que la propre définition de l'élément ne l'affiche. Utilisez une label unique lorsque vous avez besoin que les joueurs distinguent les éléments d'un coup d'œil.

#Chercher des éléments

Search trouve des éléments dans un inventaire. Avec 'count' il retourne le nombre, avec 'slots' il retourne les emplacements :

local count = exports.ox_inventory:Search(source, 'count', 'car_key')

local slots = exports.ox_inventory:Search(source, 'slots', 'car_key')
for _, slot in pairs(slots) do
    print(slot.slot, slot.metadata and slot.metadata.plate)
end

Vous pouvez également filtrer par métadonnées. Passez une table en tant que quatrième argument :

local keys = exports.ox_inventory:Search(source, 'slots', 'car_key', { plate = 'ABC 123' })
if #keys > 0 then
    -- the player has the key for that plate
end

C'est le moyen standard de vérifier la propriété : faites-le sur le serveur, avec les données en lesquelles vous avez confiance, jamais à partir d'un message client.

#Lire un emplacement

Si vous connaissez le numéro de l'emplacement, GetSlot retourne les données de cet emplacement :

local slot = exports.ox_inventory:GetSlot(source, 5)
if slot and slot.name == 'car_key' then
    print(slot.metadata.plate)
end

Lorsque vous ne connaissez que l'élément, utilisez GetSlotWithItem :

local slot = exports.ox_inventory:GetSlotWithItem(source, 'car_key', { plate = 'ABC 123' })

Les deux retournent nil quand rien ne correspond, donc vérifiez le résultat avant de lire slot.metadata. Un emplacement a aussi slot.count et slot.weight.

#Mettre à jour les métadonnées avec SetMetadata

Pour modifier un emplacement existant, par exemple marquer une clé comme copiée, ou réduire les charges restantes sur un élément, utilisez SetMetadata :

local slot = exports.ox_inventory:GetSlotWithItem(source, 'battery')
if slot then
    local metadata = slot.metadata or {}
    metadata.charge = (metadata.charge or 100) - 10
    exports.ox_inventory:SetMetadata(source, slot.slot, metadata)
end

SetMetadata(inventory, slot, metadata) remplace les métadonnées de l'emplacement par la table que vous donnez. Copiez d'abord la table existante, changez un champ, et envoyez la table entière en arrière, sinon vous effacez les autres clés.

#Éléments uniques : identifiants, clés, permis

Pour un élément unique, vous voulez deux choses : un élément qui ne s'empile pas, et des métadonnées qui l'identifient.

-- data/items.lua
['id_card'] = {
    label = 'ID card',
    weight = 10,
    stack = false,
    close = true,
},

-- server: give it at character creation
exports.ox_inventory:AddItem(source, 'id_card', 1, {
    firstname = 'Jane',
    lastname = 'Doe',
    dob = '1994-05-12',
    label = 'ID card: Jane Doe',
})

Les éléments avec des métadonnées différentes ne s'empilent pas, donc deux clés pour deux voitures occupent toujours deux emplacements, et stack = false le rend explicite pour les éléments qui ne devraient jamais.

Pour lire les données lorsque l'élément est utilisé, enregistrez une export serveur sur l'élément :

-- data/items.lua
['id_card'] = {
    label = 'ID card',
    weight = 10,
    stack = false,
    server = { export = 'my_script.id_card' },
},

-- my_script/server.lua
exports('id_card', function(event, item, inventory, slot, data)
    if event == 'usingItem' then
        local info = exports.ox_inventory:GetSlot(inventory.id, slot)
        if info and info.metadata then
            print(info.metadata.firstname, info.metadata.lastname)
        end
    end
end)

L'argument event vous dit la phase de l'utilisation. Les arguments exacts dépendent de votre version d'ox_inventory, donc consultez la documentation de votre version si l'export n'est pas appelée.

#Choses à regarder

• Les métadonnées vivent sur l'emplacement. Lorsque le joueur lâche ou échange l'élément, il se déplace avec lui, et c'est l'élément qui prouve le droit d'accéder à quelque chose.
• Ne mettez pas de secrets dans les métadonnées. Les joueurs ne voient pas les clés non listées, mais les traitent comme des données, pas comme une protection.
• Beaucoup d'éléments avec de grandes tables de métadonnées rend l'enregistrement de l'inventaire plus lent. Stockez un id et gardez les données lourdes dans votre propre table de base de données.
• Les métadonnées définies sur le client ne sont pas dignes de confiance. Appelez toujours AddItem et SetMetadata à partir du code serveur.

#Liste de contrôle