Starter Items | 0Resmon

📦 Configuration#

Located in config/config.lua:

Config.StarterItems = {
    { name = 'phone',          amount = 1 },
    { name = 'id_card',        amount = 1, customExport = false },
    { name = 'driver_license', amount = 1, customExport = false },
}

⚙️ Item Properties#

Property	Type	Required	Description
name	string	✅	Item name (must exist in your inventory)
amount	number	✅	Quantity to give
customExport	boolean	❌	Use custom ID card system

📝 Basic Items#

Add any item from your inventory:

Config.StarterItems = {
    { name = 'phone', amount = 1 },
    { name = 'bread', amount = 5 },
    { name = 'water', amount = 5 },
    { name = 'bandage', amount = 3 },
}

Make sure item names match exactly with your inventory item names!

🆔 ID Cards & Licenses#

Standard Metadata#

For id_card and driver_license, the script automatically adds player metadata:

{ name = 'id_card', amount = 1, customExport = false }

QBCore Metadata includes:

citizenid
firstname
lastname
birthdate
gender
nationality

Custom ID Card Systems#

If you use a custom ID card script, set customExport = true:

{ name = 'id_card', amount = 1, customExport = true }

Supported ID Card Scripts:

um-idcard
bl_idcard
qbx_idcard

When customExport = true, the script calls the appropriate export instead of adding the item directly.

🎮 Framework Differences#

QBCore / QBox#

Items are added with full metadata support:

-- Automatically generates metadata like:
{
    citizenid = 'ABC12345',
    firstname = 'John',
    lastname = 'Doe',
    birthdate = '1990-01-15',
    gender = 0,
    nationality = 'American'
}

ESX#

Basic item addition without advanced metadata:

-- Items are added without special metadata
-- ID cards work through your ID card script

📋 Complete Example#

Config.StarterItems = {
    -- Communication
    { name = 'phone', amount = 1 },
    { name = 'radio', amount = 1 },
    
    -- Identification
    { name = 'id_card', amount = 1, customExport = false },
    { name = 'driver_license', amount = 1, customExport = false },
    
    -- Survival
    { name = 'sandwich', amount = 5 },
    { name = 'water', amount = 5 },
    
    -- Money (if using physical cash item)
    { name = 'cash', amount = 500 },
    
    -- Tools
    { name = 'lockpick', amount = 2 },
}

🔧 Custom Item Logic#

For advanced item giving logic, modify server/functions.lua:

function GiveStarterItems(playerId)
    if not playerId then return end

    local xPlayer = Framework.GetPlayer(playerId)
    if not xPlayer then return end

    local starterItems = Config.StarterItems
    if not starterItems or #starterItems == 0 then
        return
    end

    for i = 1, #starterItems do
        local item = starterItems[i]
        local metadata = {}

        -- Custom logic for specific items
        if item.name == 'id_card' or item.name == 'driver_license' then
            -- Handle ID cards specially
            if item.customExport then
                CustomIDCard(playerId, item)
            else
                if Framework.GetFrameworkName() ~= 'es_extended' then
                    metadata = DefaultQBMetaData(xPlayer.PlayerData, item.name)
                end
            end
        end

        -- Add item with metadata
        if not item.customExport then
            Inventory.AddItem(playerId, item.name, item.amount, nil, metadata)
        end
    end
end

❓ Troubleshooting#

Items Not Being Added#

Check item names - Must match exactly with inventory items
Check inventory script - Make sure it's started before multicharacter
Check console - Look for error messages

ID Cards Not Working#

Verify your ID card script is running
Set customExport = true if using custom ID scripts
Check if the export exists in your ID card script

Amount Issues#

Some inventories have stack limits. If you're giving more than the stack limit, only the max stack will be added.