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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.0resmon.org/0resmon/0r-resources/0r-multicharacter-v3/configuration/starter-items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.