📊Player Data

Learn how to access and modify a player's data

Introduction

The Player Data object in qb-core stores all information related to a player's character, such as personal details, job, gang affiliation, metadata, and more. These values are initialized using default values defined in the config.lua file of qb-core.

This guide will provide an overview of the structure, default values, and how you can access or modify player data

QBCore
├── Players
│   ├── [source]
│       ├── PlayerData
│           ├── citizenid: string (Unique identifier)
│           ├── cid: number (Character ID)
│           ├── money: table
│           │   └── { cash: number, bank: number }
│           ├── charinfo: table
│           │   ├── firstname: string
│           │   ├── lastname: string
│           │   ├── ...
│           ├── job: table
│           │   ├── name: string
│           │   ├── label: string
│           │   ├── payment: number
│           │   ├── onduty: boolean
│           │   ├── isboss: boolean
│           │   └── grade: table
│           │       ├── name: string
│           │       └── level: number
│           ├── gang: table
│           │   ├── name: string
│           │   ├── label: string
│           │   ├── isboss: boolean
│           │   └── grade: table
│           │       ├── name: string
│           │       └── level: number
│           ├── metadata: table
│           │   ├── hunger: number
│           │   ├── thirst: number
│           │   ├── stress: number
│           │   ├── isdead: boolean
│           │   └── ...
│           ├── position: vector3
│           └── items: table (inventory items)

Configuration

The player data default values can be modified in the config.lua file of qb-core. These defaults are stored in QBConfig.Player.PlayerDefaults and determine what a player starts with when creating a new character

Player Data Object Structure

As of qb-core version 1.3.0 (check your fxmanifest.lua) you don't have to import the core to have access to the player data. You can call it like this! exports['qb-core']:GetPlayer(source) — server exports['qb-core']:GetPlayerData() — client

When accessing the player object on the server using QBCore.Functions.GetPlayer pass the source (player net id) — shown in examples

When accessing the player object on the client, you don't have to pass anything and can just call QBCore.Functions.GetPlayerData

If you prefer to access the player data directly instead of calling the functions, you can do so with this format QBCore.Players[source].PlayerData but it's not recommended

Below is a breakdown of the player data structure, its properties, default values and how to access them when retrieving the player object

Identification Table

Property	Type	Default Value	Description
citizenid	string	Generated via CreateCitizenId	A unique identifier for the player.
cid	number	1	Character ID (used for multi-character systems).

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('qb-docs:server:getPlayerInfo', function(source)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    local citizenid = Player.PlayerData.citizenid
    print(citizenid)
end)

Money Table

Property	Type	Default Value	Description
money	table	{ cash = 0, bank = 0 }	Contains the player’s cash and bank balances.

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('qb-docs:server:getPlayerInfo', function(source)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    local money = Player.PlayerData.money
    local cash = money.cash
    local bank = money.bank
    print(cash, bank)
end)

Character Information Table

Property	Type	Default Value	Description
charinfo	table	{ firstname, lastname, ... }	Basic personal information about the player.

Subfields:

Subfield	Type	Default Value	Description
firstname	string	"Firstname"	The player's first name.
lastname	string	"Lastname"	The player's last name.
birthdate	string	"00-00-0000"	The player's date of birth.
gender	number	0	The player's gender (0 for male, 1 for female).
nationality	string	"USA"	The player's nationality.
phone	string	Generated via CreatePhoneNumber	The player's phone number.
account	string	Generated via CreateAccountNumber	The player's bank account number.

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('qb-docs:server:getPlayerInfo', function(source)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    local charinfo = Player.PlayerData.charinfo
    local firstname = Player.PlayerData.firstname
    local lastname = Player.PlayerData.lastname
    local birthdate = Player.PlayerData.birthdate
    local gender = Player.PlayerData.gender
    local nationality = Player.PlayerData.nationality
    local phone = Player.PlayerData.phone
    local account = Player.PlayerData.account
    print("Player's name:", firstname, lastname)
end)

Job Table

Property	Type	Default Value	Description
job	table	{ name = 'unemployed', ... }	The player’s current job and related information.

Subfields

Subfield	Type	Default Value	Description
name	string	"unemployed"	The job name.
label	string	"Civilian"	The display label of the job.
payment	number	10	The player’s salary.
onduty	boolean	false	Whether the player is on duty.
isboss	boolean	false	Whether the player is the boss of the job.
grade	table	{ name = 'Freelancer', ... }	The player's job grade.

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('qb-docs:server:getPlayerInfo', function(source)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    local jobInfo = Player.PlayerData.job
    local name = jobInfo.name
    local label = jobInfo.label
    local payment = jobInfo.payment
    local onduty = jobInfo.onduty
    local isboss = jobInfo.isboss
    print("Player's job:", name)
    print("Job label:", label)
end)

Gang Table

Property	Type	Default Value	Description
gang	table	{ name = 'Unaffiliated', ... }	The player’s current gang and related information.

Subfields

Subfield	Type	Default Value	Description
name	string	"Unaffiliated"	The gang name.
label	string	"No Gang"	The display label of the gang.
isboss	boolean	false	Whether the player is the boss of the job.
grade	table	{ name = 'Unaffiliated', ... }	The player's job grade.

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('qb-docs:server:getPlayerInfo', function(source)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    local gangInfo = Player.PlayerData.gang
    local name = gangInfo.name
    local label = gangInfo.label
    print("Player's gang:", name)
    print("Gang label:", label)
end)

Metadata Table

Property	Type	Default Value	Description
hunger	number	100	The player’s hunger level (0–100).
thirst	number	100	The player’s thirst level (0–100).
stress	number	0	The player’s stress level (0–100).
isdead	boolean	false	Whether the player is dead.
inhale	boolean	false	Whether the player is handcuffed.
phone	table	{}	Stores phone-specific data such as installed apps.

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('qb-docs:server:getPlayerInfo', function(source)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return end
    local metadata = Player.PlayerData.metadata
    local hunger = metadata.hunger
    local thirst = metadata.thirst
    print('Hunger Level: ', hunger)
    print('Thirst Level: ', thirst)
end)

Player Object Functions

Every player that is created on the server has certain functions that are attached to them. These functions can be called on them directly!

UpdatePlayerData

Update the players data on the client & server

This function triggers the event QBCore:Player:SetPlayerData

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.UpdatePlayerData()

SetJob

Set a player's job and grade

• job: string

• grade: number

• returns: boolean - true for successful, false for unsuccessful

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.SetJob('police', 1)

SetGang

Set a players gang and grade

• gang: string

• grade: number

• returns: boolean - true for successful, false for unsuccessful

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.SetGang('lostmc', 1)

Notify

Shows the player a notification

• text: string

• type: string — error, success, primary, warning

• length (optional): number

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.Notify('Hello!', 'success', 5000)

HasItem

Preferred to use inventory export for checking if has item! This function just routes to that

• item: string | table

• amount: number

• returns: boolean

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.HasItem('water_bottle', 1)

GetName

Get's the players full character name

• returns: string

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.GetName()

SetJobDuty

Sets the player on/off duty

This function triggers the events QBCore:Server:OnJobUpdate and QBCore:Client:OnJobUpdate It also triggers the function UpdatePlayerData

• duty: boolean

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.SetJobDuty(true)

SetPlayerData

Set the player data value of a player specifically by it's name

This function also triggers the function UpdatePlayerData

• key: string

• value: string | table

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.SetPlayerData('position', vector3(-425.3, 1123.6, 325.0))

SetMetaData

Set the metadata value of a player specifically by it's name

This function also triggers the function UpdatePlayerData

• key: string

• value: string | table | number

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.SetMetaData('hunger', 80)

GetMetaData

Gets the value of a player metadata specifically by it's name

• value: string

• returns: string | table | number

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.GetMetaData('hunger')

AddRep

Adds rep to value to a rep specifically by it's name

This function also triggers the function UpdatePlayerData

Add different kinds of rep in qb-core/config.lua

• rep: string

• amount: number

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.AddRep('selling', 10)

RemoveRep

Decreases value to a rep specifically by it's name

This function also triggers the function UpdatePlayerData

Add different kinds of rep in qb-core/config.lua

• rep: string

• amount: number

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.RemoveRep('selling', 10)

GetRep

Gets the current value of rep specifically by it's name

• rep: string

• returns: number

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.GetRep('selling')

AddMoney

Adds to the value of a specific money type by it's name

This function also triggers the function UpdatePlayerData

• money: string

• returns: boolean

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.AddMoney('cash', 1000)

RemoveMoney

Decreases the value of a specific money type by it's name

This function also triggers the function UpdatePlayerData

• money: string

• returns: boolean

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.RemoveMoney('cash', 1000)

SetMoney

Sets the value of a specific money type by it's name

This function also triggers the function UpdatePlayerData

• money: string

• returns: boolean

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.SetMoney('cash', 1000)

GetMoney

Returns the value of the money type supplied

• money: string

• returns: number

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.GetMoney('cash')

Save

Triggers a save of the player

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.Save()

Logout

Forces the player to logout back to the multicharacter screen

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.Logout()

AddMethod

The AddMethod function allows you to dynamically add custom methods (functions) to the player object. This is particularly useful for extending player functionality in a modular and reusable way

It's worth checking if a method already exists! You can do so by running this check if Player.Functions.MyMethod then print("Method already exists!") end

• method: string

• handler: function

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end

Player.Functions.AddMethod('Greet', function()
    print("Hello, " .. Player.Functions.GetName() .. "!")
)

Player.Functions.Greet()

AddField

The AddField function allows you to dynamically add custom fields (variables or data) to the player object. This is useful for storing additional player-specific data that isn’t part of the default PlayerData structure

It's worth checking if a field already exists! You can do so by running this check if Player.MyField then print("Field already exists!") end

• field: string

• data: any

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
Player.Functions.AddField("Skills", {
    hacking = 1,
    driving = 3,
    shooting = 2
})