# qb-weapons: ammunition, wear and repair

`qb-weapons` integrates QBCore weapons with ammunition, attachments, durability, repair stations and weapon draw/recoil handling. This reference follows [upstream commit 95be254](https://github.com/qbcore-fivem/qb-weapons/tree/95be25450eef743bac1e97482bf6fedec8dfafc3).

## Installation

1. Start `qb-core`, `qb-inventory` and any menu/interaction resources required by your server before `qb-weapons`.
2. Deploy the complete `qb-weapons` script, its locales, `config.lua`, client files and `weaponsnspistol.meta` asset.
3. Verify ammo item names and all weapon definitions against the **installed** QBCore shared item/weapon lists.
4. Test equipping, ammo consumption, attaching components, damage degradation, repair and reconnect on staging.

There is **no** upstream `qb-weapons.sql` in this revision. Do not import community-example `weapon_licenses` or `weapon_attachments` SQL as if it were part of the source. Item metadata and license handling depend on `qb-inventory`, `qb-core` and related cityhall/police resources.

## Actual configuration

The reviewed [`config.lua`](https://github.com/qbcore-fivem/qb-weapons/blob/95be25450eef743bac1e97482bf6fedec8dfafc3/config.lua) defines:

| Key | Purpose |
| --- | --- |
| `Config.ReloadTime` | Randomized reload duration in milliseconds |
| `Config.DurabilityBlockedWeapons` | Weapon IDs excluded from normal durability loss |
| `Config.AmmoTypes` | Item-to-ammo type and amount mapping |
| `Config.Throwables` | Throwable weapon identifiers |
| `Config.WeapDraw` | Draw animation settings |
| `Config.DurabilityMultiplier` | Per-weapon durability rates |
| `Config.WeaponRepairPoints` | Repair station locations |
| `Config.WeaponRepairCosts` | Weapon repair pricing |

~~~lua filename="config.lua"
-- Existing table entries in the upstream config:
Config.AmmoTypes = {
    pistol_ammo = { ammoType = 'AMMO_PISTOL', amount = 30 },
    rifle_ammo = { ammoType = 'AMMO_RIFLE', amount = 30 },
    shotgun_ammo = { ammoType = 'AMMO_SHOTGUN', amount = 10 },
}
~~~

This is an illustrative subset, not a replacement of all ammo types.

## Source event map

The [client](https://github.com/qbcore-fivem/qb-weapons/blob/95be25450eef743bac1e97482bf6fedec8dfafc3/client/main.lua) registers `qb-weapons:client:SetCurrentWeapon`, `UseWeapon`, `AddAmmo`, `EquipTint`, `SetWeaponQuality` and `CheckWeapon`, among others. Server handlers in [`server/main.lua`](https://github.com/qbcore-fivem/qb-weapons/blob/95be25450eef743bac1e97482bf6fedec8dfafc3/server/main.lua) include:

- `qb-weapons:server:RepairWeapon` and `TakeBackWeapon`.
- `qb-weapons:server:UpdateWeaponAmmo`, `SetWeaponQuality` and `UpdateWeaponQuality`.
- `qb-weapons:server:RemoveAttachment` and `removeWeaponAmmoItem`.

An export named `getConfigWeaponAttachments` is registered in the **shared config**. This revision does **not** export `GetWeaponDurability`, `CreateWeapon` or `RegisterWeapon` as a public generic API.

Do not trigger an inventory-changing server event using untrusted client weapon serials, ammo quantities or quality values. The server must verify ownership and allowable mutations independently.

## Repair and licensing boundary

Repair mechanics are part of this resource. The player's permission to *purchase/carry* a weapon is a **separate** cityhall/police/shop metadata workflow; see the [weapon-license guide](/docs/guides/weapon-license). Adding `Config.RequireLicense` from an unrelated fork will not enforce access in this implementation.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Ammo item does nothing | `Config.AmmoTypes`, QBCore shared item and inventory usable-item flow |
| Weapon wear doesn't update | `DurabilityBlockedWeapons` and `DurabilityMultiplier` |
| Attachment not applied | Attachment config, allowed weapon component and item metadata |
| Repair UI inaccessible | Configured `WeaponRepairPoints` and player/job access |
| Quality resets after reconnect | Inventory persistence and weapon metadata |
| No such export `GetWeaponDurability` | Not exported by this version |

## Update checklist

1. Pin `qb-weapons`, `qb-inventory` and `qb-core` resource commits.
2. Test weapon use, ammo, attachments, repairs and metadata persistence.
3. Audit all client-reachable weapon mutation handlers for quantity and ownership checks.
4. Back up player inventory metadata before switching weapon implementations.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-weapons/tree/95be25450eef743bac1e97482bf6fedec8dfafc3) · [Config](https://github.com/qbcore-fivem/qb-weapons/blob/95be25450eef743bac1e97482bf6fedec8dfafc3/config.lua) · [Client events](https://github.com/qbcore-fivem/qb-weapons/blob/95be25450eef743bac1e97482bf6fedec8dfafc3/client/main.lua) · [Server events](https://github.com/qbcore-fivem/qb-weapons/blob/95be25450eef743bac1e97482bf6fedec8dfafc3/server/main.lua)
