-- Register a mining skill
exports.dime_skills:addSkill({
    name = 'mining',
    label = 'Mining',
    description = 'Extract valuable minerals from the earth.',
    category = 'Jobs',
    icon = 'pickaxe',
    levels = {
        lvlMulti = { default = 2.0, [1] = 1.5, [2] = 1.75 },
        lvlMax = 50
    },
    rewardMax = 25,
    reduceMax = 10,
    job = 'miner'
})

-- Register with level-up event
exports.dime_skills:addSkill({
    name = 'fishing',
    label = 'Fishing',
    description = 'Master the art of fishing.',
    category = 'Character',
    icon = 'fish',
    levels = {
        lvlMulti = { default = 1.5 },
        lvlMax = 30
    },
    action = {
        event = 'fishing:levelUp'  -- Triggered on level up
    },
    rewardMax = 30,
    reduceMax = 15
})

Database Integration

When a skill is registered:

Creates a new database column in player_skills table
Initializes all existing players with default values (level 1, 0 XP)
Syncs configuration to all clients

Best Practices

Register skills in server.lua or resource initialization
Use unique, descriptive names (no spaces)
Set appropriate rewardMax values to prevent exploits
Test XP progression before production use

Usage

Use this export to:

Create job-specific skills
Add server-specific skills
Extend the skill system
Create custom progression systems

grabSkills

Deprecated: Use getSkills() instead. This export will be removed in v2.0.0.

Returns all skills for a player.

exports.dime_skills:grabSkills(src)

Parameters

src (number): Player's server ID

Returns

table | nil: Table of all player skills or nil if player not found

Return Structure:

{
    ['skill_name'] = {
        level = 5,
        xp = 234.5,
        statlevel = 25.0,
        lastupdated = 1234567890
    },
    -- ... more skills
}

Example

-- Get all skills for a player
local skills = exports.dime_skills:grabSkills(source)

if skills then
    for skillName, skillData in pairs(skills) do
        print(skillName, skillData.level, skillData.xp)
    end
else
    print('Player not found or not loaded')
end

-- Send to client for custom UI
RegisterNetEvent('myresource:requestSkills', function()
    local skills = exports.dime_skills:grabSkills(source)
    TriggerClientEvent('myresource:receiveSkills', source, skills)
end)

Usage

Use this export to:

Display player skills in admin panels
Create leaderboards
Export player data
Check multiple skills at once

grabSkill

Deprecated: Use getSkill() instead. This export will be removed in v2.0.0.

Returns data for a specific player skill.

exports.dime_skills:grabSkill(src, skill)

Parameters

src (number): Player's server ID
skill (string): Skill name/identifier

Returns

table | nil: Skill data object or nil if not found

Return Structure:

{
    level = 5,
    xp = 234.5,
    statlevel = 25.0,
    lastupdated = 1234567890
}

Example

-- Check player's crafting level
local craftingSkill = exports.dime_skills:grabSkill(source, 'crafting')

if craftingSkill and craftingSkill.level >= 10 then
    -- Allow access to advanced crafting
    TriggerClientEvent('crafting:openAdvanced', source)
else
    TriggerClientEvent('ox_lib:notify', source, {
        type = 'error',
        description = 'Requires Crafting Level 10'
    })
end

-- Usage in callbacks
lib.callback.register('myresource:checkSkill', function(source, skillName, requiredLevel)
    local skill = exports.dime_skills:grabSkill(source, skillName)
    return skill and skill.level >= requiredLevel
end)

Usage

Use this export to:

Check skill requirements
Gate content behind skill levels
Validate player abilities
Create skill-based permissions

getSkillsByIdentifier

Retrieves skills for a player using their citizen ID (works offline).

exports.dime_skills:getSkillsByIdentifier(citizenID, callback)

Parameters

citizenID (string): Player's citizen ID/identifier
callback (function): Function called with results

Callback Parameters:

data (table): Array of skill objects

Data Structure:

{
    {
        name = 'crafting',
        visuals = { label = 'Engineering' },
        level = 5,
        xp = 450.0,
        percent = 75.0
    },
    -- ... more skills
}

Example

-- Get offline player skills
exports.dime_skills:getSkillsByIdentifier('ABC12345', function(skills)
    if skills and #skills > 0 then
        for _, skill in ipairs(skills) do
            print(skill.name, skill.level, skill.xp)
        end
    else
        print('No skills found for player')
    end
end)

-- Use in admin command
RegisterCommand('checkskills', function(source, args)
    local citizenID = args[1]
    
    exports.dime_skills:getSkillsByIdentifier(citizenID, function(skills)
        -- Send to admin's client
        TriggerClientEvent('admin:showPlayerSkills', source, citizenID, skills)
    end)
end, true)

-- Job application system
RegisterNetEvent('jobs:checkApplicant', function(applicantCID)
    exports.dime_skills:getSkillsByIdentifier(applicantCID, function(skills)
        -- Check if applicant meets requirements
        local qualifies = false
        for _, skill in ipairs(skills) do
            if skill.name == 'crafting' and skill.level >= 15 then
                qualifies = true
                break
            end
        end
        
        TriggerClientEvent('jobs:applicationResult', source, qualifies)
    end)
end)

Usage

Use this export for:

Admin tools (viewing offline players)
Job applications
Stat tracking systems
Leaderboards

This export queries the database, so use it sparingly. For online players, use grabSkill or grabSkills instead.

addEXP

Deprecated: Use addXP() instead (lowercase 'addXP'). This export will be removed in v2.0.0.

Adds XP to a player's skill (most commonly used export).

exports.dime_skills:addEXP(src, skill, amount, customMultiplier)

Parameters

src (number): Player's server ID
skill (string): Skill name/identifier
amount (number): XP amount to add
customMultiplier (number, optional): Custom multiplier (default: 1.0)

Returns

boolean: true if successful, false if failed

Example

-- Simple XP grant
exports.dime_skills:addEXP(source, 'mining', 10)

-- With custom multiplier (double XP event)
exports.dime_skills:addEXP(source, 'crafting', 15, 2.0)

-- In crafting system
RegisterNetEvent('crafting:itemCrafted', function(itemName)
    local xpReward = 20
    local success = exports.dime_skills:addEXP(source, 'crafting', xpReward)
    
    if success then
        print('Granted crafting XP')
    else
        print('Failed to grant XP')
    end
end)

-- Progressive XP based on difficulty
local function grantMiningXP(oreQuality)
    local xpAmounts = {
        ['copper'] = 5,
        ['iron'] = 10,
        ['gold'] = 20,
        ['diamond'] = 50
    }
    
    local xp = xpAmounts[oreQuality] or 5
    exports.dime_skills:addEXP(source, 'mining', xp)
end

Multiplier System

The final XP granted considers:

Base amount
Custom multiplier (parameter)
Bonus multiplier (from config)

final_xp = amount * customMultiplier * bonusMultiplier

Safety Checks

XP gains are capped at rewardMax from skill config unless disableSafetyCheck is enabled.

If XP exceeds rewardMax:

Warning logged (if Debug enabled)
Operation may be blocked
Helps detect exploit attempts

Level-Up Events

When a player levels up:

Client receives updated skill data
Skill notification triggered
Level-up event fired (if configured)
Multiple levels can be gained in one call

Usage

Use this export for:

Rewarding player actions
Job progression
Quest rewards
Activity rewards
Event bonuses

remoEXP

Deprecated: Use removeXP() instead. This export (and the typo) will be removed in v2.0.0.

Removes XP from a player's skill.

exports.dime_skills:remoEXP(src, skill, amount, customMultiplier)

Parameters

src (number): Player's server ID
skill (string): Skill name/identifier
amount (number): XP amount to remove
customMultiplier (number, optional): Custom multiplier (default: 1.0)

Returns

boolean: true if successful, false if failed

Example

-- Remove XP as penalty
exports.dime_skills:remoEXP(source, 'driving', 50)

-- Custom multiplier
exports.dime_skills:remoEXP(source, 'shooting', 25, 1.5)

-- Death penalty system
AddEventHandler('playerDied', function(playerId, killer)
    -- Lose XP on death
    exports.dime_skills:remoEXP(playerId, 'strength', 30)
    exports.dime_skills:remoEXP(playerId, 'shooting', 20)
end)

-- Failed action penalty
RegisterNetEvent('crafting:failed', function()
    -- Small XP loss on failed craft
    exports.dime_skills:remoEXP(source, 'crafting', 5)
end)

Behavior

XP can drop below 0, causing level loss
Multiple levels can be lost in one call
Level can't drop below 1
Client receives notification of XP loss

Safety Checks

XP losses are capped at reduceMax from skill config.

Usage

Use this export for:

Death penalties
Failed actions
Punishment systems
Skill decay
Balance adjustments

removeLevel

Removes entire levels from a skill (not just XP).

exports.dime_skills:removeLevel(src, skill, amount)

Parameters

src (number): Player's server ID
skill (string | table): Skill name or array of skill names
amount (number): Number of levels to remove

Returns

None

Example

-- Remove one level
exports.dime_skills:removeLevel(source, 'crafting', 1)

-- Remove multiple levels
exports.dime_skills:removeLevel(source, 'shooting', 3)

-- Remove level from multiple skills
exports.dime_skills:removeLevel(source, {'strength', 'stamina', 'shooting'}, 1)

-- Admin command
RegisterCommand('removeskilllevel', function(source, args)
    local targetId = tonumber(args[1])
    local skillName = args[2]
    local levels = tonumber(args[3]) or 1
    
    if targetId and skillName then
        exports.dime_skills:removeLevel(targetId, skillName, levels)
        print(('Removed %d level(s) from %s'):format(levels, skillName))
    end
end, true)

-- Punishment system
local function punishPlayer(playerId, severity)
    if severity == 'minor' then
        exports.dime_skills:removeLevel(playerId, 'driving', 1)
    elseif severity == 'major' then
        exports.dime_skills:removeLevel(playerId, {'driving', 'shooting', 'strength'}, 2)
    end
end

Behavior

Removes complete levels (not XP)
XP is reset to 0
Can't reduce level below 1
Supports single skill or multiple skills
No notifications sent (handled internally)

Usage

Use this export for:

Admin tools
Punishment systems
Skill resets
Game mechanics
Testing

For gradual XP loss, use remoEXP instead. This export is for immediate level reduction.

Usage Examples

Job Progression System

-- Complete job task and grant XP
RegisterNetEvent('jobs:taskCompleted', function(jobType, difficulty)
    local xpRewards = {
        easy = 10,
        medium = 25,
        hard = 50
    }
    
    local skillMap = {
        mechanic = 'crafting',
        miner = 'mining',
        cop = 'shooting'
    }
    
    local skill = skillMap[jobType]
    local xp = xpRewards[difficulty] or 10
    
    if skill then
        exports.dime_skills:addEXP(source, skill, xp)
    end
end)

Skill Requirements Gate

-- Check skill before allowing action
RegisterNetEvent('crafting:attemptAdvancedCraft', function(itemName)
    local craftingSkill = exports.dime_skills:grabSkill(source, 'crafting')
    
    if not craftingSkill then
        return TriggerClientEvent('ox_lib:notify', source, {
            type = 'error',
            description = 'Skill data not found'
        })
    end
    
    local requiredLevel = 15
    
    if craftingSkill.level >= requiredLevel then
        -- Allow crafting
        TriggerClientEvent('crafting:openAdvanced', source)
    else
        TriggerClientEvent('ox_lib:notify', source, {
            type = 'error',
            description = ('Requires Crafting Level %d (Current: %d)'):format(requiredLevel, craftingSkill.level)
        })
    end
end)

Leaderboard System

-- Create skill leaderboard
RegisterCommand('skilltop', function(source, args)
    local skillName = args[1] or 'crafting'
    
    MySQL.query('SELECT * FROM player_skills ORDER BY JSON_EXTRACT(`' .. skillName .. '`, "$.level") DESC, JSON_EXTRACT(`' .. skillName .. '`, "$.xp") DESC LIMIT 10', {}, function(results)
        local leaderboard = {}
        
        for i, row in ipairs(results) do
            local skillData = json.decode(row[skillName])
            table.insert(leaderboard, {
                rank = i,
                citizenid = row.citizenID,
                level = skillData.level,
                xp = skillData.xp
            })
        end
        
        TriggerClientEvent('leaderboard:show', source, skillName, leaderboard)
    end)
end)

Custom Skill Registration

-- Register custom skills on resource start
CreateThread(function()
    Wait(5000) -- Wait for dime_skills to initialize
    
    -- Hacking skill
    exports.dime_skills:addSkill({
        name = 'hacking',
        label = 'Hacking',
        description = 'Bypass security systems and access restricted data.',
        category = 'Illegal',
        icon = 'laptop-code',
        iconColor = '#10B981',
        levels = {
            lvlMulti = { default = 3.0, [1] = 1.5, [2] = 2.0 },
            lvlMax = 40
        },
        rewardMax = 30,
        reduceMax = 15,
        action = {
            event = 'hacking:levelUp'
        }
    })
    
    -- Cooking skill
    exports.dime_skills:addSkill({
        name = 'cooking',
        label = 'Culinary Arts',
        description = 'Prepare delicious meals and beverages.',
        category = 'Character',
        icon = 'utensils',
        levels = {
            lvlMulti = { default = 2.0 },
            lvlMax = 30
        },
        rewardMax = 25,
        reduceMax = 10,
        job = 'chef'
    })
end)

Best Practices

Performance

Cache Skill Data: Don't call exports in loops
Batch Operations: Group XP grants when possible
Use Appropriate Export: Online vs offline functions
Validate Input: Check parameters before calling

Security

Server-Side Only: Never trust client for XP changes
Validate Amounts: Check XP amounts are reasonable
Use Safety Checks: Keep disableSafetyCheck false
Log Suspicious Activity: Monitor large XP grants

User Experience

Meaningful Amounts: Grant appropriate XP for actions
Clear Feedback: Ensure players see notifications
Balanced Progression: Test XP rates thoroughly
Fair Penalties: Don't be too harsh with XP loss

Client Exports - Client-side functions
Server Events - Server events
Custom Skills Guide - Creating skills

Server Exports

getSkillTreePoints

getSkillTreePointsBreakdown

registerNodeEffect

triggerNodeEffect

isSkillTreeEnabled

getContributingSkills

setGlobalMultiplier

getGlobalMultiplier

resetGlobalMultiplier

getSkills

getSkill

addXP

removeXP

bulkAddXP

setLevel

View Complete Data Structure

On this page