Player Progression Settings

This page covers the player progression system including levels, experience points, and how to configure the leveling system in Koja-Crafting.

🔧 Configuration Options

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

-- ════════════════════════════════════════════════════════════════════════════════════
--  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

1

New players

New players start with configured level and exp.

2

Crafting items

Crafting items grants experience points (defined per item).

3

Reaching XP threshold

Reaching the XP threshold automatically levels up the player.

4

Higher levels

Higher levels unlock new crafting recipes (items have requiredLevel).

5

Progress is saved

Progress is saved to the database automatically.

⭐ Starting Values

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

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

Boosted Start (Players start at level 2):

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

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

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

📈 Level Configuration

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

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:

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

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:

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

Tiered Crafting System

Create progression tiers for organized gameplay:

-- 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)

• 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

XP not being granted

• Check if item has exp field defined

• Verify player crafting completes successfully

• Check database connection

• Enable Config.Debug = true to see XP events

Player not leveling up

• 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 = '...'

Starting values not applying

• 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

Admin command not working

• See Admin Permissions for setup

• Verify player has admin group

• Check console for permission errors

• Use correct syntax: /addexp [id] [amount]

📚 Related Settings

• For admin command configuration, see Admin Permissions

• For item configuration, see Crafting Stations

• For database setup, see Server Settings

• For commands list, see Commands