Exports

This page documents the public integration surface for ARS Multicharacter. Use these entries when another resource needs to read or update character slot counts, process Tebex-style slot purchases, or return a player to the selector.

Server Exports

Only call server exports from server-side scripts.

setPlayerSlots

Sets the character slot count for a Rockstar license. This creates or updates ars_multicharacter_slots.

---@param license string Rockstar license identifier
---@param slots number Desired slot count, minimum 1
---@return boolean true on success, false on invalid input
local success = exports['ars_multicharacter']:setPlayerSlots('license:12345', 5)

Example:

local license = GetPlayerIdentifierByType(source, 'license')
local ok = exports['ars_multicharacter']:setPlayerSlots(license, 6)

if ok then
    print('Character slots updated')
end

getPlayerSlots

Returns the effective character slot count for a Rockstar license. Invalid or empty input falls back to Config.MaxCharacters.

---@param license string Rockstar license identifier
---@return number Effective slot count
local slots = exports['ars_multicharacter']:getPlayerSlots('license:12345')

Example:

local license = GetPlayerIdentifierByType(source, 'license')
local maxSlots = exports['ars_multicharacter']:getPlayerSlots(license)

print(('Player has %d character slots'):format(maxSlots))

ProcessSlotPurchase

Processes a Tebex-style slot purchase by storing the transaction ID as a redeemable slot code in ars_multicharacter_auth_codes.

---@param transactionId string Tebex transaction ID
---@param slotCount number Number of slots to grant; defaults to Config.MaxCharacters when omitted
---@return boolean true on success or duplicate transaction, false on error
local success = exports['ars_multicharacter']:ProcessSlotPurchase('TXN_ABC123', 5)

Example:

local transactionId = 'TXN_ABC123'
local slots = 5
local success = exports['ars_multicharacter']:ProcessSlotPurchase(transactionId, slots)

if success then
    print(('Tebex purchase stored: txn=%s slots=%d'):format(transactionId, slots))
end

The player redeems the transaction ID through the selector or /redeemcharslot <code>. Redeeming a code adds its slot value to the player’s current total.

AddCharacterXp

Adds XP to a player’s currently logged-in character. The system automatically calculates level-ups, fires a notification, and emits the ars_multicharacter:server:levelUp event. Server-side only — there is no client-triggerable event to prevent XP spoofing.

---@param source number Player server ID
---@param amount number XP amount to add (can be negative)
---@return table|false {level, xp, leveledUp, citizenid} on success, false on failure
local result = exports['ars_multicharacter']:AddCharacterXp(source, 50)

Example:

-- Reward 50 XP for completing a mission (server-side only)
local result = exports['ars_multicharacter']:AddCharacterXp(source, 50)

if result and result.leveledUp then
    print(('Player leveled up to %d!'):format(result.level))
end

Requires Config.CharacterLevels.enabled = true.

RemoveCharacterXp

Removes XP from a player’s currently logged-in character. XP is clamped to zero — it never goes negative and the level is not reduced. Server-side only.

---@param source number Player server ID
---@param amount number XP amount to remove (must be positive)
---@return table|false {level, xp, citizenid} on success, false on failure
local result = exports['ars_multicharacter']:RemoveCharacterXp(source, 50)

Example:

-- Penalty: remove 50 XP (server-side only)
local result = exports['ars_multicharacter']:RemoveCharacterXp(source, 50)

if result then
    print(('XP reduced to %d'):format(result.xp))
end

Requires Config.CharacterLevels.enabled = true.

GetCharacterLevel

Returns the current level, XP, and XP needed for the next level for a player’s active character.

---@param source number Player server ID
---@return table|nil {level, xp, xpToNext} or nil if disabled/player not found
local info = exports['ars_multicharacter']:GetCharacterLevel(source)

Example:

local info = exports['ars_multicharacter']:GetCharacterLevel(source)

if info then
    print(('Level %d | XP %d/%d'):format(info.level, info.xp, info.xpToNext))
end

Level-Up Event

Listen for level-ups to hook rewards, unlocks, or announcements from other resources:

AddEventHandler('ars_multicharacter:server:levelUp', function(source, newLevel, citizenid)
    -- Give rewards, unlock content, broadcast announcements, etc.
    print(('Player %s reached level %d'):format(citizenid, newLevel))
end)

Client Events

ars_multicharacter:client:chooseChar

Opens the character selector for the local player. The server can trigger it with TriggerClientEvent, or another client-side script can trigger it locally.

• Side: client
• Usage: trigger

Client-side example:

TriggerEvent('ars_multicharacter:client:chooseChar')

Server-side example:

TriggerClientEvent('ars_multicharacter:client:chooseChar', playerId)

Warning: This event returns the player to character selection and clears the current play flow. Use it only for logout, moderation, or controlled server workflows.

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.