# QBCore Weapon License

The current QBCore weapon-license flow spans multiple resources:

1. `qb-policejob` grants or revokes the **permission state**.
2. `qb-core` stores that state in `PlayerData.metadata.licences.weapon`.
3. `qb-cityhall` lets an eligible player buy the **hard-copy license item**.
4. `qb-shops` can require the `weapon` license before selling configured products.

The metadata permission and the physical license item are different things.

## Default metadata state

Current `qb-core` initializes license metadata like this:

```lua
licences = {
    driver = true,
    business = false,
    weapon = false
}
```

So a new character does not have weapon-license permission by default.

Read it server-side from:

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

local hasWeaponLicense = Player.PlayerData.metadata.licences.weapon == true
```

Do not trust a client-provided Boolean for purchase authorization.

## Grant a weapon license

Current `qb-policejob` documents:

```text
/grantlicense [id] [license]
```

For a weapon license:

```text
/grantlicense 12 weapon
```

The command is available to police who meet `Config.LicenseRank`. The official resource defaults
that threshold to grade 2.

## Revoke a weapon license

Current command documentation uses:

```text
/revokelicense [id] [license]
```

Example:

```text
/revokelicense 12 weapon
```

> **Legacy docs use a different command**
> Older QBCore prose still contains `/revoke [id] [licenseType]`. The current command reference and
> qb-policejob documentation use `/revokelicense`. Verify the command registered by the exact
> qb-policejob commit you deploy.

Revoking metadata permission does not automatically remove a previously issued hard-copy item from
the player's inventory. Decide explicitly whether your server wants that separate behavior.

## Buy the hard-copy license at City Hall

Current `qb-cityhall` filters available license documents against the player's
`metadata.licences` table. Its server handler includes a `weaponlicense` document type and creates
the item only after the configured City Hall checks and payment path succeed.

That means the usual flow is:

```text
Police grants metadata permission
        ↓
metadata.licences.weapon = true
        ↓
City Hall exposes the weapon-license document
        ↓
Player purchases the hard-copy item
```

See [qb-cityhall](/docs/resources/qb-cityhall) for resource-specific configuration.

## Require the license in qb-shops

The current `qb-shops/config.lua` uses the string field **`requiredLicense`**:

```lua
{ name = 'weapon_pistol', price = 2500, amount = 5, requiredLicense = 'weapon' }
```

The current default weapons product list applies the same requirement to licensed ammunition and
several pistols.

> **Do not copy the old Boolean key**
> Older documentation examples use `requiresLicense = true`. Current qb-shops uses
> `requiredLicense = 'weapon'`. Pin your configuration to the version you actually deploy.

## Grant weapon permission to every new character

If your game design intentionally gives every new character permission, change the default in the
core configuration/source used by your deployed revision so that:

```lua
weapon = true
```

Do this only if it matches your server rules. Existing characters already stored in the database may
retain their existing metadata and therefore require a migration rather than merely changing a
default.

## Custom license types

The license table is extensible, but all participating resources must agree on the same string.

For example, if you introduce `hunting`:

```lua
PlayerData.metadata.licences.hunting = true
```

then police/admin issuance, City Hall documents, shops and any custom resource must all use exactly
that key. Avoid inventing multiple spellings for the same permission.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `/grantlicense` is missing | Confirm `qb-policejob` is installed, started and matches the documented revision. |
| Officer cannot grant it | Check police job, duty/grade logic and `Config.LicenseRank`. |
| City Hall does not show the document | Inspect `metadata.licences.weapon` and the City Hall license config. |
| Player has the card but shop refuses purchase | A physical item is not the same as the metadata permission; inspect the current metadata and shop config. |
| Shop sells guns without a license | Add `requiredLicense = 'weapon'` to the products that should be restricted. |
| Old config stopped working after update | Compare `requiresLicense = true` with the current `requiredLicense = 'weapon'` schema. |

## Related documentation

- [qb-policejob](/docs/resources/qb-policejob)
- [qb-cityhall](/docs/resources/qb-cityhall)
- [qb-shops](/docs/resources/qb-shops)
- [Player Data](/docs/core/player-data)
- [Resource update conflicts](/docs/troubleshooting/resource-update-conflicts)

## Sources

- [Current qb-core player defaults](https://github.com/qbcore-fivem/qb-core/blob/main/config.lua)
- [Current qb-policejob documentation](https://github.com/qbcore-framework/qb-docs/blob/main/qbcore-resources/qb-policejob.md)
- [Current QBCore command reference](https://github.com/qbcore-framework/qb-docs/blob/main/qb-core/commands.md)
- [Current qb-cityhall server implementation](https://github.com/qbcore-fivem/qb-cityhall/blob/main/server.lua)
- [Current qb-shops config](https://github.com/qbcore-fivem/qb-shops/blob/main/config.lua)
- [Legacy miscellaneous weapon-license guide](https://github.com/qbcore-framework/qb-docs/blob/main/guides/miscellaneous-guides.md)

Verified **2026-09-27**.
