Guide ox_inventory : inventaire FiveM moderne

Qu'est-ce que ox_inventory ?

ox_inventory est un système d'inventaire moderne et performant pour FiveM qui est devenu le choix standard pour les serveurs de jeu de rôle sérieux. Construit par l'équipe Overextended, il remplace les anciennes solutions d'inventaire par un système plus rapide, plus flexible et plus facile à étendre. Il comprend une interface utilisateur élégante basée sur React, une gestion intégrée des armes, une prise en charge de la fabrication, des magasins, des cachettes et un puissant API que les développeurs de scripts peuvent utiliser pour créer des interactions d'objets personnalisées. Que tu construisies un nouveau serveur ou que tu migracies à partir d'un autre inventaire, une compréhension approfondie de ox_inventory fera de tu un meilleur développeur FiveM.

Installation et configuration

ox_inventory nécessite ox_lib en tant que dépendance et fonctionne avec les frameworks ESX et QBCore, ainsi qu'avec les configurations autonomes. L'installation implique le téléchargement de la ressource, l'importation du schéma SQL dans ton base de données et la configuration du pont de structure. Le fichier de configuration contrôle tout, depuis les limites de poids des stocks jusqu'aux minuteries de dégradation des articles.

-- Configuration snippet from ox_inventory
return {
    playerslots = 50,
    playerweight = 30000,
    playerweaponslots = 5,

    decay = true,
    decayInterval = 60,

    trunkslots = 50,
    trunkweight = 60000,
    gloveboxslots = 5,
    gloveboxweight = 5000,
}

Enregistrement d'éléments personnalisés

Les éléments de ox_inventory sont définis dans le data/items.lua déposer. Chaque élément nécessite un nom unique, une étiquette, un poids et éventuellement une taille de pile, un taux de décroissance, une description et des gestionnaires d'événements côté client ou côté serveur. Comprendre le schéma de définition complet des éléments tu permet de créer des éléments qui font exactement ce dont tes scripts ont besoin.

-- data/items.lua
return {
    ['water_bottle'] = {
        label = 'Water Bottle',
        weight = 500,
        stack = true,
        close = true,
        description = 'A refreshing bottle of water',
        client = {
            image = 'water_bottle.png',
        }
    },

    ['lockpick'] = {
        label = 'Lockpick',
        weight = 200,
        stack = true,
        close = true,
        degrade = 300,
        description = 'Used to pick locks. Breaks after use.',
    },

    ['driver_license'] = {
        label = 'Driver License',
        weight = 0,
        stack = false,
        consume = 0,
        description = 'Issued by the DMV',
        client = {
            image = 'driver_license.png',
        }
    },
}

Utilisation du serveur ox_inventory API

Les exportations côté serveur constituent la partie la plus couramment utilisée de ox_inventory, tu permettant d'ajouter des éléments, de supprimer des éléments, de vérifier le contenu de l'inventaire et de manipuler des métadonnées. Utilisez toujours le API côté serveur pour la manipulation des éléments afin d'empêcher leur exploitation par des tricheurs.

-- Server-side: Adding items to a player
RegisterNetEvent('myresource:giveReward', function(itemName, count)
    local src = source
    local success = exports.ox_inventory:AddItem(src, itemName, count)

    if success then
        TriggerClientEvent('ox_lib:notify', src, {
            title = 'Item Received',
            description = count .. 'x ' .. itemName,
            type = 'success'
        })
    else
        TriggerClientEvent('ox_lib:notify', src, {
            title = 'Inventory Full',
            description = 'Could not add item to inventory',
            type = 'error'
        })
    end
end)

-- Server-side: Check if player has required items
local function HasRequiredItems(src, requirements)
    for _, req in ipairs(requirements) do
        local count = exports.ox_inventory:GetItemCount(src, req.name)
        if count < req.amount then
            return false, req.name, req.amount - count
        end
    end
    return true
end

-- Server-side: Remove multiple items in a transaction
local function ConsumeRecipeItems(src, recipe)
    for _, ingredient in ipairs(recipe.ingredients) do
        local removed = exports.ox_inventory:RemoveItem(
            src, ingredient.name, ingredient.amount
        )
        if not removed then
            print(('[ERROR] Failed to remove %s from player %d'):format(
                ingredient.name, src
            ))
            return false
        end
    end
    return true
end

Travailler avec les métadonnées d'un article

Les métadonnées des éléments sont l'une des fonctionnalités les plus puissantes de ox_inventory. Il tu permet de joindre des données arbitraires à des instances d'objets individuelles, permettant des numéros de série uniques sur les armes, des dates d'expiration sur les aliments, des noms de joueurs sur les cartes d'identité et des propriétés personnalisées sur n'importe quel objet.

-- Server: Create a driver license with metadata
RegisterNetEvent('myresource:issueLicense', function(targetId, licenseType)
    local src = source

    local metadata = {
        type = licenseType,
        issued = os.date('%Y-%m-%d'),
        issuedBy = GetPlayerName(src),
        holder = GetPlayerName(targetId),
        expires = os.date('%Y-%m-%d', os.time() + 30 * 86400),
    }

    exports.ox_inventory:AddItem(targetId, 'driver_license', 1, metadata)
end)

-- Client: Reading metadata when using an item
exports('driver_license', function(data, slot)
    local item = exports.ox_inventory:GetSlot(slot)
    if not item or not item.metadata then return end

    local meta = item.metadata
    lib.notify({
        title = 'Driver License',
        description = ('Holder: %s\nType: %s\nExpires: %s'):format(
            meta.holder or 'Unknown',
            meta.type or 'Standard',
            meta.expires or 'N/A'
        ),
        type = 'inform'
    })
end)

Création de boutiques personnalisées

ox_inventory comprend un système de boutique intégré que tu peux configurer avec des catalogues d'articles personnalisés, des prix, des restrictions de travail et des emplacements. Les magasins sont définis dans data/shops.lua et peut être attaché à des fournisseurs de pédagogie, à des emplacements d'incidents ou déclenché par programme.

-- data/shops.lua
return {
    ['hardware_store'] = {
        name = 'Hardware Store',
        inventory = {
            { name = 'lockpick',    price = 150,  count = 10 },
            { name = 'screwdriver', price = 80,   count = 20 },
            { name = 'radio',       price = 250,  count = 5  },
            { name = 'repairkit',   price = 1000, count = 5  },
        },
        locations = {
            vec3(45.6, -1749.3, 29.6),
            vec3(2747.8, 3472.9, 55.7),
        },
        targets = {
            ped = 's_m_y_hardware_01',
            scenario = 'WORLD_HUMAN_STAND_IMPATIENT',
            distance = 2.5,
        },
    },
}

Système de cachette et conteneurs personnalisés

Les cachettes sont des conteneurs de stockage persistants auxquels les joueurs peuvent accéder à des endroits spécifiques. ox_inventory prend en charge les caches personnelles liées à un identifiant de joueur, les caches partagées accessibles à tous et les caches restreintes à l'emploi pour les salles de preuves de la police et le stockage des hôpitaux.

-- Server: Register a custom stash for a property
local function CreatePropertyStash(propertyId, owner)
    local stashId = ('property_%s'):format(propertyId)

    exports.ox_inventory:RegisterStash(
        stashId,
        ('Property #%s Storage'):format(propertyId),
        100,     -- slots
        200000,  -- max weight
        owner    -- owner identifier (or false for shared)
    )

    return stashId
end

-- Client: Open a stash when interacting with a storage point
RegisterNetEvent('myresource:openPropertyStorage', function(propertyId)
    local stashId = ('property_%s'):format(propertyId)
    exports.ox_inventory:openInventory('stash', stashId)
end)

Meilleures pratiques pour l'intégration de ox_inventory

• Validez toujours côté serveur. Ne faites jamais confiance aux contrôles d’inventaire côté client. Utilisez les exportations de serveur comme GetItemCount et RemoveItem pour toute la logique de jeu critique.
• Utilisez les métadonnées avec parcimonie. Même si les métadonnées sont puissantes, le stockage excessif de données sur chaque élément augmente la taille de la base de données et le trafic réseau. Ne stockez que ce dont tu as réellement besoin.
• Gérez les stocks complets avec élégance. Vérifiez toujours la valeur de retour de AddItem et fournir des commentaires clairs au joueur lorsque son inventaire est plein.
• Utilisez la dégradation des objets pour plus de réalisme. La propriété de dégradation crée des puits d’éléments naturels qui maintiennent l’équilibre de ton économie. Fixez des temps de décomposition appropriés pour les biens périssables et les outils.
• Tirez parti du système de fabrication intégré. Au lieu de créer ton propre logique de création, utilisez les bancs de création ox_inventory qui gèrent automatiquement les vérifications, la suppression et la création.
• Gardez les images des articles cohérentes. Placez toutes les images des articles dans web/images/ avec les noms de fichiers correspondants. Utilisez des fichiers PNG 100x100 avec des arrière-plans transparents pour un look plus épuré.