02 - Registrare Items in ox_inventory

5 min read

Registrare Items in ox_inventory

INFO

In ox_inventory gli item non si registrano a runtime con export come RegisterWeapon. Si definiscono in file di dati (data/items.lua e data/weapons.lua) che la risorsa legge all’avvio. Questa nota spiega il formato reale.

ObiettivoDettagli
Cosa imparerai• Il formato reale di data/items.lua e data/weapons.lua
• Come aggiungere item e armi custom
• Come dare/rimuovere/controllare item con le export reali
Prerequisiti• ox_inventory installato e avviato
• Conoscenza base di ESX
• Un server FiveM funzionante

Come funziona la registrazione

ox_inventory carica al boot:

  • ox_inventory/data/items.lua — item generici (cibo, oggetti, materiali)
  • ox_inventory/data/weapons.lua — armi, componenti e munizioni

WARNING

Non usare export tipo RegisterWeapon o RegisterItem: non esistono in ox_inventory. Il modo supportato è aggiungere le voci ai file data/. Gli update di ox_inventory possono sovrascrivere i file modificati: tieni un backup. Se vuoi separare i tuoi item, puoi creare una risorsa che li unisce al boot, ma per le guide usiamo i file dati standard.

Struttura di data/items.lua

return {
    ['nome_item'] = {
        label = 'Nome Visibile',
        weight = 100,          -- peso in grammi
        stack = true,          -- impilabile?
        close = true,          -- chiude l'inventario all'uso?
        consume = 1,           -- quanti ne consuma all'uso
        description = 'Una descrizione',
        degrade = 60,          -- (opzionale) tempo in minuti prima che deperisca
    },
}

Esempio reale (dal file vanilla):

return {
    ['water'] = {
        label = 'Water',
        weight = 500,
        client = {
            status = { thirst = 200000 },
            anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle' },
            prop = { model = `prop_ld_flow_bottle`, pos = vec3(0.03, 0.03, 0.02), rot = vec3(0.0, 0.0, -1.5) },
            usetime = 2500,
            notification = 'Hai bevuto un po di acqua fresca'
        }
    },
 
    ['bandage'] = {
        label = 'Bandage',
        weight = 115,
        client = {
            anim = { dict = 'missheistdockssetup1clipboard@idle_a', clip = 'idle_a', flag = 49 },
            prop = { model = `prop_rolled_sock_02`, pos = vec3(-0.14, -0.14, -0.08), rot = vec3(-50.0, -50.0, 0.0) },
            usetime = 2500,
        }
    },
}

Campi client utili: anim (dizionario/clip), prop (modello da tenere in mano), usetime (ms), status (es. fame/sete), notification. I campi server/client con export permettono di collegare una funzione della tua risorsa all’uso dell’item.

Armi in data/weapons.lua

Le armi si registrano nella tabella Weapons di ox_inventory/data/weapons.lua:

return {
    Weapons = {
        ['WEAPON_M4A1_CUSTOM'] = {
            label = 'M4A1 Tactical',
            weight = 2500,           -- grammi
            durability = 0.02,       -- degrado per colpo (0 = infinito)
            ammoname = 'ammo-rifle', -- munizioni collegate
        },
    },
 
    Components = {
        -- es. mirino custom (opzionale)
        ['at_scope_custom'] = {
            label = 'Mirino Custom',
            type = 'sight',
            weight = 280,
            client = {
                component = {
                    `COMPONENT_AT_SCOPE_SMALL`,
                },
                usetime = 2500,
            }
        },
    },
 
    Ammo = {
        ['ammo-rifle'] = {
            label = '5.56x45',
            weight = 4,     -- grammi per proiettile
        },
    },
}

WARNING

Il name deve essere l’hash name dell’arma (quello che usi in GiveWeaponToPed). Se la tua arma si chiama w_m4a1_custom, l’hash name è WEAPON_M4A1_CUSTOM (convenzione GTA V).

Registrare munizioni

Nella tabella Ammo aggiungi il calibro, poi collega ogni arma con ammoname:

Ammo = {
    ['ammo-pistol'] = {
        label = '9mm',
        weight = 7,
    },
    ['ammo-rifle'] = {
        label = '5.56x45',
        weight = 4,
    },
    ['ammo-shotgun'] = {
        label = '12 Gauge',
        weight = 38,
    },
}

Framework e Convar

ox_inventory si adatta al framework tramite convar in server.cfg:

setr inventory:framework "esx"    -- esx, ox, qbx, nd, custom
setr inventory:slots 50           -- slot per giocatore
setr inventory:weight 30000       -- peso massimo in grammi
set inventory:accounts ["money"]  -- sincronizza item 'money' con l'account ESX

Usare gli Item nel Codice (export reali)

Tutte le export vanno chiamate con exports.ox_inventory:NomeExport(...).

Dare / rimuovere item

-- server.lua
-- Aggiunge 1 repair_kit al giocatore source
local added = exports.ox_inventory:AddItem(source, 'repair_kit', 1)
-- AddItem ritorna la quantita effettivamente aggiunta (0 se inventario pieno)
 
-- Rimuove 1 item
local removed = exports.ox_inventory:RemoveItem(source, 'repair_kit', 1)

Controllare se il giocatore ha un item

-- Ritorna il conteggio
local count = exports.ox_inventory:Search(source, 'count', 'repair_kit')
if count >= 1 then
    print('Ha un repair_kit')
end
 
-- Ritorna il primo slot con l'item (o nil)
local item = exports.ox_inventory:GetItem(source, 'repair_kit')

Armi

-- Da un'arma con 120 munizioni (metadata ammo)
exports.ox_inventory:AddItem(source, 'WEAPON_M4A1_CUSTOM', 1, {
    ammo = 120,
})
 
-- Controlla se possiede l'arma
local weapon = exports.ox_inventory:GetItem(source, 'WEAPON_M4A1_CUSTOM')
if weapon then
    print('Ha l arma, slot:', weapon.slot, 'munizioni:', weapon.metadata.ammo)
end

TIP

Con ox_inventory le armi sono item veri e propri: GetItem restituisce anche metadata.ammo, metadata.components e metadata.durability. Con il convar inventory:framework "esx" le export di ESX come xPlayer.addWeapon vengono reindirizzate automaticamente a ox_inventory.

Item generico via ESX

-- Se usi la bridge ESX di ox_inventory puoi anche:
-- xPlayer.addInventoryItem('repair_kit', 1)
-- xPlayer.removeInventoryItem('repair_kit', 1)
-- xPlayer.getInventoryItem('repair_kit').count
AzioneAPI reale
Definire itemdata/items.lua (return table)
Definire armidata/weapons.lua tabella Weapons
Munizionidata/weapons.lua tabella Ammo + ammoname
Aggiungere itemexports.ox_inventory:AddItem(source, item, count, metadata)
Rimuovere itemexports.ox_inventory:RemoveItem(source, item, count, metadata)
Contare itemexports.ox_inventory:Search(source, 'count', item)
Leggere itemexports.ox_inventory:GetItem(source, item)

TIP

Prossimo passo: 03 - Armi Custom con ESX

Torna alla: Indice Generale