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 |
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 |
Common questions
What are deferrals in FiveM?
A way to hold a connecting player in playerConnecting while your server checks something, showing messages or cards, then admitting or refusing them.
Why are players stuck on Connecting?
A deferral was started but deferrals.done was never called on some code path.
Why does deferrals.update not show?
You must wait at least one tick (Wait(0)) after deferrals.defer().
How do I refuse a connection with a message?
Call deferrals.done('your message').
Want a loading screen you never have to debug?
Build it in the browser, export once, and edit it whenever — no HTML, no re-uploads.
Start free