paintball docs›

Paintball

API

-- 10 code blocks · 1 min read

get var-paintball try it on the test server

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

lua

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

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

Lobby

lua

-- 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

lua

-- 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

lua

-- 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

lua

-- 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

lua

-- 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

lua

-- 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

lua

-- 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.

lua

-- 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

sql

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`)
);

-- 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")

-- 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)

-- 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)

-- 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)

-- 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)

-- 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)

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

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`) );