All resources

rsg-queue documentation#

Contents#

  1. Architecture
  2. How the queue works
  3. Priority rules
  4. Server exports
  5. Events and callbacks
  6. Commands
  7. Database schema
  8. Security model
  9. Server owner how-tos
  10. Troubleshooting

Architecture#

FilePurpose
fxmanifest.luaManifest, rsg-core locales, NUI files
shared/config.luaAll settings (tiers, slots, grace, links, maintenance, Discord, logging, rewards)
server/server.luaQueue, deferrals and Adaptive Card, VIP cache and DB, admin callbacks, commands, exports
client/client.luaOpens and closes the admin NUI and relays its actions
html/Admin panel (house leather & gold style, custom dropdown)
locales/*.json11 languages, same keys
install.sqlManual schema (same as auto-build)

How the queue works#

  1. playerConnecting defers the connection, waits up to 15 s for the VIP cache (rejecting with a "still starting" message if it never loads), then reads the player's license identifier (players without one are rejected).
  2. The player's priority is worked out (see below) and they are added to the queue. An older entry with the same license is dropped, so reconnect spam does not create duplicates.
  3. If Discord roles are enabled, the player's guild roles are fetched (cached, with a timeout). If maintenance mode is on and the player is not staff (or a VIP when Maintenance.allowVip), they are rejected; players already waiting are rejected too when it is switched on.
  4. A single server loop runs every second, sorts the queue (priority high to low, then join time) and admits every entry that fits a free slot:
    • Public players can fill up to sv_maxclients - ReservedSlots.
    • Entries with reserved = true (VIP tiers with reserved, staff, players moved to the front) can use all slots. This means a VIP behind a public player can still take a reserved slot.
  5. Admitted players count as "connecting" until playerJoining fires or ConnectTimeout passes, so slots are not double-booked.
  6. Once admitted, a player still sees the card until it has been on screen for Config.MinCardTime seconds (their slot is held meanwhile, and the ConnectTimeout load-in timer restarts when they actually join). Set it to 0 to join instantly.
  7. While waiting, the card refreshes every second (UpdateInterval, capped at 1 s so the clock does not skip) and shows position, tier, time waited, an estimated wait and, for VIPs, how many earlier players they skipped. The estimated wait counts down every second and is re-anchored when the queue position or admit pace changes (average gap between the last EstimateWindow admits × position). Players who close the game leave the queue automatically.
  8. If the resource stops, every waiting player is sent a "queue is restarting" message instead of a frozen card.

Priority rules#

SourcePriorityReserved slot access
No VIP0No
VIP tierConfig.Tiers[tier].priority (highest matching identifier wins)Config.Tiers[tier].reserved
Discord roleTier mapped in Config.Discord.roles if higher (or 'staff')As the tier
Staff ace (Config.StaffAce)Config.StaffPriority if higherYes
Crash grace+ Config.Grace.priority on top of the above, within Grace.minutes of dropping (not given when the player quit, was kicked or banned)Unchanged
Admin "Front"Current top priority + 1Yes

VIPs are matched against every identifier the player has, so one row can use either license: or discord:. Expired rows are ignored and reloaded every VipRefresh seconds or straight after any change.

Server exports#

ExportParametersReturns
AddVip(identifier, tier, days, name?)identifier type:value, tier key, days (0 = permanent, max 3650), optional nameok, message
RemoveVip(identifier)identifierok, message
IsVip(identifier)identifierfalse (none or expired) or `true, tier, expiresUnix
GetQueueSize()number waiting
GetQueue(){ name, tier, priority, joined }[] in queue order
SetMaintenance(on)booleanok, message (saved in the rsg_queue_state table, survives restarts)
IsMaintenance()boolean
local ok, msg = exports['rsg-queue']:AddVip('license:abc123', 'gold', 0, 'Arthur')

Events and callbacks#

NameSideDescription
rsg-queue:client:openAdmin (net)clientOpens the panel with data. Only sent by the /queue command
rsg-queue:server:getAdminData (callback)serverReturns { queue, vips, tiers, online, max, reserved, maintenance }; nil without permission
RSGCore:Server:PlayerLoaded (listened)serverPays the VIP reward when enabled
rsg-queue:server:adminAction (callback)server(action, data) with action vip_add, vip_remove, queue_front, queue_remove, maintenance (toggle); returns { ok, msg, data }

Commands#

See README. Admin commands use rsg-core's permission system (Config.AdminPermission). queuevip only runs from the server console (source 0).

Database schema#

rsg_queue_vip

ColumnTypeNotes
idINT AIPrimary key
identifierVARCHAR(80)Unique, e.g. license:..., discord:...
nameVARCHAR(100)Optional display name
tierVARCHAR(30)Key from Config.Tiers
expires_atDATETIMENULL = permanent
added_byVARCHAR(100)Admin name, console or resource name
created_atTIMESTAMPCreated time

Adding a VIP that already exists updates its tier and expiry (it does not stack days).

rsg_queue_rewards

ColumnTypeNotes
licenseVARCHAR(80)Primary key, Rockstar license
last_claimDATETIMELast VIP reward paid

rsg_queue_state

ColumnTypeNotes
keyVARCHAR(50)Primary key (maintenance)
valueVARCHAR(100)1 = maintenance on, 0 = off

Maintenance state lives in MySQL, not resource KVP, so the server never creates a db folder.

Security model#

  • Priority is decided only on the server from the database, aces and the server's own records. Nothing comes from the client.
  • Both admin callbacks check RSGCore.Functions.HasPermission(source, Config.AdminPermission) on every call.
  • Identifiers are validated (type:value, letters and digits only, max 80 chars), tiers must exist in config, days are clamped to 0–3650, and all SQL uses ? parameters.
  • NUI text is escaped before rendering.
  • VIP rewards: paid only on the server from Config.VipRewards, for the tier the server admitted the player with. The cooldown is a single atomic SQL upsert per license, so reconnecting or switching characters cannot claim twice.
  • The Discord bot token is read from a server convar, never from the shared config (which clients download).
  • Scripts calling the exports must do their own permission checks before granting VIP.

Server owner how-tos#

  • Add a tier: add diamond = { label = 'Diamond', priority = 40, reserved = true } to Config.Tiers, then restart.
  • Priority without reserved slots: set reserved = false on that tier.
  • No reserved slots at all: Config.ReservedSlots = 0.
  • Discord roles: enable Developer Mode in Discord, right-click a role → Copy ID, then roles = { ['1234567890'] = 'gold', ['9876543210'] = 'staff' }.
  • Maintenance before an update: /queuemaint on, restart, test, then /queuemaint off.
  • Renaming a tier key: existing rows with the old key are ignored; update them with SQL (UPDATE rsg_queue_vip SET tier = 'new' WHERE tier = 'old').

Troubleshooting#

ProblemFix
Players connect instantly with no queueThe server is not full and MinCardTime is 0; raise MinCardTime to always show the card
"database setup failed" in consoleCheck oxmysql connection string; or set AutoDatabase = false and import install.sql
Players see "server is still starting"The database or VIP load failed on start; check the console for a red [rsg-queue] error
VIP not getting priorityCheck the stored identifier matches one the player has (license: vs license2:), and that it has not expired
Card stuck on "Checking your connection"rsg-queue failed to start its database; see console
Staff not prioritisedAdd add_ace group.admin rsgqueue.staff allow (or your group) to server.cfg
Discord roles ignoredCheck the token convar, guildId, the bot is in the guild with the Server Members intent, and the player has linked Discord to RedM. Turn on Debug to see lookup errors
Wait estimate says "Calculating..."It needs at least two admits since the last restart
No logsStart rsg-log and add the Config.Log.channel channel to its config
Another resource also defers connectionsFine, but start rsg-queue early so the queue card shows first

Support the Project : https://rexshack.tebex.store/

Changelog#

  • 3.0.1: estimated wait and "players skipped" on the card, Discord role priority, maintenance mode (/queuemaint, panel toggle, exports), add VIP from the Queue tab, daily VIP cash rewards (rsg_queue_rewards table), rsg-log logging, restart message for waiting players; admits every free slot each second (was one player per second), rejects connections cleanly if the database fails on start, no crash grace after a deliberate quit/kick/ban, expired grace entries are swept, IsVip respects expiry, identifiers like license2: accepted, Staff label localised.
<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-queue 3.0.3. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core, oxmysql

Database#

Tables: rsg_queue_vip, rsg_queue_rewards.

Tables are created automatically on start while Config.AutoDatabase = true (default). Nothing is ever dropped or overwritten. For a manual install set Config.AutoDatabase = false and import install.sql once.

-- shared/config.lua
Config.AutoDatabase = true -- false = import the SQL file yourself

Configuration#

OptionDefaultNotes
Config.AutoDatabasetruecreate tables on start; set false and import install.sql to install manually
Config.Debugfalse
Config.ServerName'My RSG Server'shown at the top of the queue card
Config.CardImage''optional banner image url (https) for the queue card, '' = none
Config.UpdateInterval1000ms between queue card refreshes (keep at 1000 so the card clock ticks every second)
Config.MinCardTime15seconds the queue card always shows, even with a free slot (0 = join instantly)
Config.ConnectTimeout180seconds an admitted player may take to load in before their slot is freed
Config.VipRefresh300seconds between VIP cache reloads from the database (expiry)
Config.EstimateWindow20recent admits used to estimate the wait time on the card
Config.ReservedSlots4slots kept free for VIP/staff only. Public players can fill (sv_maxclients - ReservedSlots)
Config.AdminPermission'admin'rsg-core permission for /queue, /vipadd, /vipremove
Config.StaffAce'rsgqueue.staff'ace that gives staff top priority + reserved slot access
Config.StaffPriority100
Config.Gracetableplayers who drop keep a priority boost for a few minutes so they can rejoin quickly
Config.Tierstablepriority: higher goes first | reserved: may use reserved slots
Config.Linkstable
Config.Maintenancetable
Config.Discordtablethe bot must be in your guild with the Server Members intent enabled
Config.Logtable
Config.VipRewardstable

Exports#

Server

ExportArgumentsFile
AddVipidentifier, tier, days, nameserver/server.lua
RemoveVipidentifierserver/server.lua
SetMaintenanceonserver/server.lua
IsMaintenance``server/server.lua
IsVipidentifierserver/server.lua
GetQueueSize``server/server.lua
GetQueue``server/server.lua
-- example
local result = exports['rsg-queue']:AddVip(identifier, tier, days, name)

Callbacks#

CallbackSideArgumentsFile
rsg-queue:server:getAdminDataserversource, cbserver/server.lua
rsg-queue:server:adminActionserversource, cb, action, dataserver/server.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-queue:server:getAdminData', function(result)
    -- use result
end)

Events#

Server events can be fired by any client, so every handler re-validates the player, the arguments and any permission, distance or cooldown on the server. Never add a reward to a handler without those checks.

EventSideArgumentsFile
rsg-queue:client:openAdminclientdataclient/client.lua
-- from a server script
TriggerClientEvent('rsg-queue:client:openAdmin', source, data)

Commands#

CommandNotesFile
/queuelocale('cmd_queue')server/server.lua
/vipaddlocale('cmd_vipadd')server/server.lua
/vipremovelocale('cmd_vipremove')server/server.lua
/queuemaintlocale('cmd_maint')server/server.lua
/queuevipserver/server.lua

Locales#

Language files in locales/: de, el, en, es, fr, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->