# Server Exports

## 🎮 SL-Queue API Documentation

Zaawansowany system kolejki dla serwerów FiveM z funkcjami zarządzania graczami, biletami pracy i priorytetami.

***

### 📋 Table of Contents

* 🚀 Getting Started
* 📊 Queue Status
* 👤 Player Management
* 🎫 Job Tickets
* ⚙️ Server Status
* 👑 Admin Functions
* 📈 Statistics
* 💡 Examples

***

### 🚀 Getting Started

SL-Queue provides a comprehensive API for managing your server's queue system. All exports are available through the resource name.

#### Basic Usage

```lua
local queueCount = exports['sl-queue']:GetQueueCount()
```

***

### 📊 Queue Status

#### GetQueueCount

Returns the current number of players in queue.

**Returns:** `number`

```lua
local count = exports['sl-queue']:GetQueueCount()
print("Players in queue:", count)
```

#### GetMaxPlayers

Returns the maximum number of players allowed on the server.

**Returns:** `number`

```lua
local maxPlayers = exports['sl-queue']:GetMaxPlayers()
print("Server capacity:", maxPlayers)
```

#### GetOnlineCount

Returns the current number of online players.

**Returns:** `number`

```lua
local online = exports['sl-queue']:GetOnlineCount()
print("Players online:", online)
```

#### GetConnectingCount

Returns the number of players currently connecting.

**Returns:** `number`

```lua
local connecting = exports['sl-queue']:GetConnectingCount()
print("Players connecting:", connecting)
```

***

### 👤 Player Management

#### GetPlayerQueuePosition

Gets a player's position in the queue.

**Parameters:**

* `source` (number) - Player server ID

**Returns:** `number` - Queue position (-1 if not in queue)

```lua
local position = exports['sl-queue']:GetPlayerQueuePosition(source)
if position > 0 then
    print("Queue position:", position)
end
```

#### IsPlayerInQueue

Checks if a player is currently in the queue.

**Parameters:**

* `source` (number) - Player server ID

**Returns:** `boolean`

```lua
local inQueue = exports['sl-queue']:IsPlayerInQueue(source)
if inQueue then
    print("Player is in queue")
end
```

#### GetPlayerQueueInfo

Gets detailed information about a player in the queue.

**Parameters:**

* `source` (number) - Player server ID

**Returns:**

```lua
{
    position = number,
    tier = number,
    name = string,
    joinTime = string,
    jobTicketId = string | nil,
    steamHex = string,
    discordId = string,
    license = string
} | nil
```

**Example:**

```lua
local info = exports['sl-queue']:GetPlayerQueueInfo(source)
if info then
    print("Position:", info.position)
    print("Priority tier:", info.tier)
    print("Join time:", info.joinTime)
end
```

#### GetPlayerTicketStatus

Gets the ticket status for a player.

**Parameters:**

* `source` (number) - Player server ID

**Returns:**

```lua
{
    ticketType = "normal" | "job",
    ticketId = string | nil,
    job = string | nil
}
```

**Example:**

```lua
local ticket = exports['sl-queue']:GetPlayerTicketStatus(source)
print("Ticket type:", ticket.ticketType)
if ticket.job then
    print("Job:", ticket.job)
end
```

#### CanUseCharacter

Checks if a player can use a specific character.

**Parameters:**

* `source` (number) - Player server ID
* `characterIdentifier` (string) - Character identifier

**Returns:** `boolean`

```lua
local canUse = exports['sl-queue']:CanUseCharacter(source, "char1:license")
if canUse then
    print("Player can use this character")
end
```

***

### 🎫 Job Tickets

#### GetJobTicketStats

Gets statistics for all job tickets.

**Returns:**

```lua
{
    [jobName] = {
        currentTickets = number,
        maxTickets = number,
        currentPlayers = number,
        tier = number
    }
}
```

**Example:**

```lua
local jobStats = exports['sl-queue']:GetJobTicketStats()
for job, stats in pairs(jobStats) do
    local usage = math.floor((stats.currentTickets / stats.maxTickets) * 100)
    print(string.format("%s: %d/%d (%d%% full)", 
        job, stats.currentTickets, stats.maxTickets, usage))
end
```

***

### ⚙️ Server Status

#### GetServerStatus

Gets the current server status including technical breaks and locks.

**Returns:**

```lua
{
    technicalBreak = boolean,
    technicalBreakTime = number,
    remainingTime = number,
    queueLock = boolean,
    whitelist = boolean
}
```

**Example:**

```lua
local status = exports['sl-queue']:GetServerStatus()
if status.technicalBreak then
    local minutes = math.floor(status.remainingTime / 60)
    print("Technical break:", minutes, "minutes remaining")
end
```

***

### 👑 Admin Functions

#### IsPlayerAdmin

Checks if a player is an administrator.

**Parameters:**

* `source` (number) - Player server ID

**Returns:** `boolean`

```lua
local isAdmin = exports['sl-queue']:IsPlayerAdmin(source)
if isAdmin then
    print("Player is an admin")
end
```

#### GetAdminCount

Gets the number of online administrators.

**Returns:** `number`

```lua
local adminCount = exports['sl-queue']:GetAdminCount()
print("Admins online:", adminCount)
```

#### GetQueueList

Gets the complete queue list (admin only).

**Returns:**

```lua
{
    {
        position = number,
        name = string,
        tier = number,
        joinTime = string,
        jobTicketId = string | nil,
        steamHex = string,
        discordId = string
    }
}
```

**Example:**

```lua
local queueList = exports['sl-queue']:GetQueueList()
for i, player in ipairs(queueList) do
    print(string.format("%d. %s (Tier: %d)", 
        player.position, player.name, player.tier))
end
```

***

### 📈 Statistics

#### GetServerStats

Gets comprehensive server statistics.

**Returns:**

```lua
{
    queue = {
        count = number,
        maxPlayers = number,
        onlineCount = number,
        connectingCount = number
    },
    status = {
        technicalBreak = boolean,
        technicalBreakTime = number,
        remainingBreakTime = number,
        queueLock = boolean,
        whitelist = boolean
    },
    jobTickets = { [jobName] = number },
    jobPlayers = { [jobName] = number },
    adminCount = number
}
```

**Example:**

```lua
local stats = exports['sl-queue']:GetServerStats()
print(string.format("Server: %d/%d online, %d in queue", 
    stats.queue.onlineCount, 
    stats.queue.maxPlayers, 
    stats.queue.count))
```

***

### 💡 Examples

#### Quick Server Overview

```lua
function GetServerOverview()
    local stats = exports['sl-queue']:GetServerStats()
    
    return {
        online = stats.queue.onlineCount,
        capacity = stats.queue.maxPlayers,
        queue = stats.queue.count,
        admins = stats.adminCount,
        utilization = math.floor((stats.queue.onlineCount / stats.queue.maxPlayers) * 100)
    }
end
```

#### Player Status Check

```lua
function CheckPlayer(source)
    local isAdmin = exports['sl-queue']:IsPlayerAdmin(source)
    local inQueue = exports['sl-queue']:IsPlayerInQueue(source)
    
    if isAdmin then
        return "Administrator"
    elseif inQueue then
        local position = exports['sl-queue']:GetPlayerQueuePosition(source)
        return "In queue at position " .. position
    else
        return "Connected to server"
    end
end
```

#### Queue Monitor

```lua
function MonitorQueue()
    CreateThread(function()
        while true do
            local count = exports['sl-queue']:GetQueueCount()
            local online = exports['sl-queue']:GetOnlineCount()
            local max = exports['sl-queue']:GetMaxPlayers()
            
            print(string.format("[QUEUE] %d online | %d in queue | %d/%d capacity", 
                online, count, online, max))
            
            Wait(30000) -- Check every 30 seconds
        end
    end)
end
```

#### Job Ticket Dashboard

```lua
function ShowJobDashboard()
    local jobStats = exports['sl-queue']:GetJobTicketStats()
    
    print("=== JOB TICKETS DASHBOARD ===")
    for job, stats in pairs(jobStats) do
        local percentage = math.floor((stats.currentTickets / stats.maxTickets) * 100)
        local status = percentage >= 80 and "🔴 HIGH" or percentage >= 50 and "🟡 MED" or "🟢 LOW"
        
        print(string.format("%s: %d/%d (%d%%) %s", 
            job, stats.currentTickets, stats.maxTickets, percentage, status))
    end
end
```

***

### ⚠️ Important Notes

#### Security

* Always validate player permissions before using admin functions
* Check if exports are available before calling them
* Log administrative actions for security purposes

#### Performance

* Cache results when possible to avoid excessive calls
* Use appropriate wait times in monitoring loops
* Consider server load when implementing automated systems

#### Best Practices

* Always check return values for nil
* Handle errors gracefully
* Use descriptive variable names
* Comment your integration code

***

### 🔧 Troubleshooting

#### Common Issues

**Export not found**

* Ensure the resource is started
* Check resource name in exports call
* Verify resource is loaded before calling

**Permission denied**

* Check admin permissions for restricted functions
* Verify player exists and is connected

**Invalid data returned**

* Player may have disconnected
* Queue state may have changed
* Always validate returned data

***

Last updated: August 2025