Skip to main content

Installation Steps

1

Install dependencies

Verify all dependencies below are started before this script in your server.cfg.

ox_lib

Download ox_lib (CommunityOx)

oxmysql

Download oxmysql (overextended)
2

Extract and place the resource

Extract the script from the zip file and place it into your resources folder (for example standalone or [projectx]).
3

Import the SQL

Import sql/install.sql into your database. This creates the player_xp table.
The script can also auto-add missing columns at runtime if the table already exists.
Legacy Pickle XP JSON data can migrate automatically when skill keys match entries in Config.Skills.
4

Configure the resource

Open config/config.lua and adjust the settings to your liking. See the configuration section below for details.
5

Add to server.cfg

Start projectx-xp after your framework, ox_lib, and oxmysql, and before any scripts that award XP:
6

Configure the bridge (Optional)

If you use projectx-bridge, set XPSystem to 'projectx' or 'auto'.
  • 'projectx' — always use projectx-xp
  • 'auto' — detects projectx-xp when the resource is started
See the Bridge Installation page for full setup.
7

Add the menu item (Optional)

If you enable UseItem, add the x_device item to your inventory so players can open the XP menu from an item.
Never grant XP from the client. All XP changes must go through server exports only.

Configuration

Key options in config/config.lua:

General Settings

string
default:"en"
Language locale used by the resource.
string
Your server framework (for example QBCore, Qbox, or ESX). Match this to your server setup.
string
Your inventory system. Required if you use UseItem with x_device.
string
default:"xp"
Chat command to open the XP menu (e.g. /xp).
string
default:"F7"
Keybind to open the XP menu.
boolean
When enabled, using the x_device item opens the XP menu. Add the item to your inventory if you enable this.

Notifications

string
Notification system: 'customui', 'ox', 'qb', or 'esx'.
number
Default notification display duration.
number
Display duration for XP buff notifications.
boolean
Notify the player when they gain XP.
boolean
Notify the player when they level up.
boolean
Notify the player when they reach a milestone.
boolean
Notify the player when an XP buff is applied or removed.

UI & Leaderboard

number
Maximum number of entries shown on the leaderboard.
string
Primary accent color for the XP UI.
number
Overall UI scale multiplier.
number
Scale multiplier for XP-related notifications.
boolean
Show milestone reward details in the UI.
boolean
Display level titles from each skill’s LevelTitles table.
table
Ordered list of skill IDs that controls how skills appear in the UI.

Skills (Config.Skills)

Each entry in Config.Skills is keyed by a skill ID (for example criminal) and supports: Milestone Rewards support types such as:
  • money — cash/bank reward
  • item — inventory item reward
  • export — custom export callback
Default skills: criminal, fishing, crafting, mechanic, delivery, farming, diving, mining

UI Build

The shipped UI lives in web/build. Only rebuild web/ if you edit the UI source: