DocumentationAPI ReferenceServer Events

Server Events

QBCore fires a variety of server-side events that let you react to player lifecycle changes, data updates, job transitions, and framework state. Use these hooks to synchronize resources, persist data, or broadcast updates to connected clients.

Player Lifecycle Events

QBCore:Server:PlayerLoaded

Triggered after a player’s data has been loaded from the database and the server-side Player object is ready.

Parameters:

  • Player (table): The fully initialized player object

Example:

AddEventHandler('QBCore:Server:PlayerLoaded', function(Player)
    local src = Player.PlayerData.source
    print(('Player %s (%s) loaded'):format(Player.PlayerData.name, src))
 
    -- Send a welcome message and sync pending invites
    TriggerClientEvent('chat:addMessage', src, {
        args = {'QBCore', 'Welcome back, ' .. Player.PlayerData.charinfo.firstname .. '!'}
    })
    exports['qb-phone']:SyncMail(src)
end)

QBCore:Server:OnPlayerUnload

Fires when a player disconnects or their server session is terminated.

Parameters:

  • source (number): Server ID of the player that unloaded

Example:

AddEventHandler('QBCore:Server:OnPlayerUnload', function(source)
    print(('Player %d unloaded, saving session data'):format(source))
 
    -- Clean up temporary state
    exports['housing']:CleanupPlayer(source)
    TriggerEvent('logs:server:CreateLog', 'players', 'Player Unloaded', 'yellow', ('Player %d disconnected'):format(source))
end)

QBCore:Server:PlayerLoggedOut

Emitted when a player explicitly logs out (for example through multicharacter) without closing their FiveM client.

Parameters:

  • source (number): Server ID of the player logging out

Example:

AddEventHandler('QBCore:Server:PlayerLoggedOut', function(source)
    local Player = QBCore.Functions.GetPlayer(source)
    if Player then
        print(('Player %s logged out'):format(Player.PlayerData.citizenid))
    end
 
    -- Release job duty slots and stop timers
    TriggerEvent('duty:server:Toggle', source, false)
end)

Player Data & Economy Events

QBCore:Server:SetPlayerData

Raised whenever a field on the player object is updated via Player.Functions.SetPlayerData.

Parameters:

  • Player (table): Player object being modified
  • key (string): Data field that changed
  • value (any): New value written to the player data table

Example:

AddEventHandler('QBCore:Server:SetPlayerData', function(Player, key, value)
    if key == 'metadata' and value.stress then
        TriggerClientEvent('hud:client:UpdateStress', Player.PlayerData.source, value.stress)
    end
end)

QBCore:Server:OnMoneyChange

Triggers whenever a player’s money changes through AddMoney, RemoveMoney, or SetMoney.

Parameters:

  • source (number): Server ID of the player whose money changed
  • moneyType (string): cash, bank, or crypto
  • amount (number): Amount that changed
  • action (string): add, remove, or set
  • reason (string): Reason supplied when the change occurred

Example:

AddEventHandler('QBCore:Server:OnMoneyChange', function(source, moneyType, amount, action, reason)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
 
    print(('%s %s %s (%s)'):format(Player.PlayerData.name, action, amount, moneyType))
    exports['qb-logging']:CreateLog('economy', moneyType, {
        player = Player.PlayerData.citizenid,
        action = action,
        amount = amount,
        reason = reason or 'unspecified'
    })
end)

Job & Gang Events

QBCore:Server:OnJobUpdate

Dispatched when a player’s job is changed via Player.Functions.SetJob.

Parameters:

  • source (number): Server ID of the player whose job changed
  • jobInfo (table): Updated job data (name, label, grade, duty status, etc.)

Example:

AddEventHandler('QBCore:Server:OnJobUpdate', function(source, jobInfo)
    TriggerClientEvent('QBCore:Notify', source, ('You are now %s - %s'):format(jobInfo.label, jobInfo.grade.name), 'success')
 
    if jobInfo.name == 'police' then
        TriggerEvent('dispatch:server:SyncOfficerStatus', source, true)
    end
end)

QBCore:Server:OnGangUpdate

Dispatched when a player’s gang affiliation changes.

Parameters:

  • source (number): Server ID of the player whose gang changed
  • gangInfo (table): Updated gang data (name, label, grade, etc.)

Example:

AddEventHandler('QBCore:Server:OnGangUpdate', function(source, gangInfo)
    TriggerClientEvent('gangs:client:RefreshTerritory', source, gangInfo.name)
    print(('Gang update: %d -> %s'):format(source, gangInfo.label))
end)

Framework Maintenance Events

QBCore:Server:UpdateObject

Sent whenever the global QBCore object is refreshed (typically after a resource restart).

Parameters:

  • object (table): Updated QBCore object reference

Example:

AddEventHandler('QBCore:Server:UpdateObject', function(object)
    QBCore = object
    print('QBCore object refreshed on the server')
end)

Related Documentation

Client FunctionsClient Events