# QBCore shared data

`qb-core` loads its shared definitions before client and server scripts. At the verified commit the
manifest loads locale data, `shared/main.lua`, utility functions, items, jobs, vehicles, gangs,
weapons, and locations.

## Read a namespace

```lua
local policeJob = exports['qb-core']:GetShared('Jobs', 'police')
local allItems = exports['qb-core']:GetShared('Items')
```

`GetShared(namespace, item)` returns the whole namespace when `item` is omitted, one entry when
it is supplied, and `nil` for an unknown namespace/key.

The source annotation currently names these namespaces:

| Namespace | Typical value |
| --- | --- |
| `Vehicles` | vehicle definitions |
| `VehicleHashes` | hash lookup generated by the vehicle data |
| `Items` | item definitions |
| `Gangs` | gang definitions |
| `Jobs` | job definitions |
| `Locations` | shared coordinates/locations |
| `Weapons` | weapon definitions |
| `StarterItems` | starter inventory definitions |

## Read through the core object

```lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Shared' })
local water = QBCore.Shared.Items['water_bottle']
```

Treat these tables as framework-owned data. For supported server-side runtime mutations use the
[shared mutation exports](/docs/core/shared-exports) rather than editing a cached client table.

## Shared utility functions

Current `shared/functions.lua` exposes these functions on both sides:

| Function | Signature | Return / behavior |
| --- | --- | --- |
| `RandomStr` | `RandomStr(length)` | Random alphabetic string; empty string for non-positive length |
| `RandomInt` | `RandomInt(length)` | Random numeric string; empty string for non-positive length |
| `SplitStr` | `SplitStr(str, delimiter)` | Array of string segments |
| `Trim` | `Trim(value)` | Trimmed string, or `nil` for a falsy value |
| `FirstToUpper` | `FirstToUpper(value)` | String with first lowercase character uppercased, or `nil` |
| `Round` | `Round(value, numDecimalPlaces)` | Rounded number |
| `ChangeVehicleExtra` | `ChangeVehicleExtra(vehicle, extra, enable)` | Applies a vehicle-extra state; no return |
| `IsFunction` | `IsFunction(value)` | Boolean for Lua/CFX function references |
| `SetDefaultVehicleExtras` | `SetDefaultVehicleExtras(vehicle, config)` | Resets extras then applies the config; no return |

The vehicle helpers call GTA natives, so although the file is shared, invoke them only in a context
where those entity natives and handles are valid.

## Starter items

At this commit `QBCore.Shared.StarterItems` contains `phone`, `id_card`, and
`driver_license`, each with amount `1`. Do not copy that list into a migration and assume it
matches a fork; inspect the deployed shared file.

## Runtime mutation boundary

The shared tables are ordinary Lua tables, but supported server exports exist for adding, updating,
and removing jobs, gangs, and items. Those exports notify clients after a successful mutation.
Runtime changes do not persist back into the source files, so maintain the deployed definitions as
the source of truth across restarts.

## Sources

- [shared/main.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/shared/main.lua)
- [shared/functions.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/shared/functions.lua)
- [fxmanifest.lua](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/fxmanifest.lua)
