Exports

Server Exports

AddXP

Awards XP to a player for a skill. Active XP buffs are applied using:

floor((baseXp + flatBonusTotal) * multiplierTotal)

local ok, result = exports['projectx-xp']:AddXP(source, skillId, amount)

number

required

Player server ID

string

required

Skill ID from Config.Skills (e.g. 'criminal')

number

required

Base XP to award before buffs

Returns

ok (boolean) — true on success, false on failure
result (table | string)
- On success (table):
  - skill (string) — skill ID
  - amount (number) — XP awarded after buffs
  - xp (number) — current XP toward the next level
  - totalXp (number) — lifetime XP for the skill
  - level (number) — current level
  - previousLevel (number) — level before this award
  - leveledUp (boolean) — whether the player leveled up
  - milestones (table) — milestones reached from this award (if any)
- On failure (string), common values include:
  - 'invalid_player'
  - 'invalid_skill'
  - 'invalid_amount'
  - 'max_level'

Example

local ok, result = exports['projectx-xp']:AddXP(source, 'criminal', 50)
if ok then
    print(('Awarded %s XP — now level %s'):format(result.amount, result.level))
else
    print('AddXP failed:', result)
end

AddXPRaw

Awards XP while ignoring active XP buffs (no multiplier or flat bonus applied).

local ok, result = exports['projectx-xp']:AddXPRaw(source, skillId, amount)

number

required

Player server ID

string

required

Skill ID from Config.Skills

number

required

Exact XP to award

Returns Same shape as AddXP.

RemoveXP

Removes XP from a player for a skill.

local ok, result = exports['projectx-xp']:RemoveXP(source, skillId, amount)

number

required

Player server ID

string

required

Skill ID from Config.Skills

number

required

XP to remove

Returns

ok (boolean)
result (table | string) — updated skill state on success, or an error string on failure

SetLevel

Sets a player’s level for a skill directly.

SetLevel does not re-grant milestone rewards for levels the player skips or is set to.

local ok, result = exports['projectx-xp']:SetLevel(source, skillId, level)

number

required

Player server ID

string

required

Skill ID from Config.Skills

number

required

Target level (clamped to the skill’s MaxLevel)

Returns

ok (boolean)
result (table | string) — updated skill state on success, or an error string on failure

GetSkill

Returns a single skill record for a player.

local skill = exports['projectx-xp']:GetSkill(source, skillId)

number

required

Player server ID

string

required

Skill ID from Config.Skills

Returns

table or nil — skill data (level, xp, totalXp, etc.)

GetSkills

Returns all skill records for a player.

local skills = exports['projectx-xp']:GetSkills(source)

number

required

Player server ID

Returns

table — map of skill ID → skill data

GetLevel

Returns the player’s current level for a skill.

local level = exports['projectx-xp']:GetLevel(source, skillId)

number

required

Player server ID

string

required

Skill ID from Config.Skills

Returns

number — current level (typically 0 if missing)

GetTotalXp

Returns the player’s total (lifetime) XP for a skill.

local totalXp = exports['projectx-xp']:GetTotalXp(source, skillId)

number

required

Player server ID

string

required

Skill ID from Config.Skills

Returns

number — total XP

GetSkillIds

Returns the configured skill IDs.

local skillIds = exports['projectx-xp']:GetSkillIds()

Returns

table — list of skill ID strings

OpenMenu

Opens the XP menu for a player from the server.

exports['projectx-xp']:OpenMenu(source)

number

required

Player server ID

SyncClient

Forces a client sync of the player’s XP data.

exports['projectx-xp']:SyncClient(source)

number

required

Player server ID

AddXpBuff

Adds a temporary XP buff. Multiple buffs stack. Award formula while buffs are active:

floor((baseXp + flatBonusTotal) * multiplierTotal)

local ok, result = exports['projectx-xp']:AddXpBuff(source, options)

number

required

Player server ID

table

required

Buff options table

string

Skill ID to apply the buff to, or a value that targets all skills depending on your config

number

Multiplier contribution (e.g. 1.5 for +50%)

number

Flat XP added before the multiplier is applied

number

Buff duration in seconds

string

Display label shown in notifications / UI

string

Optional unique buff ID (useful for targeted removal)

boolean

Whether to notify the player when the buff is applied

Example

exports['projectx-xp']:AddXpBuff(source, {
    skill = 'criminal',
    multiplier = 1.5,
    flatBonus = 10,
    duration = 300,
    label = 'Heist Boost',
    id = 'heist_boost',
    notify = true,
})

RemoveXpBuff

Removes an active XP buff by ID (or matching options, depending on usage).

local ok = exports['projectx-xp']:RemoveXpBuff(source, buffId)

number

required

Player server ID

string

required

Buff ID previously passed to AddXpBuff

Returns

boolean — whether a buff was removed

GetXpBuffs

Returns active XP buffs for a player.

local buffs = exports['projectx-xp']:GetXpBuffs(source, skillId)

number

required

Player server ID

string

Optional skill filter

Returns

table — list of active buffs

GetXpMultiplier

Returns the combined XP multiplier (and related totals) currently applied for a skill.

local multiplier = exports['projectx-xp']:GetXpMultiplier(source, skillId)

number

required

Player server ID

string

required

Skill ID from Config.Skills

Returns

number — combined multiplier total used by AddXP

Client Exports

OpenMenu

Opens the XP menu on the local client.

exports['projectx-xp']:OpenMenu()

IsMenuOpen

Returns whether the XP menu is currently open.

local open = exports['projectx-xp']:IsMenuOpen()

Returns

boolean

RefreshMenu

Refreshes the XP menu UI if it is open.

exports['projectx-xp']:RefreshMenu()

GetXpBuffs

Returns active XP buffs known to the client.

local buffs = exports['projectx-xp']:GetXpBuffs(skillId)

string

Optional skill filter

Returns

table — list of active buffs

Bridge Integration

When XPSystem is set to 'projectx' (or 'auto' and projectx-xp is running), Project X scripts can award and read XP through the bridge:

exports['projectx-bridge']:AddExperience(source, 'criminal', 25)
exports['projectx-bridge']:GetLevel(source, 'criminal')

See Bridge Installation for XPSystem options.

Example: Robbery / Job Award

-- Server-side only
local ok, result = exports['projectx-xp']:AddXP(source, 'criminal', 50)
if ok and result.leveledUp then
    print(('Player reached criminal level %s'):format(result.level))
end

Do not call AddXP (or any XP-mutating export) from client scripts. Award XP on the server only.

Getting Started

Project X Bridge

Paid Resources

Free Resources

Server Exports

AddXP

AddXPRaw

RemoveXP

SetLevel

GetSkill

GetSkills

GetLevel

GetTotalXp

GetSkillIds

OpenMenu

SyncClient

AddXpBuff

RemoveXpBuff

GetXpBuffs

GetXpMultiplier

Client Exports

OpenMenu

IsMenuOpen

RefreshMenu

GetXpBuffs

Bridge Integration

Example: Robbery / Job Award