Skills System Guide

This guide explains how the skill system works in Dime Skills, including leveling mechanics, XP calculations, and progression systems.

Core Concepts

Skills

A skill represents a character's proficiency in a specific activity or discipline. Each skill has:

• Name: Unique identifier (e.g., crafting, driving)
• Label: Display name shown to players (e.g., "Engineering", "Motoring")
• Level: Current progression level (1 to max)
• XP: Experience points toward next level
• Category: Grouping for UI organization

Experience Points (XP)

XP is the currency of progression. Players earn XP by:

• Completing activities
• Crafting items
• Performing jobs
• Automatic progression (built-in skills)

XP accumulates until the player levels up, then wraps to the next level.

Levels

Levels represent mastery thresholds. Higher levels:

• Require more XP to reach
• May unlock new abilities
• Can be job-restricted
• Trigger level-up events

Leveling System

XP Requirements

The XP required to level up follows this formula:

required_xp = level * 100 * multiplier

Where multiplier is defined in the skill config:

levels = {
    lvlMulti = {
        default = 2.5,  -- Default for unlisted levels
        [1] = 1.5,      -- Level 1 → 2
        [2] = 2.0,      -- Level 2 → 3
        [3] = 2.5       -- Level 3 → 4
    },
    lvlMax = 30
}

Example Progression

For a skill with the above multipliers:

Level Caps

Each skill has a maximum level (lvlMax):

lvlMax = 30  -- Can't exceed level 30

When max level is reached:

• No more XP is gained
• Level stays at maximum
• Player is considered "mastered"

Multiple Level Gains

Players can gain multiple levels in a single XP grant:

-- Player at level 5 with 50 XP
-- Grant 3000 XP
exports.dime_skills:addEXP(source, 'mining', 3000)

-- Result: Player reaches level 7 or 8
-- Excess XP carries over to next level

Built-in Skills

Dime Skills includes several skills with automatic progression:

Strength

Progression: Automatic with melee combat

• Increases melee damage
• Progresses while fighting
• Affects punch/melee weapons
• Cooldown-based XP gain

Configuration:

Strength = {
    enabled = true,
    baseModifier = -0.35,
    levelMultiplier = 1.00,
    minModifier = 0.05,
    maxModifier = 2.0
}

How it works:

• Player engages in melee combat
• XP granted every X seconds (cooldown)
• Damage modifier increases with level

Driving

Progression: Automatic when driving fast

• Improves vehicle handling
• Progresses at high speeds
• Vehicle class restrictions apply
• Speed threshold required

Configuration:

Driving = {
    enabled = true,
    SpeedUnit = 'MPH',
    SpeedThreshold = 100,
    validVehicleClasses = {
        [0] = true,   -- Compacts
        [8] = true,   -- Motorcycles
        -- ...
    }
}

How it works:

• Player drives above threshold speed
• XP granted periodically
• Only valid vehicle classes count
• Affects vehicle performance

Stamina

Progression: Automatic while running/swimming

• Increases endurance
• Reduces stamina drain
• Extends running distance
• Affects swimming duration

Configuration:

Stamina = {
    enabled = true,
    xpGainMethod = "cooldown",
    action = {
        builtIn = true,
        cooldown = 30,
        xp = 10
    }
}

How it works:

• Player runs or swims
• XP granted on cooldown
• Native stamina bar improved
• Level affects max stamina

Shooting

Progression: Automatic with weapon usage

• Improves accuracy
• Increases damage
• Progresses when firing weapons
• Cooldown-based

How it works:

• Player fires weapons
• XP granted periodically
• Applies to all weapon types
• Level affects weapon stats

Diving

Progression: Automatic while underwater

• Extends oxygen capacity
• Improves underwater time
• Works with/without scuba gear
• Dynamic oxygen calculation

Configuration:

Diving = true

DivingToStamina = {
    enabled = true,
    stepsToSkip = 2
}

Oxygen Formula:

-- With scuba tank
oxygen = (diving_level * 1.5) + 60

-- Without tank
oxygen = (diving_level * 1.5) + 10

How it works:

• Player goes underwater
• XP granted on cooldown
• Oxygen capacity calculated
• Can also grant stamina XP

Custom Skills

Manual Progression

Skills without action.builtIn require manual XP grants:

['crafting'] = {
    visuals = { label = 'Engineering' },
    levels = {
        lvlMulti = { default = 3 },
        lvlMax = 30
    },
    rewardMax = 20,
    reduceMax = 20,
    -- No action.builtIn
}

Grant XP manually:

-- Server-side
exports.dime_skills:addEXP(source, 'crafting', 15)

-- Or via event from client
TriggerServerEvent('dime_skills:addXP', 'crafting', 15)

Job-Locked Skills

Restrict skills to specific jobs:

['weaponary'] = {
    -- ... config
    job = 'mechanic'  -- Only mechanics can use
}

Behavior:

• Hidden from UI for unauthorized players
• Can't gain XP without the job
• Automatically shown when job is acquired
• Useful for job-specific progression

XP Degradation

Skills can lose XP over time for added realism:

levels = {
    lvlMulti = { default = 2.0 },
    lvlMax = 30,
    degrade = {
        enabled = true,
        time = 12,      -- Every 12 hours
        amount = 250    -- Lose 250 XP
    }
}

Degradation Modes

Online Only (deductOnline = true):

• XP only deducted while player is online
• Inactive players don't lose XP
• Encourages regular play

Always (deductOnline = false):

• XP deducted even when offline
• Based on real time
• More realistic decay

Preventing Degradation

Certain skills (like character stats) benefit from degradation:

• Stamina: Encourages regular exercise
• Strength: Muscle atrophy simulation
• Shooting: Skills rust over time

Other skills shouldn't degrade:

• Crafting: Knowledge retention
• Driving: Learned ability
• Cooking: Permanent skill

Multiplier System

XP gains can be modified by multipliers:

Bonus Multipliers

Set in skill config:

bonusmultiplier = 1.5  -- 50% bonus XP

Custom Multipliers

Passed when granting XP:

-- Double XP event
exports.dime_skills:addEXP(source, 'mining', 10, 2.0)

Final Calculation

final_xp = base_amount * custom_multiplier * bonus_multiplier

Example:

base_amount = 10
custom_multiplier = 2.0  -- Event bonus
bonus_multiplier = 1.5   -- Skill config

final_xp = 10 * 2.0 * 1.5 = 30 XP

Safety Limits

Reward Maximum

Prevents exploit attempts:

rewardMax = 20  -- Max XP per operation

If XP exceeds limit:

• Warning logged (Debug mode)
• Operation may be blocked
• Helps detect cheating

Reduce Maximum

Caps XP loss:

reduceMax = 20  -- Max XP loss per operation

Prevents:

• Excessive penalties
• Griefing mechanics
• Balance issues

Level-Up Events

Trigger custom logic when players level up:

action = {
    event = 'myresource:levelUp'
}

Server-side handler:

RegisterNetEvent('myresource:levelUp', function()
    local _source = source
    
    -- Grant rewards
    -- Unlock features
    -- Send notifications
end)

Use cases:

• Unlock crafting recipes
• Grant permissions
• Give rewards
• Trigger cutscenes

Skill Categories

Organize skills in the UI:

visuals = {
    category = 'Crafting'  -- Groups with other Crafting skills
}

Common categories:

• Character: Personal attributes (strength, stamina)
• Crafting: Creation skills (engineering, weaponary)
• Jobs: Job-specific skills (lumberjacking)
• Illegal: Criminal skills (lockpicking, hacking)

Best Practices

Balancing Progression

1. Start Slow: Early levels should be quick
2. Increase Gradually: Use level-specific multipliers
3. Test Thoroughly: Playtest XP rates
4. Listen to Feedback: Adjust based on player experience

XP Amounts

Guidelines for XP rewards:

• Simple Actions: 5-10 XP
• Medium Tasks: 15-25 XP
• Complex Activities: 30-50 XP
• Major Achievements: 75-100 XP

Adjust based on:

• Action frequency
• Difficulty
• Time investment
• Reward multipliers

Level Caps

Choose appropriate max levels:

• Character Skills: 20-50 (long-term progression)
• Job Skills: 30-40 (role mastery)
• Mini-game Skills: 10-20 (quick progression)

Degradation Settings

If using degradation:

• Time: 168+ hours (1 week+)
• Amount: 5-10% of level XP
• Skills: Only physical/practice skills

Common Patterns

Difficulty-Based XP

local xpByDifficulty = {
    easy = 10,
    medium = 25,
    hard = 50,
    expert = 100
}

local xp = xpByDifficulty[difficulty]
exports.dime_skills:addEXP(source, skill, xp)

Progressive Rewards

local function calculateXP(playerLevel, taskLevel)
    local difference = taskLevel - playerLevel
    local base = 20
    
    if difference > 0 then
        -- Harder task = more XP
        return base * (1 + (difference * 0.1))
    else
        -- Easier task = less XP
        return base * math.max(0.5, 1 - (math.abs(difference) * 0.1))
    end
end

Milestone Bonuses

-- Bonus XP at certain levels
RegisterNetEvent('dime_skills:skillNotify', function(data)
    if data.newLevel > data.oldLevel then
        local milestones = {[10] = 100, [25] = 250, [50] = 500}
        local bonus = milestones[data.newLevel]
        
        if bonus then
            TriggerServerEvent('skills:milestoneBonus', data.skillName, bonus)
        end
    end
end)

Related

• Configuration - Config all settings
• Custom Skills Guide - Create skills
• Server Exports - API reference