دليل ox_inventory: الجرد المفضل في FiveM لعام 2026

ما هو ox_inventory؟

ox_inventory هو نظام جرد حديث وعالي الأداء لـ FiveM أصبح الخيار القياسي لخوادم اللعب الجاد. تم تطويره بواسطة فريق Overextended، ويحل محل حلول الجرد القديمة بنظام أسرع وأكثر مرونة وأسهل في التوسيع. يتميز بواجهة مستخدم أنيقة مبنية على React، وإدارة أسلحة مدمجة، ودعم التصنيع، والمتاجر، والتخزين، وAPI قوي يمكن لمطوري السكريبتات استخدامه لإنشاء تفاعلات عناصر مخصصة. سواء كنت تبني خادمًا جديدًا أو تنتقل من نظام جرد آخر، فإن فهم ox_inventory بعمق سيجعلك مطور FiveM أفضل.

التثبيت والتكوين

يتطلب ox_inventory ox_lib كاعتماد وتعمل مع أُطُر ESX و QBCore، وكذلك الإعدادات المستقلة. يتضمن التثبيت تنزيل المورد، استيراد مخطط SQL إلى قاعدة بياناتك، وتكوين جسر الإطار. يتحكم ملف التكوين في كل شيء من حدود وزن الجرد إلى مؤقتات تلف العناصر.

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

    decay = true,
    decayInterval = 60,

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

تسجيل العناصر المخصصة

العناصر في ox_inventory تُعرّف في data/items.lua الملف. كل عنصر يحتاج إلى اسم فريد، تسمية، وزن، وخيارياً حجم التكديس، معدل التلف، وصف، ومعالجات أحداث على جانب العميل أو الخادم. فهم مخطط تعريف العنصر الكامل يتيح لك إنشاء عناصر تفعل بالضبط ما تحتاجه سكريبتاتك.

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

استخدام API خادم ox_inventory

تُعد الصادرات على جانب الخادم الجزء الأكثر استخدامًا من ox_inventory، مما يتيح لك إضافة عناصر، إزالة عناصر، التحقق من محتويات المخزون، والتلاعب بالبيانات الوصفية. استخدم دائمًا API جانب الخادم لمعالجة العناصر لمنع الاستغلال من قبل الغشاشين.

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

العمل مع بيانات التعريف للعناصر

بيانات تعريف العنصر هي واحدة من أقوى ميزات ox_inventory. تتيح لك إرفاق بيانات عشوائية لحالات العناصر الفردية، مما يمكّن من أرقام تسلسلية فريدة على الأسلحة، تواريخ انتهاء صلاحية على الطعام، أسماء اللاعبين على بطاقات الهوية، وخصائص مخصصة على أي عنصر.

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

إنشاء متاجر مخصصة

يتضمن ox_inventory نظام متجر مدمج يمكنك تكوينه باستخدام كتالوجات عناصر مخصصة، وتسعير، وقيود الوظائف، والمواقع. تُعرف المتاجر في data/shops.lua ويمكن إرفاقه ببائعي الشخصيات، مواقع العلامات، أو تفعيله برمجيًا.

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

نظام التخزين والحاويات المخصصة

التخزينات هي حاويات تخزين دائمة يمكن للاعبين الوصول إليها في مواقع محددة. يدعم ox_inventory التخزينات الشخصية المرتبطة بمعرف اللاعب، والتخزينات المشتركة التي يمكن لأي شخص الوصول إليها، والتخزينات المقيدة بالوظائف مثل غرف أدلة الشرطة وتخزين المستشفى.

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

• تحقق دائمًا من جانب الخادم. لا تثق أبداً بفحوصات الجرد على جانب العميل. استخدم تصديرات الخادم مثل GetItemCount و RemoveItem لكل منطق اللعبة الحرج.
• استخدم البيانات الوصفية باعتدال. بينما البيانات الوصفية قوية، فإن تخزين بيانات زائدة على كل عنصر يزيد من حجم قاعدة البيانات وحركة الشبكة. خزّن فقط ما تحتاجه فعليًا.
• التعامل مع الجرد الكامل بسلاسة. تحقق دائمًا من قيمة الإرجاع لـ AddItem وقم بتوفير ردود واضحة للاعب عندما يكون مخزونه ممتلئًا.
• استخدم تدهور العنصر للواقعية. خاصية التدهور تخلق مصارف طبيعية للعناصر تحافظ على توازن اقتصادك. عيّن أوقات تحلل مناسبة للسلع القابلة للتلف والأدوات.
• استفد من نظام الصنع المدمج. بدلاً من بناء منطق التصنيع الخاص بك، استخدم طاولات تصنيع ox_inventory التي تتعامل مع الفحوصات والإزالة والإنشاء تلقائيًا.
• حافظ على تناسق صور العناصر. ضع جميع صور العناصر في web/images/ مع أسماء ملفات مطابقة. استخدم ملفات PNG بحجم 100x100 مع خلفيات شفافة لأفضل مظهر نظيف.