DocumentationAPI ReferenceClient Events

Client Events

QBCore uses an event-driven architecture on the client to keep player state, UI, and gameplay systems in sync with the server. These events can be listened to with RegisterNetEvent to react when the framework broadcasts updates.

Player Lifecycle Events

QBCore:Client:OnPlayerLoaded

Triggered when the local player has finished loading and all PlayerData is available.

Example:

RegisterNetEvent('QBCore:Client:OnPlayerLoaded', function()
    local PlayerData = QBCore.Functions.GetPlayerData()
    print(('Welcome back, %s'):format(PlayerData.charinfo.firstname))
 
    -- Initialize HUD and job-dependent systems
    TriggerEvent('hud:client:Init')
    TriggerEvent('job:client:refreshEquipment')
end)

QBCore:Client:OnPlayerUnload

Fires when the player is removed from the active session (disconnect or character switch).

Example:

RegisterNetEvent('QBCore:Client:OnPlayerUnload', function()
    print('Player unloaded, clearing cached data')
 
    -- Reset stateful tables and UI elements
    PlayerData = {}
    TriggerEvent('hud:client:Reset')
    exports['qb-target']:RemoveZone('dutyToggle')
end)

QBCore:Player:SetPlayerData

Dispatched whenever the server updates the PlayerData table.

Parameters:

  • data (table): Full player data payload delivered from the server

Example:

RegisterNetEvent('QBCore:Player:SetPlayerData', function(data)
    PlayerData = data
    TriggerEvent('hud:client:UpdateNeeds', data.metadata.hunger, data.metadata.thirst)
end)

Job & Gang Events

QBCore:Client:OnJobUpdate

Triggered when a player’s job changes (name, grade, or duty status).

Parameters:

  • jobInfo (table): Updated job table (name, label, grade, onduty, etc.)

Example:

RegisterNetEvent('QBCore:Client:OnJobUpdate', function(jobInfo)
    PlayerData.job = jobInfo
    QBCore.Functions.Notify(('New job: %s'):format(jobInfo.label), 'success')
 
    if jobInfo.name == 'police' then
        TriggerEvent('police:client:OnDuty')
    end
end)

QBCore:Client:SetDuty

Fired when the player’s duty status toggles without changing the job itself.

Parameters:

  • duty (boolean): true if going on duty, false otherwise

Example:

RegisterNetEvent('QBCore:Client:SetDuty', function(duty)
    PlayerData.job.onduty = duty
    TriggerEvent('hud:client:ToggleJob', duty)
end)

QBCore:Client:OnGangUpdate

Triggered when a player’s gang affiliation or grade changes.

Parameters:

  • gangInfo (table): Updated gang table (name, label, grade, etc.)

Example:

RegisterNetEvent('QBCore:Client:OnGangUpdate', function(gangInfo)
    PlayerData.gang = gangInfo
    TriggerEvent('gangs:client:RefreshColors', gangInfo.name)
end)

Money & Inventory Events

QBCore:Client:OnMoneyChange

Emitted whenever the player’s money changes on the client.

Parameters:

  • moneyType (string): cash, bank, or crypto
  • amount (number): Amount changed
  • operation (string): add, remove, or set
  • reason (string): Optional description of the transaction

Example:

RegisterNetEvent('QBCore:Client:OnMoneyChange', function(moneyType, amount, operation, reason)
    TriggerEvent('hud:client:MoneyChange', moneyType, amount, operation)
    print(('Money update: %s %s %s (%s)'):format(operation, moneyType, amount, reason or 'N/A'))
end)

QBCore:Client:OnUseItem

Triggered when the player uses a useable item.

Parameters:

  • itemName (string): Name of the item used
  • itemData (table): Item metadata (slot, info, etc.)

Example:

RegisterNetEvent('QBCore:Client:OnUseItem', function(itemName, itemData)
    if itemName == 'lockpick' then
        TriggerEvent('lockpick:client:Use', itemData)
    end
end)

QBCore:Client:ItemBox

Displays the item box animation when an item is added or removed.

Parameters:

  • itemData (table): Item information table (name, label, info)
  • type (string): add or remove

Example:

RegisterNetEvent('QBCore:Client:ItemBox', function(itemData, type)
    if type == 'add' then
        PlaySoundFrontend(-1, 'Pickup_Remote_Pistol', 'HUD_LIQUOR_STORE_SOUNDSET', false)
    end
end)

Vehicle Events

QBCore:Client:VehicleInfo

Provides vehicle statistics when entering or approaching a vehicle.

Parameters:

  • info (table): Vehicle data (model, plate, fuel, damage, etc.)

Example:

RegisterNetEvent('QBCore:Client:VehicleInfo', function(info)
    SendNUIMessage({ action = 'vehicleInfo', data = info })
end)

QBCore:Client:EnteredVehicle

Fires when the player enters any vehicle.

Example:

RegisterNetEvent('QBCore:Client:EnteredVehicle', function()
    local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
    local plate = QBCore.Functions.GetPlate(vehicle)
    print(('Entered vehicle %s'):format(plate))
end)

QBCore:Client:LeftVehicle

Fires when the player exits a vehicle.

Example:

RegisterNetEvent('QBCore:Client:LeftVehicle', function()
    print('Exited vehicle, resetting cruise control')
    TriggerEvent('vehicles:client:DisableCruise')
end)

Framework & Utility Events

QBCore:Client:UpdateObject

Dispatched when the QBCore object is refreshed (for example after restarting qb-core).

Example:

RegisterNetEvent('QBCore:Client:UpdateObject', function()
    QBCore = exports['qb-core']:GetCoreObject()
    print('Refreshed QBCore object on client')
end)

QBCore:Notify

Allows the server to show a standard QBCore notification on the client.

Parameters:

  • text (string): Message to display
  • type (string): success, error, primary, warning, or info
  • length (number): Duration in milliseconds

Example:

RegisterNetEvent('QBCore:Notify', function(text, type, length)
    QBCore.Functions.Notify(text, type, length)
end)

QBCore:Command:Update

Sent by the server when available commands are refreshed (permissions changed, new commands registered, etc.).

Parameters:

  • commands (table): Array of command definitions available to the player

Example:

RegisterNetEvent('QBCore:Command:Update', function(commands)
    print(('Received %d commands from server'):format(#commands))
    TriggerEvent('chat:client:SetSuggestions', commands)
end)

Related Documentation

Server EventsCommands