> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/new/crafting/configuration/player-progression-settings.md).

# Player Progression Settings

## 🔧 Configuration Options

All progression settings are located in `shared/config.lua` under the **PLAYER PROGRESSION** section.

```lua
-- ════════════════════════════════════════════════════════════════════════════════════
--  PLAYER PROGRESSION
-- ════════════════════════════════════════════════════════════════════════════════════

Config.StartingValues = {
    level = 1,
    exp = 0
}

Config.Levels = {
    { level = 1, expToNext = 100 },
    { level = 2, expToNext = 200 },
    { level = 3, expToNext = 300 },
    { level = 4, expToNext = 400 },
    { level = 5, expToNext = 500 }
}
```

## 📝 How Progression Works

### System Overview

{% stepper %}
{% step %}

### New players

New players start with configured `level` and `exp`.
{% endstep %}

{% step %}

### Crafting items

Crafting items grants experience points (defined per item).
{% endstep %}

{% step %}

### Reaching XP threshold

Reaching the XP threshold automatically levels up the player.
{% endstep %}

{% step %}

### Higher levels

Higher levels unlock new crafting recipes (items have `requiredLevel`).
{% endstep %}

{% step %}

### Progress is saved

Progress is saved to the database automatically.
{% endstep %}
{% endstepper %}

## ⭐ Starting Values

```lua
Config.StartingValues = {
    level = 1,
    exp = 0
}
```

Purpose: Define initial crafting level and experience for new players.

### Configuration Options

| Setting | Type   | Description                | Default |
| ------- | ------ | -------------------------- | ------- |
| `level` | Number | Starting crafting level    | `1`     |
| `exp`   | Number | Starting experience points | `0`     |

### Examples

Standard Start (Everyone begins at level 1):

```lua
Config.StartingValues = {
    level = 1,
    exp = 0
}
```

Boosted Start (Players start at level 2):

```lua
Config.StartingValues = {
    level = 2,
    exp = 0
}
```

VIP Start (Players start at level 3 with some XP):

```lua
Config.StartingValues = {
    level = 3,
    exp = 150
}
```

## 📈 Level Configuration

```lua
Config.Levels = {
    { level = 1, expToNext = 100 },
    { level = 2, expToNext = 200 },
    -- ... more levels
}
```

Purpose: Define XP requirements for each level and control progression curve.

### Structure Explanation

Each level entry contains:

* `level`: The current level number
* `expToNext`: Experience points needed to reach the NEXT level

### Example Calculation

```lua
Config.Levels = {
    { level = 1, expToNext = 100 }, -- Need 100 XP to reach level 2
    { level = 2, expToNext = 200 }, -- Need 200 more XP to reach level 3
    { level = 3, expToNext = 300 }, -- Need 300 more XP to reach level 4
    { level = 4, expToNext = 400 }, -- Need 400 more XP to reach level 5
    { level = 5, expToNext = 500 }  -- Max level (500 XP for potential level 6)
}
```

Total XP needed for each level:

* Level 1 → 2: `100 XP`
* Level 2 → 3: `200 XP` (total: 300 XP)
* Level 3 → 4: `300 XP` (total: 600 XP)
* Level 4 → 5: `400 XP` (total: 1000 XP)
* Level 5 → 6: `500 XP` (total: 1500 XP)

## 🎮 Item Experience Configuration

Experience is granted per item in the crafting configuration:

```lua
items = {
    {
        respname = 'bandage',
        name = 'Bandage',
        craftingTime = 20,
        requiredLevel = 1,
        exp = 10, -- XP gained when crafting completes
        -- ...
    }
}
```

### XP Balancing Guidelines

| Item Complexity | Crafting Time | Suggested XP | Level Requirement |
| --------------- | ------------- | ------------ | ----------------- |
| Basic           | 5-10s         | 5-15 XP      | Level 1           |
| Common          | 10-30s        | 15-30 XP     | Level 1-2         |
| Uncommon        | 30-60s        | 30-50 XP     | Level 2-3         |
| Rare            | 60-120s       | 50-80 XP     | Level 3-4         |
| Epic            | 120-300s      | 80-150 XP    | Level 4-5         |
| Legendary       | 300s+         | 150-300 XP   | Level 5+          |

### Example Configuration

```lua
items = {
    -- Basic Item (Low XP, Low Level)
    {
        respname = 'bandage',
        name = 'Bandage',
        craftingTime = 10,
        requiredLevel = 1,
        exp = 10,
        resources = {
            { name = 'cloth', amount = 2 }
        }
    },
    
    -- Advanced Item (Medium XP, Medium Level)
    {
        respname = 'lockpick',
        name = 'Lockpick',
        craftingTime = 30,
        requiredLevel = 2,
        exp = 35,
        resources = {
            { name = 'iron', amount = 3 },
            { name = 'scrapmetal', amount = 2 }
        }
    },
    
    -- High-End Item (High XP, High Level)
    {
        respname = 'armour',
        name = 'Bulletproof Vest',
        craftingTime = 120,
        requiredLevel = 5,
        exp = 150,
        resources = {
            { name = 'kevlar', amount = 5 },
            { name = 'steel', amount = 10 }
        }
    }
}
```

## 🔓 Level-Gated Content

### Basic Progression Lock

Items can be locked behind level requirements:

```lua
{
    respname = 'advanced_weapon',
    requiredLevel = 4, -- Player must be level 4+
    -- ...
}
```

### Tiered Crafting System

Create progression tiers for organized gameplay:

```lua
-- TIER 1: Beginner Items (Level 1-2)
items = {
    { respname = 'bandage', requiredLevel = 1, exp = 10 },
    { respname = 'lockpick', requiredLevel = 1, exp = 15 },
}

-- TIER 2: Intermediate Items (Level 2-3)
items = {
    { respname = 'medikit', requiredLevel = 2, exp = 35 },
    { respname = 'repair_kit', requiredLevel = 2, exp = 40 },
}

-- TIER 3: Advanced Items (Level 3-4)
items = {
    { respname = 'radio', requiredLevel = 3, exp = 65 },
    { respname = 'body_armour', requiredLevel = 3, exp = 80 },
}

-- TIER 4: Expert Items (Level 4-5)
items = {
    { respname = 'weapon_parts', requiredLevel = 4, exp = 120 },
    { respname = 'night_vision', requiredLevel = 5, exp = 200 },
}
```

## 🛠️ Admin Commands

### Add Experience Points

Grant XP to players using the admin command:

```
/addexp [playerID] [amount]
```

Examples:

```
/addexp 1 100        # Give 100 XP to player ID 1
/addexp 5 500        # Give 500 XP to player ID 5
```

Requirements:

* Must have admin permissions (see [Admin Permissions](broken://pages/45a75381560a402eb0697e8eda903edaa0c5f85c))
* Player must be online
* Amount must be a positive number

What happens:

* XP is added to player's current total
* Player may level up if XP threshold is reached
* Progress is saved to database immediately
* Player receives notification

## 🔍 Troubleshooting

<details>

<summary>XP not being granted</summary>

* Check if item has `exp` field defined
* Verify player crafting completes successfully
* Check database connection
* Enable `Config.Debug = true` to see XP events

</details>

<details>

<summary>Player not leveling up</summary>

* Verify `Config.Levels` is configured correctly
* Check current XP vs `expToNext` requirement
* Look for database errors in console
* Manually check database: `SELECT * FROM koja-crafting WHERE identifier = '...'`

</details>

<details>

<summary>Starting values not applying</summary>

* Ensure player is new (hasn't crafted before)
* Check if database entry exists (delete to reset)
* Verify `Config.StartingValues` in config.lua
* Restart resource after config changes

</details>

<details>

<summary>Admin command not working</summary>

* See [Admin Permissions](broken://pages/45a75381560a402eb0697e8eda903edaa0c5f85c) for setup
* Verify player has admin group
* Check console for permission errors
* Use correct syntax: `/addexp [id] [amount]`

</details>

## 📚 Related Settings

* For admin command configuration, see [Admin Permissions](broken://pages/45a75381560a402eb0697e8eda903edaa0c5f85c)
* For item configuration, see [Crafting Stations](broken://pages/4bbcf723e7cb8b7e86b7ff18adaa252950f832b1)
* For database setup, see [Server Settings](broken://pages/27642ea36c6140036d69396f37f446bea1ed0301)
* For commands list, see [Commands](broken://pages/e9796abb8c379f9a9e6e06f60d7f8d9a5896bbc4)