[ABANDONED][ESX][QB]xperience

FiveM Releases
, , , , ,
1

xperience | 经验系统

XP Ranking System for FiveM | FiveM 经验排名系统

NOTE:The original author no longer maintains it, so I have taken over.

Features

  • Designed to emulate the native GTA:O system
  • Saves and loads players XP / rank
  • Add / remove XP from your own script / job
  • Allows you listen for rank changes to reward players
  • Fully customisable UI
  • Integrated leaderboard
  • Increasing XP

Demo Image 1

Rank Up

Demo Image 2

Install

  • Download and extract the package: GitHub - wusheng666/xperience: FiveM的XP排名系统
    Select an option:

  • Option 1 - If you want to use xperience as a standalone resource then import xperience_standalone.sql only

  • Option 2 - If using ESX with Config.UseESX set to true then import xperience_esx.sql only. This adds the xp and rank columns to the users table

  • Option 3 - If using QBCore with Config.UseQBCore set to true then there’s no need to import any sql files as the xp and rank are saved to the player’s metadata - see QBCore Integration

then:

  • Drop the xperience directory into you resources directory

  • Add ensure xperience to your server.cfg file

By default this resource uses oxmysql, but if you don’t want to use / install it then you can use mysql-async by following these instructions:

  • Uncomment the '@mysql-async/lib/MySQL.lua', line in fxmanifest.lua and comment out the '@oxmysql/lib/MySQL.lua' line

Transitioning from esx_xp

If you previously used esx_xp and are still using es_extended then do the following to make your current stored xp / rank data compatible with xperience

  • Rename the rp_xp column in the users table to xp

  • Rename the rp_rank column in the users table to rank

  • Set Config.UseESX to true

  • Usage

Client Side

Client Exports

Give XP to player

exports.xperience:AddXP(xp --[[ integer ]])

Take XP from player

exports.xperience:RemoveXP(xp --[[ integer ]])

Set player’s XP

exports.xperience:SetXP(xp --[[ integer ]])

Set player’s rank

exports.xperience:SetRank(rank --[[ integer ]])

Get player’s XP

exports.xperience:GetXP()

Get player’s rank

exports.xperience:GetRank()

Get XP required to rank up

exports.xperience:GetXPToNextRank()

Get XP required to reach defined rank

exports.xperience:GetXPToRank(rank --[[ integer ]])

Client Events

Listen for rank up event on the client

AddEventHandler("xperience:client:rankUp", function(newRank, previousRank, player)
    -- do something when player ranks up
end)

Listen for rank down event on the client

AddEventHandler("xperience:client:rankDown", function(newRank, previousRank, player)
    -- do something when player ranks down
end)

Server Side

Server Exports

Get player’s XP

exports.xperience:GetPlayerXP(playerId --[[ integer ]])

Get player’s rank

exports.xperience:GetPlayerRank(playerId --[[ integer ]])

Get player’s required XP to rank up

exports.xperience:GetPlayerXPToNextRank(playerId --[[ integer ]])

Get player’s required XP to reach defined rank

exports.xperience:GetPlayerXPToRank(playerId --[[ integer ]], rank --[[ integer ]])

Server Triggers

TriggerClientEvent('xperience:client:addXP', playerId --[[ integer ]], xp --[[ integer ]])

TriggerClientEvent('xperience:client:removeXP', playerId --[[ integer ]], xp --[[ integer ]])

TriggerClientEvent('xperience:client:setXP', playerId --[[ integer ]], xp --[[ integer ]])

TriggerClientEvent('xperience:client:setRank', playerId --[[ integer ]], rank --[[ integer ]])

Server Events

RegisterNetEvent('xperience:server:rankUp', function(newRank, previousRank)
    -- do something when player ranks up
end)

RegisterNetEvent('xperience:server:rankDown', function(newRank, previousRank)
    -- do something when player ranks down
end)

Rank Actions

You can define callbacks on each rank by using the Action function.

The function will be called both when the player reaches the rank and drops to the rank.

You can check whether the player reached or dropped to the new rank by utilising the rankUp parameter.

Config.Ranks = {
    [1] = { XP = 0 },
    [2] = {
        XP = 800, -- The XP required to reach this rank
        Action = function(rankUp, prevRank, player)
            -- rankUp: boolean      - whether the player reached or dropped to this rank
            -- prevRank: number     - the player's previous rank
            -- player: integer      - The current player            
        end
    },
    [3] = { XP = 2100 },
    [4] = { XP = 3800 },
    ...
}

QBCore Integration

If Config.UseQBCore is set to true then the player’s xp and rank are stored in their metadata. The metadata is saved whenever a player’s xp / rank changes.

Client


local PlayerData = QBCore.Functions.GetPlayerData()

local xp = PlayerData.metadata.xp

local rank = PlayerData.metadata.rank

Server


local Player = QBCore.Functions.GetPlayer(src)

local xp = Player.PlayerData.metadata.xp

local rank = Player.PlayerData.metadata.rank

ESX Integration

Server


local xPlayer = ESX.GetPlayerById(src)

local xp = xPlayer.get('xp')

local rank = xPlayer.get('rank')

Commands


-- Set the theme

/setXPTheme [theme]

Admin Commands

These require ace permissions: e.g. add_ace group.admin command.addXP allow


-- Award XP to player

/addXP [playerId] [xp]

-- Deduct XP from player

/removeXP [playerId] [xp]

-- Set a player's XP

/setXP [playerId] [xp]

-- Set a player's rank

/setRank [playerId] [rank]
4 Likes
2

i press Z but never show anything

3

I will fix him.

1 Like
4

Could you send me your config.lua and the framework you’re using?

5

esx legacy


Config.Debug        = true     -- Prints debug info to the console

Config.Timeout      = 5000      -- Sets the time in ms that the XP bar is displayed before fading out
Config.UIKey        = 'z'       -- The key that toggles the UI - default is "z"
Config.Theme        = 'native'  -- Set the default theme

Config.Themes = {
    native = {
        segments = 20,  -- Sets the number of segments the XP bar has. Native = 10, Max = 20
        width = 532     -- Sets the width of the XP bar in px
    },

    hitman = {
        segments = 80,
        width = 800
    },
    
    hexagon = {
        segments = 16,
        width = 400
    },
}

Config.UseQBCore    = false
Config.UseESX       = true

Config.ESXIdentifierColumn = 'identifier'
6

Download the latest version to try it out, and remember to import the database.

7

What are the newest changes? i have a very older version but works great

8

Please tell me your current version number

9

i dont know why still not show anything if press Z . haha . no error in console . i think because this line

    for _, id in pairs(GetPlayerIdentifiers(src)) do
        if string.sub(id, 1, string.len('license:')) == 'license:' then
            if Config.UseESX and Config.ESXIdentifierColumn == 'license' then
                return id
            end

            return string.sub(id, 9, string.len(id))
        end
    end 
    
    return false
end```
10

i change to this . now ok

    if Config.UseESX then
        local xPlayer = ESX.GetPlayerFromId(src)
        if xPlayer then
            return xPlayer.identifier --  return steam:xxxx
        end
    end

    return false
end```
11

Okay, I’ll sync him today.

12

Okay, I’ll sync him today.

13

Please tell me your current version number

14 
"version": "0.4.0",
"updateLog": [
    "Unified framework configuration with a single Config.Framework option",
    "Fixed AddXP function to properly calculate cumulative XP values",
    "Added max rank protection to prevent nil errors",
    "Improved identifier retrieval for all framework modes",
    "Fixed Load function timeout issues with default value handling",
    "Enhanced Save function with proper INSERT/UPSERT logic",
    "Resolved admin command offline detection for QBCore/Standalone modes"
]