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

New players

New players start with configured level and exp.

Crafting items

Crafting items grants experience points (defined per item).

Reaching XP threshold

Reaching the XP threshold automatically levels up the player.

Higher levels

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

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]

For admin command configuration, see Admin Permissions
For item configuration, see Crafting Stations
For database setup, see Server Settings
For commands list, see Commands

PreviousImages Settings NextAdmin Settings

Last updated 6 days ago