Player Progression Settings#

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

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#

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#

📚 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

Related pages#

• General Settings — This page covers the basic configuration options for Koja-Crafting that control debug mode, language, and player behavior.
• Server Settings — This page covers server-side configuration options including database management, crafting recovery, and shared table functionality.
• Images Settings — This page explains how to configure item images, add custom graphics, and manage image paths in Koja-Crafting.
• Admin Settings — This page covers admin permission configuration and available admin commands for managing Koja-Crafting.
• Interaction Settings — This page covers how players interact with crafting stations - either through key press or target system (ox_target,qb-target,).
• Crafting Queue Settings — This page covers the crafting queue system that manages distance checking, warnings, and crafting cancellation when players move away from stations.
• Configuration — back to the section overview