# Starter Items

### 📦 Configuration

Located in `config/config.lua`:

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

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

{% hint style="warning" %}
Make sure item names match exactly with your inventory item names!
{% endhint %}

***

### 🆔 ID Cards & Licenses

#### Standard Metadata

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

```lua
{ 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`:

```lua
{ 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:

```lua
-- 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:

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

***

### 📋 Complete Example

```lua
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`:

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