Deferrals: what players see while connecting
In playerConnecting, call deferrals.defer(), wait at least one tick, then use deferrals.update(text) for progress, deferrals.presentCard(card, cb) for an interactive Adaptive Card, and finish with deferrals.done() to admit or deferrals.done(reason) to refuse. deferrals.handover(data) passes data to the loading screen. Every code path must end in done.
Between clicking Connect and the loading screen, a server can hold the player on a connecting screen — to check bans, verify a whitelist, show a queue position or simply greet them. That is what deferrals are for, and a few strict rules decide whether they work or leave players stuck forever.
#The deferrals object
| Member | Does |
|---|---|
defer() | Takes over the connection for your resource |
update(message) | Shows a progress message |
presentCard(card, cb) | Shows an Adaptive Card; cb receives submitted data |
done(reason?) | Admits (no reason) or refuses (with reason) |
handover(data) | Passes data to the loading screen for this player |
From the playerConnecting documentation.
#A ban check with progress messages
AddEventHandler('playerConnecting', function(name, setKickReason, deferrals)
local src = source
deferrals.defer()
Wait(0) -- mandatory
deferrals.update(('Hello %s, checking your account…'):format(name))
local license = GetPlayerIdentifierByType(src, 'license')
local ban = MySQL.single.await('SELECT reason FROM bans WHERE license = ?', { license })
Wait(0)
if ban then
deferrals.done(('You are banned: %s. Appeal on our Discord.'):format(ban.reason))
return
end
deferrals.handover({ name = name, joinedAt = os.time() })
deferrals.done()
end)The loading screen can read the handover data — see handover data.
#The rules
- Wait at least one tick after
defer()beforeupdate,presentCardordone. - Wait a tick between a prior deferral call and
done. - Use the temporary
sourceonly with identifier and name functions — the player is not in the game yet. - Several resources can defer the same connection; the player gets in only when all finish.
- Always finish — including when a database or HTTP call fails.
#What deferrals are used for
| Use | Guide |
|---|---|
| Ban checks | Above |
| Discord role whitelist | Discord whitelist |
| Interactive rules / password cards | Adaptive Cards in deferrals |
| Queues and priority | Connect queue and priority |
Questions
What are deferrals in FiveM?
playerConnecting while your server checks something, showing messages or cards, then admitting or refusing them.Why are players stuck on Connecting?
deferrals.done was never called on some code path.Why does deferrals.update not show?
Wait(0)) after deferrals.defer().How do I refuse a connection with a message?
deferrals.done('your message').Ready to pick a map?
Twelve themes on three base map styles, $8 each, instant download.
Relevant to what you just read
The tool for this
A drag-and-drop loading screen, hosted for you From Free, built in the browser, exported as a drop-in resource.