red-valley/resources/[framework]/[base]/[auth]/connectqueue/README.md

# ConnectQueue
---
Easy to use queue system for FiveM with:
- Simple API
- Priority System
- **Advanced Logging System** 🆕
- Config
    - Ability for whitelist only
    - Require steam
    - Language options

**Please report any bugs on the release thread [Here](https://forum.fivem.net/t/alpha-connectqueue-a-server-queue-system-fxs/22228) or through [GitHub](https://github.com/Nick78111/ConnectQueue/issues).**

## How to install
---
- Drop the folder inside your resources folder.
- Add `start connectqueue` inside your server.cfg. - *Preferrably at the top*
- Set convars to your liking.
- Open `connectqueue/server/sv_queue_config.lua` and edit to your liking.
- Renaming the resource may cause problems.

## ConVars
---
	set sv_debugqueue true # prints debug messages to console
	set sv_displayqueue true # shows queue count in the server name '[count] server name'

## Advanced Logging System 🆕
---
The queue now features a comprehensive logging system with:

### Log Levels & Colors
| Level | Color | Icon | Description |
|-------|-------|------|-------------|
| DEBUG | ^5 (Cyan) | 🔍 | Detailed debug information |
| INFO | ^2 (Green) | ℹ️ | General information |
| WARN | ^3 (Yellow) | ⚠️ | Warning messages |
| ERROR | ^1 (Red) | ❌ | Error messages |
| SUCCESS | ^2 (Green) | ✅ | Successful operations |
| PLAYER | ^6 (Purple) | 👤 | Player-related events |
| QUEUE | ^4 (Blue) | 📋 | Queue operations |
| PRIORITY | ^8 (Orange) | ⭐ | Priority-related events |
| TIMEOUT | ^1 (Red) | ⏱️ | Timeout events |
| SYSTEM | ^9 (Pink) | ⚙️ | System messages |

### Log Format
```
[HH:MM:SS] [LEVEL] 🔍 Message
    ├─ Key1: Value1
    ├─ Key2: Value2
    └─ Key3: Value3
```

### Console Commands
Use `rcon queue <command>` to access these debug commands:
| Command | Description |
|---------|-------------|
| `addq` | Add debug queue entry |
| `removeq <index>` | Remove from queue by index |
| `printq` | Print formatted queue list |
| `addc` | Add debug connecting entry |
| `removec <index>` | Remove from connecting by index |
| `printc` | Print formatted connecting list |
| `printl` | Print active players list |
| `printp` | Print priority list |
| `printcount` / `stats` | Print server statistics |
| `printtp` | Print temp priority list |
| `removetp <id>` | Remove temp priority |
| `setpos <index> <newpos>` | Set queue position |
| `setdata <index> <field> <value>` | Modify player data |
| `commands` | Show all available commands |

### Example Output
```
╔══════════════════════════════════════════════════════════════╗
║                     📊 QUEUE STATISTICS                      ║
╚══════════════════════════════════════════════════════════════╝
  Players Online: 45 / 64
  Queue Size: 12
  Connecting: 2
  Available Slots: 17
──────────────────────────────────────────────────────────────
```

## How to use / Examples
---
To use the API add `server_script "@connectqueue/connectqueue.lua"` at the top of the `__resource.lua` file in question.
I would also suggest adding `dependency "connectqueue"` to it aswell.
You may now use any of the functions below, anywhere in that resource.

### OnReady
This is called when the queue functions are ready to be used.
```Lua
    Queue.OnReady(function() 
        print("HI")
    end)
```
All of the functions below must be called **AFTER** the queue is ready.

### OnJoin
This is called when a player tries to join the server.
Calling `allow` with no arguments will let them through.
Calling `allow` with a string will prevent them from joining with the given message.
`allow` must be called or the player will hang on connecting...
```Lua
Queue.OnJoin(function(source, allow)
    allow("No, you can't join")
end)
```

## AddPriority
Call this to add an identifier to the priority list.
The integer is how much power they have over other users with priority.
This function can take a table of ids or individually.
```Lua
-- individual
Queue.AddPriority("STEAM_0:1:33459672", 100)
Queue.AddPriority("steam:110000103fd1bb1", 10)
Queue.AddPriority("ip:127.0.0.1", 25)

-- table
local prioritize = {
    ["STEAM_0:1:33459672"] = 100,
    ["steam:110000103fd1bb1"] = 10,
    ["ip:127.0.0.1"] = 25,
}
Queue.AddPriority(prioritize)
```

## RemovePriority
Removes priority from a user.
```Lua
Queue.RemovePriority("STEAM_0:1:33459672")
```

## IsReady
Will return whether or not the queue's exports are ready to be called.
```Lua
print(Queue.IsReady())
```

## Other Queue Functions
You can call every queue function within sh_queue.lua.
```Lua
local ids = Queue.Exports:GetIds(src)

-- sets the player to position 1 in queue
Queue.Exports:SetPos(ids, 1)
-- returns whether or not the player has any priority
Queue.Exports:IsPriority(ids)
--- returns size of queue
Queue.Exports:GetSize()
-- plus many more...
```