bjj_dev / products
betabjj_queue
An efficient standalone queue system for FiveM with Discord integration, priority tiers, and a WebSocket relay for real-time web clients. Server-side performance sits between 0.00 and 0.03 ms.
Architecture
┌─────────────┐ HTTP POST ┌─────────────────┐ WebSocket ┌─────────────┐ │ FiveM │ ──────────────────► │ Relay Server │ ◄───────────────► │ Web Client │ │ Server │ /push, /broadcast │ (Node.js) │ │ (Browser) │ └─────────────┘ └─────────────────┘ └─────────────┘
FiveM pushes queue events to the relay via HTTP. The relay maintains persistent WebSocket connections with authenticated web clients — solving the serverless limitation on platforms like Vercel.
Features
Discord Priority System
Role-based priority queue powered by your Discord server. Map roles to priority tiers — staff, supporters, and VIPs skip ahead automatically.
Anti Rate-Limiter
Built-in request throttling caps Discord API calls at 30/min, preventing 429s and keeping your bot stable under heavy load.
Grace Period
Players who disconnect can rejoin with elevated queue priority within a configurable window — no penalty for crashes or quick restarts.
Emergency Lockdown
Kill switch that kicks all players, shuts down the server, and creates a lockfile preventing auto-restart until manually cleared.
WebSocket Relay
Companion relay server bridges FiveM queue events to web clients in real-time via WebSocket — works behind Vercel and other serverless hosts.
Ghost Player Detection
Periodic checks identify and remove ghost players from the queue, keeping counts accurate and slots available.
Configuration (Convars)
Place these in your server.cfg. Only convars marked required need values — everything else has sane defaults.
| Convar | Type | Description |
|---|---|---|
| bjjqueue:discordBotToken | STRING | Discord Bot Token from the Developer Portal |
| bjjqueue:discordGuildId | STRING | Discord server ID (right-click in Dev Mode) |
| bjjqueue:discordDebug | STRING | Enable debug prints in server console |
| bjjqueue:discordAPIVersion | INT | Discord API version (default: 10) |
| bjjqueue:discordRequestsPerMinute | INT | Max Discord API requests/min (default: 30) |
| bjjqueue:displayQueueInHostname | INT | Show queue count in server hostname |
| bjjqueue:gracePeriod | INT | Seconds a disconnected player keeps priority (0 = off) |
| bjjqueue:ghostCheckInterval | INT | Seconds between ghost player checks (default: 60) |
| bjjqueue:webhookStatusMessage | STRING | Webhook URL for status messages |
| bjjqueue:webhookStatusUpdateInterval | INT | Seconds between webhook status updates (default: 30) |
Exports (API)
GetQueueStatus(identifier: string)
→ { queueNumber: int, queuePriority: int }
Get a player's current queue position and priority.
UpdateQueuePriority(identifier: string, priority: int)
→ boolean
Temporarily update a player's queue priority for this session.
ForceRefreshQueue(void)
→ void
Force-refresh everyone's queue number and priority.
OnQueueAdded(callback: function)
→ void
Register a callback fired when a player enters the queue.
WebSocket Relay
The companion bjj_queue_relay is a lightweight Node.js server that sits between FiveM and your web frontend. It accepts HTTP pushes from the game server and fans them out over authenticated WebSocket connections.
JWT Auth
Web clients authenticate with short-lived tokens signed by your NEXTAUTH_SECRET.
API Token
FiveM authenticates pushes with a shared secret — simple and secure.
Docker Ready
Ships with docker-compose for one-command deployment behind nginx.
Relay Endpoints
Emergency Lockdown
If the queue malfunctions or a security breach is detected, trigger a lockdown. This kicks all players, shuts down the server process, and creates a queue_lockdown.lock file. The server will refuse to restart — even via txAdmin — until the file is manually deleted.
Console
queuelockdown "Reason Here"Export
exports['bjj_queue']:TriggerLockdown("Reason") bjj_queue is currently in beta.
← Back to bjj-dev.com