# qb-core

`qb-core` is the central QBCore framework resource. It owns the core object, player lifecycle and
persistence, shared definitions, callbacks, commands, permissions and framework events used by the
rest of the ecosystem.

This page is an orientation map. Use the dedicated API pages for exact current signatures.

## Install and start

The official txAdmin recipe installs `qb-core` and imports the QBCore schema. For a normal QBCore
deployment, prefer that recipe over manually assembling a server from unrelated forks.

The generated resource order starts the core before the `[qb]` resource group:

```cfg
ensure qb-core
ensure [qb]
```

See [QBCore server.cfg](/docs/installation/server-config) and
[Resource load order](/docs/troubleshooting/resource-load-order).

## Core object

Client or server resources can cache the core object:

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

Request only the sections you need when practical:

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

See [Core Object](/docs/core/core-object) for filtering, direct function exports and client/server
boundaries.

## Player data and methods

Server code gets an authoritative connected player object with:

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

print(Player.PlayerData.citizenid)
print(Player.PlayerData.job.name)
```

Money, job, gang and metadata changes should go through the player methods exposed by the deployed
core revision. Inventory item methods are added by `qb-inventory` when that resource is running;
do not treat inventory behavior as permanently owned by `qb-core`.

See [Player Data](/docs/core/player-data) and
[Server Functions](/docs/api/server-functions).

## Shared definitions

`qb-core/shared/` contains the framework's shared definitions such as items, jobs, gangs, vehicles,
weapons and locations.

Read them through `QBCore.Shared` or the current shared export surface:

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

See [Shared Data](/docs/core/shared) and
[Shared Mutation Exports](/docs/core/shared-exports).

## Functions

The current core separates client and server helper functions.

- [Client Functions](/docs/api/client-functions)
- [Server Functions](/docs/api/server-functions)

On the server, current `QBCore.Functions` includes player lookup, callbacks, usable-item handling,
permissions, routing buckets, vehicle helpers and other framework utilities. Current functions are
also exported by name from the core server runtime.

Do not copy a function list from an old fork: check the deployed source revision.

## Events

Core lifecycle and synchronization events are documented separately:

- [Client Events](/docs/api/client-events)
- [Server Events](/docs/api/server-events)
- [qb-core events reference](/docs/resources/qb-core/events)

An event emitted by `qb-inventory`, `qb-policejob` or another resource is not a qb-core event just
because it uses QBCore data.

## Commands and permissions

`QBCore.Commands.Add` registers framework commands and integrates with the ACE-backed permission
model.

See:

- [Commands API](/docs/api/commands)
- [Become Admin](/docs/guides/how-to-become-admin)
- [Admin Commands](/docs/guides/admin-commands)

Current default permission groups are `god`, `admin` and `mod`, configured in
`QBCore.Config.Server.Permissions`.

## Database ownership

The repository includes `qbcore.sql`, which defines the core schema used by the recipe. Do not
invent additional core tables because a third-party resource happens to use them.

See [Database guide](/docs/database) and [Core schema](/docs/database/core-schema).

## Common integration pattern

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

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

    -- Validate protected state on the server before changing it.
end)
```

For networked actions, follow the [Safe Server Events](/docs/security/safe-server-events) and
[Server Authority Checklist](/docs/security/server-authority-checklist).

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `No such export GetCoreObject` | Confirm the correct `qb-core` resource is installed and started before the caller. |
| A function from a tutorial is nil | Compare the tutorial with your deployed qb-core revision; APIs change. |
| Inventory methods are missing | Confirm `qb-inventory` is running and that your revision adds those player methods. |
| Admin command denied | Inspect ACE principals and QBCore permission inheritance. |
| Player data is nil on client startup | Wait for the player lifecycle rather than assuming character data exists before load. |

## Sources

- [qb-core repository](https://github.com/qbcore-fivem/qb-core)
- [qb-core config](https://github.com/qbcore-fivem/qb-core/blob/main/config.lua)
- [Server functions](https://github.com/qbcore-fivem/qb-core/blob/main/server/functions.lua)
- [Server exports](https://github.com/qbcore-fivem/qb-core/blob/main/server/exports.lua)
- [Server events](https://github.com/qbcore-fivem/qb-core/blob/main/server/events.lua)
- [Official QBCore docs source](https://github.com/qbcore-framework/qb-docs)

Verified against current upstream source on **2026-09-27**.
