⚙️API

This page documents the events and callbacks available for developers who want to integrate Var-PaintBall with other resources.

---

Server Events

These events are triggered from the client to the server.

Queue

-- Join the quick play queue
TriggerServerEvent("var-paintball:server:queue:join")

-- Leave the quick play queue
TriggerServerEvent("var-paintball:server:queue:leave")

Lobby

-- Create a lobby
TriggerServerEvent("var-paintball:server:lobby:create", {
    arena      = "boardwalk",    -- Arena key
    mode       = "TEAM",         -- TEAM | ELIM | FFA | GUNGAME
    weapon     = "paintball",    -- Weapon key
    teamSize   = 3,              -- Players per team
    target     = 35,             -- Target score
    timeLimit  = 600,            -- Max duration (seconds)
    nightMode  = false,
    hardcore   = false,
    friendly   = false,
    autoStart  = true,
    password   = "",             -- Empty = no password
    wager      = 0,              -- 0 = no wager
    wagerAccount = "cash",       -- "cash" or "bank"
})

-- Join a lobby
TriggerServerEvent("var-paintball:server:lobby:join", lobbyId, {
    password      = "",          -- Password if required
    wagerAccount  = "cash",
})

-- Leave a lobby
TriggerServerEvent("var-paintball:server:lobby:leave")

-- Start the match (creator only)
TriggerServerEvent("var-paintball:server:lobby:start")

-- Toggle ready state
TriggerServerEvent("var-paintball:server:lobby:ready")

Match

-- Leave the current match
TriggerServerEvent("var-paintball:server:match:leave")

-- Spectate a match
TriggerServerEvent("var-paintball:server:match:spectate", matchId)

-- Stop spectating
TriggerServerEvent("var-paintball:server:match:stopSpectating")

-- Request a respawn
TriggerServerEvent("var-paintball:server:match:requestRespawn")

-- Register a hit (called automatically by the client)
TriggerServerEvent("var-paintball:server:registerHit", victimId, weaponHash, boneIndex)

Other

-- Set a nickname
TriggerServerEvent("var-paintball:server:nickname:set", nickname)

-- Fetch the leaderboard
TriggerServerEvent("var-paintball:server:leaderboard:fetch")

---

Client Events

These events are sent from the server to the client.

Interface

-- Toggle the UI
TriggerClientEvent("var-paintball:client:ui:toggle", source)

-- Update state (lobbies, queue, etc.)
TriggerClientEvent("var-paintball:client:state:update", source, stateData)

-- Notification
TriggerClientEvent("var-paintball:client:notify", source, message)

Match

-- Start the match on the client
TriggerClientEvent("var-paintball:client:match:start", source, matchSettings)

-- Update scores
TriggerClientEvent("var-paintball:client:match:update", source, matchData)

-- Hit feedback (for the attacker)
TriggerClientEvent("var-paintball:client:match:hit", source, hitData)

-- Kill feed entry
TriggerClientEvent("var-paintball:client:match:killfeed", source, killData)

-- Medal awarded
TriggerClientEvent("var-paintball:client:match:medal", source, medalType)

-- Weapon swap (Gun Game)
TriggerClientEvent("var-paintball:client:match:weaponSwap", source, tierData)

-- Respawn the player
TriggerClientEvent("var-paintball:client:match:respawn", source, spawnData)

-- Match ended
TriggerClientEvent("var-paintball:client:match:end", source, resultsData)

Spectator

-- Spectate a teammate (ELIM after elimination)
TriggerClientEvent("var-paintball:client:match:spectate", source, targetId)

-- External spectating
TriggerClientEvent("var-paintball:client:match:spectateExternal", source, matchData)

-- End spectating
TriggerClientEvent("var-paintball:client:match:spectateEnd", source)

Leaderboard

-- Leaderboard data
TriggerClientEvent("var-paintball:client:leaderboard:update", source, leaderboardData)

---

Hooks (Framework)

The file server/hooks.lua provides a framework abstraction layer. These functions are used internally but can be modified to fit your server.

-- Get the player's identifier
Hooks.getIdentifier(source)  -- Returns license or steam ID

-- Get the player's locale
Hooks.getLocale(source)  -- Returns "en", "fr", etc.

-- Get the player's money
Hooks.getMoney(source, account)  -- account: "cash" or "bank"

-- Remove money
Hooks.removeMoney(source, amount, account)

-- Add money
Hooks.addMoney(source, amount, account)

-- Set the routing bucket
Hooks.setBucket(source, bucket)

-- Remove all weapons
Hooks.clearLoadout(source)

-- Send a notification
Hooks.notify(source, key)

-- Fetch Steam avatar (async)
Hooks.fetchSteamAvatar(source, callback)

Hooks auto-detect your framework (ESX, QBCore, Standalone). You normally don't need to modify anything unless you have a very specific setup.

---

NUI Callbacks

The React interface communicates with the client via these callbacks:

Callback	Description
hideFrame	Close the interface
quickPlay	Join the quick play queue
leaveQueue	Leave the quick play queue
createLobby	Create a lobby
joinLobby	Join a lobby
leaveLobby	Leave a lobby
startLobby	Start the match
toggleReady	Toggle ready state
setNickname	Set a nickname
leaveMatch	Leave the match
spectateMatch	Spectate a match
stopSpectating	Stop spectating
refreshLeaderboard	Refresh the leaderboard

---

Database Schema

CREATE TABLE IF NOT EXISTS `paintball_stats` (
    `identifier`  VARCHAR(60) NOT NULL,     -- Unique player identifier
    `nickname`    VARCHAR(32) DEFAULT 'Player',
    `games`       INT UNSIGNED DEFAULT 0,   -- Games played
    `wins`        INT UNSIGNED DEFAULT 0,   -- Wins
    `points`      INT UNSIGNED DEFAULT 0,   -- Total points
    `kills`       INT UNSIGNED DEFAULT 0,   -- Total kills
    `deaths`      INT UNSIGNED DEFAULT 0,   -- Total deaths
    `headshots`   INT UNSIGNED DEFAULT 0,   -- Total headshots
    `best_streak` INT UNSIGNED DEFAULT 0,   -- Best streak
    `playtime`    INT UNSIGNED DEFAULT 0,   -- Playtime (seconds)
    `updated_at`  TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`identifier`)
);