ox_inventory Rehberi: 2026'da Tercih Edilen FiveM Envanteri

ox_inventory nedir?

ox_inventory, FiveM için ciddi rol yapma sunucularının standart tercihi haline gelmiş modern ve yüksek performanslı bir envanter sistemidir. Overextended ekibi tarafından geliştirilen bu sistem, eski envanter çözümlerinin yerini daha hızlı, daha esnek ve genişletilmesi daha kolay bir sistemle alır. Şık React tabanlı bir UI, yerleşik silah yönetimi, üretim (crafting) desteği, mağazalar, zulalar ve script geliştiricilerinin özel eşya etkileşimleri oluşturmak için kullanabileceği güçlü bir API sunar. İster yeni bir sunucu kuruyor olun ister başka bir envanterden geçiş yapıyor olun, ox_inventory'yi derinlemesine anlamak sizi daha iyi bir FiveM geliştiricisi yapacaktır.

Kurulum ve Yapılandırma

ox_inventory şunları gerektirir: ox_lib bir bağımlılık olarak bulunur ve standalone kurulumların yanı sıra hem ESX hem de QBCore altyapılarıyla çalışır. Kurulum; kaynağın indirilmesini, SQL şemasının veritabanınıza aktarılmasını ve altyapı köprüsünün yapılandırılmasını içerir. Yapılandırma dosyası, envanter ağırlık sınırlarından eşya bozulma sürelerine kadar her şeyi kontrol eder.

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

    decay = true,
    decayInterval = 60,

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

Özel Eşyaları Kaydetme

ox_inventory içindeki itemler şu konumda tanımlanır: data/items.lua dosyası. Her eşya benzersiz bir ada, bir etikete, bir ağırlığa ve isteğe bağlı olarak yığın boyutuna, bozulma oranına, açıklamaya ve istemci veya sunucu taraflı olay işleyicilerine ihtiyaç duyar. Öğe tanım şemasının tamamını anlamak, scriptlerinizin tam olarak ihtiyaç duyduğu şeyi yapan eşyalar oluşturmanızı sağlar.

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

ox_inventory Sunucu API'sini Kullanma

Sunucu tarafı export'ları, ox_inventory'nin en sık kullanılan kısmıdır: eşya eklemenize, eşya kaldırmanıza, envanter içeriğini kontrol etmenize ve meta verileri düzenlemenize olanak tanır. Hileciler tarafından suistimal edilmesini önlemek için eşya manipülasyonunda her zaman sunucu tarafı API'sini kullanın.

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

Eşya Metadata'sı ile Çalışma

İtem metadatası, ox_inventory'nin en güçlü özelliklerinden biridir. Tekil item örneklerine rastgele veriler eklemenize olanak tanır: silahlarda benzersiz seri numaraları, yiyeceklerde son kullanma tarihleri, kimlik kartlarında oyuncu adları ve herhangi bir item üzerinde özel nitelikler tanımlamanızı sağlar.

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

Özel Mağazalar Oluşturma

ox_inventory, özel eşya katalogları, fiyatlandırma, meslek kısıtlamaları ve konumlarla yapılandırabileceğiniz yerleşik bir mağaza sistemi içerir. Mağazalar şurada tanımlanır: data/shops.lua ve ped satıcılarına, blip konumlarına eklenebilir veya programatik olarak tetiklenebilir.

-- 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 Sistemi ve Özel Konteynerler

Stash'ler, oyuncuların belirli konumlarda erişebileceği kalıcı depolama konteynerleridir. ox_inventory, bir oyuncu kimliğine bağlı kişisel stash'leri, herkesin erişebileceği paylaşılan stash'leri ve polis kanıt odaları ile hastane depoları için meslek kısıtlamalı stash'leri destekler.

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

ox_inventory Entegrasyonu İçin En İyi Uygulamalar

• Her zaman sunucu tarafında doğrulayın. İstemci tarafı envanter kontrollerine asla güvenmeyin. Şu gibi sunucu exportlarını kullanın: GetItemCount ve RemoveItem tüm kritik oyun mantığı için.
• Meta verileri tasarruflu kullanın. Metadata güçlü bir özellik olsa da, her öğede aşırı veri depolamak veritabanı boyutunu ve ağ trafiğini artırır. Yalnızca gerçekten ihtiyacınız olanı saklayın.
• Dolu envanterleri sorunsuzca yönetin. Her zaman şunun dönüş değerini kontrol edin: AddItem ve envanterleri dolduğunda oyuncuya net geri bildirim sağlayın.
• Gerçekçilik için eşya yıpranmasını kullanın. Degrade özelliği, ekonominizi dengede tutan doğal eşya tüketim kanalları (item sinks) yaratır. Bozulabilir mallar ve aletler için uygun aşınma süreleri belirleyin.
• Yerleşik crafting sisteminden yararlanın. Kendi crafting mantığınızı geliştirmek yerine, kontrolleri, eşya silmeyi ve oluşturmayı otomatik olarak halleden ox_inventory crafting tezgahlarını kullanın.
• Eşya görsellerini tutarlı tutun. Tüm eşya görsellerini şuraya yerleştirin: web/images/ eşleşen dosya adları ile. En temiz görünüm için şeffaf arka plana sahip 100x100 PNG dosyaları kullanın.