Éléments ESX : la table items, RegisterUsableItem et addInventoryItem

Vous voulez un nouvel élément sur votre serveur ESX : un burger, un téléphone, un pied-de-biche. Dans ESX, un élément est une ligne de la base de données, et un script le donne, le supprime et l'utilise via l'objet joueur. Cet article couvre la table items, rendre un élément utilisable, les fonctions xPlayer que vous utilisez tous les jours, et ce qui change quand le serveur exécute ox_inventory.

#La table items

ESX lit ses éléments depuis la table items. Ses colonnes sont :

Ajoutez un élément avec SQL :

INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`)
VALUES ('burger', 'Burger', 1, 0, 1);

Redémarrez ESX, ou le serveur entier, pour qu'il recharge la table. Si votre base de données montre un ensemble différent de colonnes, suivez les colonnes qu'elle a, car les versions diffèrent un peu. Si vous n'êtes pas sûr de comment exécuter une requête, voir Requêtes oxmysql.

Attention : le nom de l'élément est la clé. burger et Burger sont différents, et un élément ajouté avec la mauvaise orthographe échoue silencieusement dans la plupart des scripts.

#Rendre un élément utilisable

Enregistrez l'élément sur le serveur, dans un script :

ESX = exports['es_extended']:getSharedObject()

ESX.RegisterUsableItem('burger', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return end

    xPlayer.removeInventoryItem('burger', 1)
    TriggerClientEvent('my_script:eatBurger', source)
end)

Le rappel s'exécute sur le serveur quand le joueur utilise l'élément. Il ne supprime pas l'élément par lui-même, donc vous le supprimez vous-même. Faites la suppression sur le serveur, puis dites au client de jouer l'animation. Si l'objet est nil, voir ESX is nil: fixing getSharedObject.

Sur le client, l'événement doit seulement jouer l'effet :

RegisterNetEvent('my_script:eatBurger', function()
    -- animation, progress bar, hunger update
end)

#Donnez, supprimez et vérifiez les éléments

Ce sont les fonctions xPlayer dont vous avez besoin :

local xPlayer = ESX.GetPlayerFromId(source)

-- give
xPlayer.addInventoryItem('burger', 2)

-- remove
xPlayer.removeInventoryItem('burger', 1)

-- read one item
local item = xPlayer.getInventoryItem('burger')
print(item.count)

getInventoryItem retourne une table avec au moins count, label et name. Si l'élément n'existe pas dans la table, le résultat peut être nil sur certaines versions, donc vérifiez avant de lire count.

Un modèle fiable est de vérifier avant de supprimer :

local item = xPlayer.getInventoryItem('lockpick')
if item and item.count >= 1 then
    xPlayer.removeInventoryItem('lockpick', 1)
    -- do the action
else
    xPlayer.showNotification('You need a lockpick')
end

#Vérifiez d'abord le poids : canCarryItem

Avant de donner un élément, demandez si le joueur peut le porter. Si vous ne le faites pas, addInventoryItem peut échouer sur un inventaire plein et le joueur perd la récompense :

if xPlayer.canCarryItem('burger', 2) then
    xPlayer.addInventoryItem('burger', 2)
else
    xPlayer.showNotification('You cannot carry that much')
end

canCarryItem(name, count) compare le poids de l'élément avec le poids libre du joueur. Utilisez-le partout où un script récompense un élément : emplois, fabrication, butin. Pour d'autres aides, voir Configuration de l'emploi ESX.

#Un exemple : une boutique qui vend un élément

Mettez les pièces ensemble sur le serveur, avec une vérification d'argent et de poids :

RegisterNetEvent('my_script:buyBurger', function()
    local src = source
    local xPlayer = ESX.GetPlayerFromId(src)
    if not xPlayer then return end

    local price = 10
    if xPlayer.getAccount('money').money < price then
        return xPlayer.showNotification('Not enough money')
    end
    if not xPlayer.canCarryItem('burger', 1) then
        return xPlayer.showNotification('Your inventory is full')
    end

    xPlayer.removeAccountMoney('money', price)
    xPlayer.addInventoryItem('burger', 1)
end)

Le prix et l'élément sont fixés sur le serveur. Le client dit seulement « Je veux un burger », il n'envoie jamais le prix. Voir Sécuriser les événements serveur pour savoir pourquoi.

#ESX avec ox_inventory

De nombreux serveurs ESX exécutent ox_inventory au lieu de l'inventaire par défaut. Alors :

• les éléments sont définis dans ox_inventory/data/items.lua, pas dans la table SQL
• la famille xPlayer.addInventoryItem fonctionne toujours, car ESX la remet à ox_inventory
• ESX.RegisterUsableItem fonctionne toujours, donc les anciens scripts n'ont pas besoin de changement
• l'élément doit exister dans items.lua, ou l'appel échoue

Pour basculer, suivez la configuration ox_inventory pour ESX, et définissez l'option d'inventaire personnalisé dans la config es_extended pour que ESX sache quel inventaire est en utilisation. Pour ajouter un élément de la manière ox_inventory, voir comment ajouter des éléments à ox_inventory.

Astuce : si vous ne voulez pas modifier SQL ou Lua pour chaque nouvel élément, Item Creator vous permet de créer des éléments en jeu.

#Liste de vérification