# qb-doorlock

`qb-doorlock` manages lock states for GTA door entities. Its setup has two independent parts: identifying the actual door in your installed map and defining who may operate it. A visible prompt proves neither that the model is correct nor that the intended access policy is enforced.

**Baseline:** [a019531f](https://github.com/qbcore-fivem/qb-doorlock/tree/a019531fa26f5c1fb39da62eaca4b8b5d033f32b). The [README](https://github.com/qbcore-fivem/qb-doorlock/blob/a019531fa26f5c1fb39da62eaca4b8b5d033f32b/README.md) lists qb-core, qb-input for door creation and qb-minigames for lockpicking. The [manifest](https://github.com/qbcore-fivem/qb-doorlock/blob/a019531fa26f5c1fb39da62eaca4b8b5d033f32b/fxmanifest.lua) loads global configuration and `configs/*.lua` definitions.

## Set up a FiveM door lock

Load the actual map/MLO and required resources on staging. Check startup errors first. Use [Pleb Masters Forge](/docs/guides/pleb-masters-forge) to research a model, but obtain placement and heading from the installed entity, not a catalog screenshot.

Use `/newdoor` with an account allowed by `Config.CommandPermission`, then review the generated definition. `/doordebug` is the documented debugging command. Creation permissions are not the same as permissions to open an existing door; the [upstream command/config reference](https://github.com/qbcore-framework/qb-docs/blob/930c12ec4f60dfbba60253571f1a58980129516d/qbcore-resources/qb-doorlock.md) describes those commands.

Before committing a generated door, inspect:

| Value | What must match your server |
| --- | --- |
| Definition key/door ID | Unique, stable ID used by dependent resources |
| Model and coordinates | The actual door entity in this map revision |
| Heading | The door's intended closed orientation |
| Single or double type | Whether one or two entities make up the opening |
| Interaction distance/text position | Reachable from the intended side without excessive range |
| `locked` | Deliberate initial/default lock state |
| Authorization fields | Your intended access paths, without copied unrelated entries |

For a double door, capture both leaves. Keep only one controller for the same physical door. Do not overwrite existing bank-door IDs: [qb-bankrobbery](/docs/resources/qb-bankrobbery) can depend on their order or identifiers.

## Configuration and authorization

The [pinned server authorization function](https://github.com/qbcore-fivem/qb-doorlock/blob/a019531fa26f5c1fb39da62eaca4b8b5d033f32b/server.lua) returns as soon as an allowed path succeeds. **Job, gang, citizen ID and item access are alternatives, not an automatic combined requirement.** Adding an item field does not make an already-authorized job require that item too.

For a generated door intended to allow police grade 2 and above, the relevant field is:

```lua
authorizedJobs = { ['police'] = 2 },
```

This is a field inside the existing generated definition, not a standalone resource. Remove unintended copied `authorizedGangs`, `authorizedCitizenIDs` or `items` paths when implementing a job-only policy. Also review `allAuthorized`, lockpicking and global administrative access.

| Setting | Meaning at this baseline |
| --- | --- |
| `Config.CommandPermission` | Permission for creating doors |
| `Config.AdminAccess` / `Config.AdminPermission` | Separate optional administrative operating access |
| `authorizedJobs = { ['police'] = 2 }` | Matching internal job with minimum grade 2 |
| `authorizedCitizenIDs` | Another identity-based operating path |
| `needsAllItems` | Combines checks inside item access; does not combine items with a job rule |
| `allAuthorized` | Broad access path that must not be enabled accidentally |

Do not interpret client-side prompt visibility as a server audit. Review the complete handler and your installed modifications before relying on a restriction. A more complex policy, such as job **and** item, needs a deliberately reviewed server-side implementation rather than a copied table with both fields present.

## Persistent state is not the default state

The [config](https://github.com/qbcore-fivem/qb-doorlock/blob/a019531fa26f5c1fb39da62eaca4b8b5d033f32b/config.lua) exposes `Config.PersistentDoorStates`. The server saves states to `saves/doorstates.json` and reloads matching IDs. A persisted state can therefore supersede the default `locked` value when persistence is enabled.

The setting is spelled `Config.PersistentSaveInternal` at this baseline; do not silently rename it to a more natural-looking `Interval` key. Its config comment expresses the interval in milliseconds. Check the consumer and storage errors before changing timing or deleting saved states.

To diagnose a restart mismatch, record the door ID, configured default, persistence setting and stored state. Work on a staging copy. Deleting a whole state file is not a targeted fix for one door and can affect every saved door.

## Troubleshooting doors that will not lock

| Symptom | Inspect first | Distinguishing test |
| --- | --- | --- |
| No prompt | Loaded definition, distance, map startup and model | Inspect the installed entity with debugging enabled |
| Prompt toggles but door still moves | Model/coordinates, door type and competing controller | Test one definition without overlapping controllers |
| Only one leaf behaves correctly | Both entities and their headings | Inspect each leaf, not just the center text |
| Intended police grade is denied | Current internal job and numeric grade | Test just below and at the configured grade |
| Unrelated player can open it | Alternative authorization paths | Review each allow path, not only `authorizedJobs` |
| State differs after restart | Persistence and saved ID | Compare default state with the saved value |
| Door-creation form does not appear | qb-input startup and client errors | Test [qb-input](/docs/resources/qb-input) independently |

Turn debug output off after diagnosis. Do not enable global admin access as a fix for a misconfigured job or inaccessible prompt.

## Update checklist

Use separate staging characters for the permitted grade, a lower grade and an unrelated job. Check both sides of the door, each double-door leaf, lock/unlock, reconnect and a controlled restart. Review robbery scripts before changing any shared door IDs.

Save the code/config diff and prior state file before a persistence experiment. Roll back the specific definition and its intended state, not unrelated player or inventory records. The acceptance matrix is an instruction to test, not a report of completed FiveM runtime tests or proof that every upstream handler is secure.

Continue with [safe updates](/docs/migration/resource-updates), [server authority](/docs/security/server-authority-checklist) or [resource references](/docs/resources).
