ox_inventory-Leitfaden: Das beliebteste FiveM-Inventar 2026

Was ist ox_inventory?

ox_inventory ist ein modernes, leistungsstarkes Inventarsystem für FiveM und hat sich als Standard für ernsthafte Roleplay-Server etabliert. Das vom Overextended-Team entwickelte System ersetzt ältere Inventarlösungen und ist schneller, flexibler und einfacher erweiterbar. Es bietet eine elegante, auf React basierende Benutzeroberfläche, integrierte Waffenverwaltung, Crafting-Unterstützung, Shops, Stashes und eine leistungsstarke API, mit der Script-Entwickler individuelle Interaktionen mit Gegenständen erstellen können. Egal, ob du einen neuen Server aufbaust oder von einem anderen Inventar wechselst: Wenn du ox_inventory genau verstehst, wirst du ein besserer FiveM-Entwickler.

Installation und Konfiguration

ox_inventory benötigt ox_lib als Abhängigkeit und funktioniert sowohl mit den Frameworks ESX und QBCore als auch in standalone-Setups. Für die Installation musst du die Ressource herunterladen, das SQL-Schema in deine Datenbank importieren und die Framework-Bridge konfigurieren. Die Konfigurationsdatei steuert alles, von Gewichtslimits des Inventars bis hin zu Verfallszeiten für Gegenstände.

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

    decay = true,
    decayInterval = 60,

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

Benutzerdefinierte Gegenstände registrieren

Gegenstände in ox_inventory werden in der data/items.lua Datei definiert. Jeder Gegenstand benötigt einen eindeutigen Namen, eine Bezeichnung und ein Gewicht. Optional kannst du außerdem eine maximale Stapelgröße, eine Verfallsrate, eine Beschreibung sowie clientseitige oder serverseitige Event-Handler festlegen. Wenn du das vollständige Schema für Gegenstandsdefinitionen kennst, kannst du Gegenstände erstellen, die genau das tun, was deine Scripts benötigen.

-- 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',
        }
    },
}

Die Server-API von ox_inventory verwenden

Die serverseitigen Exports sind der am häufigsten verwendete Teil von ox_inventory. Damit kannst du Gegenstände hinzufügen und entfernen, Inventarinhalte prüfen und Metadaten bearbeiten. Verwende zum Bearbeiten von Gegenständen immer die serverseitige API, um Exploits durch Cheater zu verhindern.

-- 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

Mit Gegenstandsmetadaten arbeiten

Gegenstandsmetadaten gehören zu den leistungsstärksten Funktionen von ox_inventory. Damit kannst du beliebige Daten an einzelne Gegenstandsinstanzen anhängen. So kannst du Waffen eindeutige Seriennummern, Lebensmitteln Verfallsdaten, Ausweisen Spielernamen und beliebigen Gegenständen benutzerdefinierte Eigenschaften zuweisen.

-- 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)

Benutzerdefinierte Shops erstellen

ox_inventory enthält ein integriertes Shopsystem, das du mit eigenen Gegenstandskatalogen, Preisen, Jobbeschränkungen und Standorten konfigurieren kannst. Shops werden in data/shops.lua definiert und können an Ped-Händler und Blip-Standorte gebunden oder programmatisch ausgelöst werden.

-- 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,
        },
    },
}

Stash-System und benutzerdefinierte Container

Stashes sind dauerhafte Lagercontainer, auf die Spieler an bestimmten Orten zugreifen können. ox_inventory unterstützt persönliche Stashes, die an eine Spielerkennung gebunden sind, gemeinsame Stashes, auf die jeder zugreifen kann, und jobbeschränkte Stashes für Beweisräume der Polizei und Lagerräume von Krankenhäusern.

-- 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)

Best Practices für die Integration von ox_inventory

• Validiere immer serverseitig. Vertraue niemals clientseitigen Inventarprüfungen. Verwende für jede wichtige Spiellogik Server-Exports wie GetItemCount und RemoveItem .
• Metadaten sparsam verwenden. Metadaten sind zwar leistungsstark, aber übermäßig viele Daten auf jedem Gegenstand erhöhen die Datenbankgröße und den Netzwerkverkehr. Speichere nur, was du tatsächlich brauchst.
• Volle Inventare sauber behandeln. Prüfe immer den Rückgabewert von AddItem und gib dem Spieler eine klare Rückmeldung, wenn sein Inventar voll ist.
• Gegenstandsverfall für mehr Realismus nutzen. Die Eigenschaft degrade sorgt für einen natürlichen Verbrauch von Gegenständen und hilft dir, deine Wirtschaft im Gleichgewicht zu halten. Lege für verderbliche Waren und Werkzeuge passende Verfallszeiten fest.
• Das integrierte Crafting-System nutzen. Verwende statt einer eigenen Crafting-Logik die Crafting-Bänke von ox_inventory. Sie übernehmen Prüfungen, das Entfernen von Zutaten und das Erstellen von Gegenständen automatisch.
• Sorge für einheitliche Bilder der Gegenstände. Platziere alle Artikelbilder in web/images/ mit passenden Dateinamen. Verwende 100x100-PNG-Dateien mit transparentem Hintergrund für ein optimales Ergebnis.