# 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

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

{% hint style="info" %}
Hooks auto-detect your framework (ESX, QBCore, Standalone). You normally don't need to modify anything unless you have a very specific setup.
{% endhint %}

***

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