# Shared

## Introduction

* The shared folder inside qb-core contains all the information for your jobs, vehicles, items & more! You will spend a lot of time in this folder configuring everything to your exact specifications. Jenkins hashes are used frequently, you can find more information on those [here](https://cookbook.fivem.net/2019/06/23/lua-support-for-compile-time-jenkins-hashes/)

{% hint style="success" %}
QBCore uses Lua tables for storing static information instead of relying on a database. This avoids the need for frequent database queries, resulting in faster operations. Combined with [Shared Exports](/qbcore-documentation/qb-core/shared-exports.md) it can be a very powerful tool!
{% endhint %}

### Utility

* Found in `qb-core/shared/main.lua`

#### Starting Items

Starter items are predefined items that a player receives when joining the server for the first time

* item\_name: `string`
* amount: `number`

```lua
QBShared.StarterItems = {
    phone = 1,
    id_card = 1,
    driver_license = 1,
}
```

Example Usage:

```lua
for item, amount in pairs(QBCore.Shared.StarterItems) do
    local item_info = QCore.Shared.Items[item]
    print('Received '..amount..' '..item_info.label)
end
```

#### Generate a Random String

Generates a random string of a specified length

```lua
QBShared.RandomStr(length)
```

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

Example Usage:

```lua
local randomString = QBCore.Shared.RandomStr(8)
print(randomString) -- Example Output: "aBcD1234"
```

#### Generate a Random Integer String

Generates a random numeric string of a specified length

```lua
QBShared.RandomInt(length)
```

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

Example Usage:

```lua
local randomInt = QBCore.Shared.RandomInt(6)
print(randomInt) -- Example Output: "473829"
```

#### Split a String

Splits a string into parts based on a delimiter

```lua
QBShared.SplitStr(str, delimiter)
```

* str: `string` - The string to split
* delimiter: `string` - The character or sequence used to split the string
* <mark style="color:yellow;">returns</mark>: `table`

Example Usage:

```lua
local result = QBCore.Shared.SplitStr("apple,banana,orange", ",")
-- Result: { "apple", "banana", "orange" }
```

#### Trim WhiteSpace

Removes leading and trailing whitespace from a string

```lua
QBShared.Trim(value)
```

* value: `string` - The string to trim
* <mark style="color:yellow;">returns</mark>: `string`

Example Usage:

```lua
local trimmed = QBCore.Shared.Trim("   Hello World!   ")
print(trimmed) -- Output: "Hello World!"
```

#### Round a Number

Rounds a number to the nearest whole number or to a specified number of decimal places

```lua
QBShared.Round(value, numDecimalPlaces)
```

* value: `number` - The number to round
* numDecimalPlaces (optional): `number` - The number of decimal places to round to
* <mark style="color:yellow;">returns</mark>: `number`

Example Usage:

```lua
local roundedValue = QBCore.Shared.Round(5.6789, 2)
print(roundedValue) -- Output: 5.68
```

#### Change Vehicle Extra

Toggles an extra on a vehicle

```lua
QBShared.ChangeVehicleExtra(vehicle, extra, enable)
```

* vehicle: `number` - The vehicle entity
* extra: `number` - The extra ID
* enable: `boolean` - Whether to enable/disable the extra

Example Usage:

```lua
QBCore.Shared.ChangeVehicleExtra(vehicle, 1, true)
```

#### Set Default Vehicle Extras

Resets all extras on a vehicle and applies a specified configuration

```lua
QBShared.SetDefaultVehicleExtras(vehicle, config)
```

* vehicle: `number` - The vehicle entity
* config: `table` - A table defining which extras to enable/disable

Example Usage:

```lua
local config = {
    [1] = true, -- Enable extra 1
    [2] = false, -- Disable extra 2
    [3] = true -- Enable extra 3
}
QBCore.Shared.SetDefaultVehicleExtras(vehicle, config)
```

### Items

* Found in `qb-core/shared/items.lua`

The `Items` table in **qb-core** defines all the items available in your server. Each item is represented as an object with several properties that determine its behavior, appearance, and functionality.

| Property      | Type      | Description                                                             |
| ------------- | --------- | ----------------------------------------------------------------------- |
| `name`        | `string`  | The internal name used for spawning, giving, or removing the item.      |
| `label`       | `string`  | The display name shown in the inventory.                                |
| `weight`      | `number`  | The weight of the item, affecting inventory capacity.                   |
| `type`        | `string`  | The type of item (e.g., `item`, `weapon`).                              |
| `image`       | `string`  | The filename of the item's image located in `qb-inventory/html/images`. |
| `unique`      | `boolean` | Whether the item is unique (`true`) or stackable (`false`).             |
| `useable`     | `boolean` | Whether the item is usable. Must still be registered as a usable item.  |
| `shouldClose` | `boolean` | Whether using the item closes the inventory (`true` or `false`).        |
| `description` | `string`  | A short description of the item shown in the inventory.                 |

**Example: Basic Item Definition**

```lua
QBShared.Items = {
    id_card = {
        name = 'id_card', -- Internal name
        label = 'ID Card', -- Display name in inventory
        weight = 0, -- Item weight
        type = 'item', -- Type of item (e.g., item, weapon)
        image = 'id_card.png', -- Item image filename
        unique = true, -- Is the item unique?
        useable = true, -- Can the item be used?
        shouldClose = false, -- Does it close the inventory on use?
        description = 'A card containing all your information to identify yourself' -- Description
    }
}
```

### Jobs

* Found in `qb-core/shared/jobs.lua`

The `Jobs` table in **qb-core** defines all the jobs available on your server, including their ranks, salaries, and specific features. This allows you to manage employment roles, responsibilities, and pay structures effectively.

**Example: Global Setting**

The global setting determines if the duty state should default to the `defaultDuty` setting of the job upon login or persist based on the last saved state in the database:

```lua
QBShared.ForceJobDefaultDutyAtLogin = true -- true: Use job's defaultDuty | false: Use last saved duty state from database
```

***

**Job Object Layout**

| Property      | Type      | Description                                                                                |
| ------------- | --------- | ------------------------------------------------------------------------------------------ |
| `label`       | `string`  | The display name of the job.                                                               |
| `type`        | `string`  | The type of job (e.g., `leo` for law enforcement officer).                                 |
| `defaultDuty` | `boolean` | Whether the player is automatically on duty when they log in.                              |
| `offDutyPay`  | `boolean` | Whether the player receives a paycheck while off duty.                                     |
| `grades`      | `table`   | A table defining job grades, including names, payment, and other rank-specific attributes. |

**Grades Table Layout**

| Property  | Type      | Description                                                           |
| --------- | --------- | --------------------------------------------------------------------- |
| `name`    | `string`  | The name of the grade (e.g., Recruit, Officer).                       |
| `payment` | `number`  | The salary for this grade.                                            |
| `isboss`  | `boolean` | (Optional) If `true`, this grade is marked as the boss (e.g., Chief). |

**Example: Basic Job Definition**

This example defines the unemployed job with a single grade:

```lua
QBShared.Jobs = {
    unemployed = {
        label = 'Civilian', -- Display name
        defaultDuty = true, -- Automatically on duty at login
        offDutyPay = false, -- No payment while off duty
        grades = {
            { name = 'Freelancer', payment = 10 } -- Single grade with payment
        }
    }
}
```

**Example: Advanced Job Definition**

This example defines the police job with multiple grades, each with specific attributes:

```lua
QBShared.Jobs = {
    police = {
        label = 'Law Enforcement', -- Display name
        type = 'leo', -- Job type (e.g., law enforcement)
        defaultDuty = true, -- Automatically on duty at login
        offDutyPay = false, -- No payment while off duty
        grades = {
            { name = 'Recruit',    payment = 50 },  -- Rank 1: Recruit with $50 payment
            { name = 'Officer',    payment = 75 },  -- Rank 2: Officer with $75 payment
            { name = 'Sergeant',   payment = 100 }, -- Rank 3: Sergeant with $100 payment
            { name = 'Lieutenant', payment = 125 }, -- Rank 4: Lieutenant with $125 payment
            { name = 'Chief',      isboss = true, payment = 150 }, -- Rank 5: Chief, marked as boss, with $150 payment
        }
    }
}
```

### Gangs

* Found in `qb-core/shared/gangs.lua`

The `Gangs` table in **qb-core** defines all the gangs available on your server, including their ranks, salaries, and specific features. This allows you to manage member roles, responsibilities, and pay structures effectively.

***

**Gang Object Layout**

| Property | Type     | Description                                                                       |
| -------- | -------- | --------------------------------------------------------------------------------- |
| `label`  | `string` | The display name of the gang                                                      |
| `grades` | `table`  | A table defining gang grades, including names and other rank-specific attributes. |

**Grades Table Layout**

| Property | Type      | Description                                                          |
| -------- | --------- | -------------------------------------------------------------------- |
| `name`   | `string`  | The name of the grade (e.g., Recruit, Enforcer).                     |
| `isboss` | `boolean` | (Optional) If `true`, this grade is marked as the boss (e.g., Boss). |

**Example: Basic Gang Definition**

This example defines the unemployed gang with a single grade:

```lua
QBShared.Gangs = {
    none = {
        label = 'No Gang', -- Display name
        grades = {
            { name = 'Unaffiliated' } -- Single grade
        }
    }
}
```

**Example: Advanced Gang Definition**

This example defines the lost mc gang with multiple grades, each with specific attributes:

```lua
QBShared.Gangs = {
    lostmc = {
        label = 'The Lost MC', -- Display name
        grades = {
            { name = 'Recruit' }, -- Rank 1
            { name = 'Enforcer' }, -- Rank 2
            { name = 'Shot Caller' }, -- Rank 3
            { name = 'Boss', isboss = true }, -- Rank 4 marked as boss
        },
    },
}
```

### Vehicles

{% hint style="danger" %}
If you want to save a vehicle to the database for ownership, it MUST be defined in the shared vehicles table!
{% endhint %}

* Found in `qb-core/shared/vehicles.lua`

The `Vehicles` table in **qb-core** defines all the vehicles available on your server, including their properties and categories. This table allows you to configure specific attributes for each vehicle to control how they behave in-game.

| Property   | Type              | Description                                                                                                                          |
| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `model`    | `string`          | The spawn code of the vehicle (must match the model name in the game).                                                               |
| `name`     | `string`          | The display name of the vehicle shown to players.                                                                                    |
| `brand`    | `string`          | The brand or manufacturer of the vehicle (e.g., "Maxwell", "Karin").                                                                 |
| `price`    | `number`          | The price of the vehicle in in-game currency.                                                                                        |
| `category` | `string`          | The category of the vehicle (e.g., "compacts", "sports"). Use [GetVehicleClass](https://docs.fivem.net/natives/?_0x29439776AAA00A62) |
| `type`     | `string`          | The type of vehicle (e.g., "automobile", "bike"). Refer to [Vehicle Types](https://docs.fivem.net/natives/?_0x6AE51D4B)              |
| `shop`     | `string \| table` | The shop(s) where the vehicle is available. Can be a single shop (e.g., "pdm") or multiple shops as a table                          |

```lua
QBShared.Vehicles = {
    {
        model = 'asbo',        -- This has to match the spawn code of the vehicle
        name = 'Asbo',         -- This is the display of the vehicle
        brand = 'Maxwell',     -- This is the vehicle's brand
        price = 4000,          -- The price that the vehicle sells for
        category = 'compacts', -- Category of the vehilce, stick with GetVehicleClass() options https://docs.fivem.net/natives/?_0x29439776AAA00A62
        type = 'automobile',   -- Vehicle type, refer here https://docs.fivem.net/natives/?_0x6AE51D4B & here https://docs.fivem.net/natives/?_0xA273060E
        shop = 'pdm',          -- Can be a single shop or multiple shops. For multiple shops for example {'shopname1','shopname2','shopname3'}
    }
}
```

{% hint style="success" %}
We automatically index the QBShared.Vehicles table with the model of the vehicle! So you can access it's properties via `QBCore.Shared.Vehicles[model]`

We also create a table called `QBShared.VehicleHashes` which stores the hash of the vehicle as the key!
{% endhint %}

Sometimes you only have the vehicle hash to work with so you can look it up following the example below!

```lua
local vehicleHash = 12345

local vehicleData = QBShared.VehicleHashes[vehicleHash]
print('Found matching model: '..vehicleData.model)
print(json.encode(vehicleData))

-- alternatively

for model, vehicleData in pairs(QBCore.Shared.Vehicles) do
    if vehicleData.hash == vehicleHash then
        print('Found matching model: '..model)
        print(json.encode(vehicleData))
        break
    end
end
```

### Weapons

{% hint style="warning" %}
Weapons are added in shared/items.lua as well to use as items! This table is only for looking up weapon information via it's hash which is returned via [GetCurrentPedWeapon](https://docs.fivem.net/natives/?_0xB0237302) or similar native function that returns the weapons hash
{% endhint %}

* Found in `qb-core/shared/weapons.lua`

The `Weapons` table in **qb-core** defines all the weapons available on your server. It includes attributes like the weapon's name, label, type, ammo type, and a damage reason for death notifications. This table allows you to manage and customize the weapons players can access.

**Weapon Object Layout**

| Property       | Type     | Description                                                                               |
| -------------- | -------- | ----------------------------------------------------------------------------------------- |
| `name`         | `string` | The internal spawn name of the weapon (e.g., `weapon_pistol`).                            |
| `label`        | `string` | The display name of the weapon shown to players.                                          |
| `weapontype`   | `string` | The type of weapon (e.g., "Pistol", "Shotgun", "Rifle").                                  |
| `ammotype`     | `string` | The type of ammo the weapon uses (e.g., `AMMO_PISTOL`, `AMMO_SHOTGUN`).                   |
| `damagereason` | `string` | A customizable message that appears in kill notifications to describe the cause of death. |

```lua
QBShared.Weapons = {
    [`weapon_pistol`] = { -- Weapon hash (uses compile-time Jenkins hashes)
        name = 'weapon_pistol', -- The internal spawn name of the weapon (e.g., weapon_pistol)
        label = 'Walther P99', -- The display name of the weapon shown to players
        weapontype = 'Pistol', -- The type of weapon (e.g., "Pistol", "Shotgun", "Rifle")
        ammotype = 'AMMO_PISTOL', -- The type of ammo the weapon uses (e.g., AMMO_PISTOL, AMMO_SHOTGUN)
        damageReason = 'Pistoled / Blasted / Plugged / Bust a cap in' -- A customizable message that appears in kill notifications to describe the cause of death
    }
}
```


---

# 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/shared.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.