# QBCore Core Object

The QBCore core object is the main API surface exposed by `qb-core`.
Cache it once in your resource and request only the sections you need.

![Core Object exports, functions and shared definitions](/diagrams/core-object.svg)

*Conceptual diagram; verify the behavior against your installed resource version.*

## Get the full core object

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

The full object can expose framework sections such as:

| Section | Purpose |
| --- | --- |
| `Functions` | Client- or server-side helper functions for the current runtime |
| `Shared` | Shared items, jobs, gangs, vehicles, weapons, locations and helpers |
| `Config` | Current core configuration |
| `Commands` | Server command registry and helpers |
| `Players` | Server-side connected-player objects |

Not every section is meaningful on both client and server. Treat client and server APIs as separate
surfaces.

At the reviewed core commit, `GetCoreObject(filters)` copies only truthy top-level keys requested by
name. The source annotation lists `Config`, `Shared`, `ClientCallbacks`, `ServerCallbacks`,
`PlayerData`, `Functions`, `Players`, `PlayersByCitizenId`, `Player_Buckets`, `Entity_Buckets`,
`UsableItems`, and `Commands`. Keys unavailable on the current client or server side are omitted.

## Filter the core object

When a resource only needs part of the core object, pass an array of section names:

```lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })
```

Or:

```lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions', 'Shared' })
```

This keeps resource dependencies explicit and avoids importing framework tables your script never
uses.

A common server-side pattern:

```lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions', 'Commands', 'Shared' })
```

## Direct function exports

Current QBCore also exposes core functions as exports. That is useful when a server resource only
needs one or two functions and does not need a cached core object.

For example:

```lua
local Player = exports['qb-core']:GetPlayer(source)
if not Player then return end
```

The exact exported function set follows the functions available in the current core runtime. Do not
assume an inventory helper is part of `qb-core`: inventory operations belong to the installed
inventory resource.

For the current server function surface, see
[Server Functions](/docs/api/server-functions).

## Read shared definitions

You can access shared data through a filtered core object:

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

local water = QBCore.Shared.Items['water_bottle']
if water then
    print(water.label)
end
```

Or use the dedicated `GetShared` export:

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

See [Shared Data](/docs/core/shared) for supported namespaces and
[Shared Mutation Exports](/docs/core/shared-exports) for server-side runtime mutation helpers.

## Server example: resolve a player

```lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })

RegisterNetEvent('myresource:server:inspectJob', function()
    local src = source
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return end

    local job = Player.PlayerData.job
    print(('%s is %s grade %s'):format(
        Player.PlayerData.citizenid,
        job.name,
        job.grade.level
    ))
end)
```

The server owns authoritative player state. Never accept a client-provided citizen ID, job,
permission, balance or price as proof of authorization.

## Server example: register a command

```lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions', 'Commands' })

QBCore.Commands.Add('routecount', 'Show active routes', {}, false, function(source)
    QBCore.Functions.Notify(source, ('Active routes: %d'):format(countRoutes()), 'primary')
end, 'admin')
```

The permission argument is ACE-backed. See
[Commands API](/docs/api/commands) and
[Admin permissions](/docs/guides/how-to-become-admin).

## Client example: read local player data

```lua
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })

RegisterNetEvent('QBCore:Client:OnPlayerLoaded', function()
    local data = QBCore.Functions.GetPlayerData()
    if not data or not data.citizenid then return end

    print(data.citizenid)
end)
```

Client-side player data is a synchronized view for UI and gameplay presentation. Server-side code
must still validate protected actions.

## Do not wait for `GetCoreObject()` in a loop

A normal resource that declares and starts after `qb-core` can cache the export at file load time:

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

If that call fails, fix the manifest dependency or resource start order rather than adding a polling
loop that hides a broken dependency.

See [Resource load order](/docs/troubleshooting/resource-load-order).

## Common mistakes

### Importing the full core object for one function

Prefer a filtered object or direct export when the resource only needs a narrow API.

### Treating inventory methods as core methods

Current QBCore delegates inventory behavior to the installed inventory resource. Use that resource's
documented exports for item mutation.

### Using client data for authorization

Client `PlayerData` can guide presentation. Permission, money, ownership, proximity and job checks
for protected actions belong on the server.

### Copying an API from an old fork

QBCore forks can diverge significantly. Pin examples to the deployed repository and commit when
building production resources.

## Related documentation

- [Player Data](/docs/core/player-data)
- [Shared Data](/docs/core/shared)
- [Client Functions](/docs/api/client-functions)
- [Server Functions](/docs/api/server-functions)
- [Commands API](/docs/api/commands)
- [Safe Server Events](/docs/security/safe-server-events)

## Sources

- [Official core-object documentation](https://github.com/qbcore-framework/qb-docs/blob/main/qb-core/core-object.md)
- [Pinned qb-core source](https://github.com/qbcore-fivem/qb-core/tree/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf)
- [Pinned server exports](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/exports.lua)
- [Pinned server functions](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua)

Last verified against current upstream files: **2026-09-27**.
