# Player 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

{% hint style="success" %}
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
{% endhint %}

{% hint style="info" %}
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
{% endhint %}

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). |

```lua
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. |

```lua
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.               |

```lua
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.                    |

```lua
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.                    |

```lua
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. |

```lua
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

{% hint style="info" %}
This function triggers the event `QBCore:Player:SetPlayerData`
{% endhint %}

```lua
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`
* <mark style="color:yellow;">returns</mark>: `boolean` - true for successful, false for unsuccessful

```lua
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`
* <mark style="color:yellow;">returns</mark>: `boolean` - true for successful, false for unsuccessful

```lua
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`

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

### HasItem

{% hint style="info" %}
Preferred to use inventory export for checking if has item! This function just routes to that
{% endhint %}

* item: `string | table`
* amount: `number`
* <mark style="color:yellow;">returns</mark>: `boolean`

```lua
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

* <mark style="color:yellow;">returns</mark>: `string`

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

### SetJobDuty

Sets the player on/off duty

{% hint style="info" %}
This function triggers the events `QBCore:Server:OnJobUpdate` and `QBCore:Client:OnJobUpdate` It also triggers the function `UpdatePlayerData`
{% endhint %}

* duty: `boolean`

```lua
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

{% hint style="info" %}
This function also triggers the function `UpdatePlayerData`
{% endhint %}

* key: `string`
* value: `string | table`

```lua
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

{% hint style="info" %}
This function also triggers the function `UpdatePlayerData`
{% endhint %}

* key: `string`
* value: `string | table | number`

```lua
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`
* <mark style="color:yellow;">returns</mark>: `string | table | number`

```lua
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

{% hint style="info" %}
This function also triggers the function `UpdatePlayerData`
{% endhint %}

{% hint style="info" %}
Add different kinds of rep in `qb-core/config.lua`
{% endhint %}

* rep: `string`
* amount: `number`

```lua
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

{% hint style="info" %}
This function also triggers the function `UpdatePlayerData`
{% endhint %}

{% hint style="info" %}
Add different kinds of rep in `qb-core/config.lua`
{% endhint %}

* rep: `string`
* amount: `number`

```lua
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`
* <mark style="color:yellow;">returns</mark>: `number`

```lua
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

{% hint style="info" %}
This function also triggers the function `UpdatePlayerData`
{% endhint %}

* money: `string`
* <mark style="color:yellow;">returns</mark>: `boolean`

```lua
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

{% hint style="info" %}
This function also triggers the function `UpdatePlayerData`
{% endhint %}

* money: `string`
* <mark style="color:yellow;">returns</mark>: `boolean`

```lua
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

{% hint style="info" %}
This function also triggers the function `UpdatePlayerData`
{% endhint %}

* money: `string`
* <mark style="color:yellow;">returns</mark>: `boolean`

```lua
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`
* <mark style="color:yellow;">returns</mark>: `number`

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

### Save

Triggers a save of the player

```lua
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

```lua
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

{% hint style="warning" %}
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`
{% endhint %}

* method: `string`
* handler: `function`

```lua
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

{% hint style="warning" %}
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`
{% endhint %}

* field: `string`
* data: `any`

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qbcore.org/qbcore-documentation/qb-core/player-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.