# qb-prison: inmate state and prison break flow

The official `qb-prison` works with `qb-policejob`, QBCore player metadata and `qb-inventory` to manage jail time, inmate belongings, prison jobs and prison-break alerts. Verified against [commit 4ac6a67](https://github.com/qbcore-fivem/qb-prison/tree/4ac6a6752bf423cadac2e3a4c110b6976e756cda).

## Setup

1. Start `qb-core` and `qb-inventory` before prison-related resources.
2. Configure `qb-prison` and the installed `qb-policejob` to use the same jail flow.
3. Keep `Config.UseTarget` aligned with the `UseTarget` convar if using target interactions.
4. Verify `Config.Locations`, `Config.Jobs` and `Config.Uniforms` in the actual [config](https://github.com/qbcore-fivem/qb-prison/blob/4ac6a6752bf423cadac2e3a4c110b6976e756cda/config.lua).
5. Test jailing, inventory custody, working off time, release and reconnect with test characters.

## Player state and inventory

| Data / event | Role |
| --- | --- |
| `PlayerData.metadata.injail` | Time remaining in jail |
| `PlayerData.metadata.jailitems` | Saved items during custody |
| `prison:server:SetJailStatus` | Updates jail metadata; source code also changes a jailed player's job to unemployed |
| `prison:server:SaveJailItems` | Saves/clears inventory while jailed |
| `prison:server:GiveJailItems` | Attempts item return; behavior differs when the `escaped` argument is true |
| `prison:server:ResetJailItems` | Clears saved jail item metadata |

Those handlers are **network events**, not external server exports. In the reviewed [server source](https://github.com/qbcore-fivem/qb-prison/blob/4ac6a6752bf423cadac2e3a4c110b6976e756cda/server/main.lua), `SetJailStatus` accepts a jail time directly and does not perform a caller-role authorization check. Never expose it as an unrestricted jailing/un-jailing integration; enforce police/admin authority in a trusted server-side workflow.

## Prison activity and alarms

The server source also registers `prison:server:SecurityLockdown`, `SetGateHit`, `CheckRecordStatus`, `JailAlarm` and `CheckChance`. These implement internal prison-break and item-reward behavior, not a general permission-safe administration API. Configure the corresponding coordinates and test the flow with multiple clients.

The prison jobs list lives under `Config.Jobs` (the bundled example includes `electrician`) and its location entries live under `Config.Locations.jobs`.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Player stays jailed after reconnect | `metadata.injail` persistence and jail-status flow |
| Confiscated items do not return | `metadata.jailitems`, `qb-inventory` and release/escape path |
| Prison outfit does not apply | Configured `Uniforms` and actual appearance resource |
| Police do not receive alerts | Police job, `onduty` and prison-break server events |
| Job unexpectedly changes | `SetJailStatus` resets non-unemployed jobs when jailing |
| Jail time can be changed without authority | Audit all exposed event paths and server-side authorization |

## Update checklist

1. Record installed `qb-prison`, `qb-policejob` and `qb-inventory` commits.
2. Test detention and release with two different players and persistence across reconnect.
3. Verify no untrusted client can arbitrarily call a privileged jail-time or alarm operation.
4. Test item restoration and rollback on a staging database.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-prison/tree/4ac6a6752bf423cadac2e3a4c110b6976e756cda) · [Server events](https://github.com/qbcore-fivem/qb-prison/blob/4ac6a6752bf423cadac2e3a4c110b6976e756cda/server/main.lua) · [Config](https://github.com/qbcore-fivem/qb-prison/blob/4ac6a6752bf423cadac2e3a4c110b6976e756cda/config.lua)

Related: [qb-policejob](/docs/resources/qb-policejob), [safe server events](/docs/security/safe-server-events).
