Starter Items

Configure items that new characters receive automatically upon creation.

📦 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

1. Check item names - Must match exactly with inventory items

2. Check inventory script - Make sure it's started before multicharacter

3. Check console - Look for error messages

ID Cards Not Working

1. Verify your ID card script is running

2. Set customExport = true if using custom ID scripts

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