Updated 2026-10-11 · 3 min read
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.
Installation
- Start
qb-core,qb-inventoryand any menu/interaction resources required by your server beforeqb-weapons. - Deploy the complete
qb-weaponsscript, its locales,config.lua, client files andweaponsnspistol.metaasset. - Verify ammo item names and all weapon definitions against the installed QBCore shared item/weapon lists.
- 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 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 |
-- 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 registers qb-weapons:client:SetCurrentWeapon, UseWeapon, AddAmmo, EquipTint, SetWeaponQuality and CheckWeapon, among others. Server handlers in server/main.lua include:
qb-weapons:server:RepairWeaponandTakeBackWeapon.qb-weapons:server:UpdateWeaponAmmo,SetWeaponQualityandUpdateWeaponQuality.qb-weapons:server:RemoveAttachmentandremoveWeaponAmmoItem.
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. 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
- Pin
qb-weapons,qb-inventoryandqb-coreresource commits. - Test weapon use, ammo, attachments, repairs and metadata persistence.
- Audit all client-reachable weapon mutation handlers for quantity and ownership checks.
- Back up player inventory metadata before switching weapon implementations.
Sources
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
