QBCore Frameworkqbcore.netCommunity docs
On this page

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

  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 defines:

KeyPurpose
Config.ReloadTimeRandomized reload duration in milliseconds
Config.DurabilityBlockedWeaponsWeapon IDs excluded from normal durability loss
Config.AmmoTypesItem-to-ammo type and amount mapping
Config.ThrowablesThrowable weapon identifiers
Config.WeapDrawDraw animation settings
Config.DurabilityMultiplierPer-weapon durability rates
Config.WeaponRepairPointsRepair station locations
Config.WeaponRepairCostsWeapon 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: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. Adding Config.RequireLicense from an unrelated fork will not enforce access in this implementation.

Troubleshooting

SymptomCheck
Ammo item does nothingConfig.AmmoTypes, QBCore shared item and inventory usable-item flow
Weapon wear doesn't updateDurabilityBlockedWeapons and DurabilityMultiplier
Attachment not appliedAttachment config, allowed weapon component and item metadata
Repair UI inaccessibleConfigured WeaponRepairPoints and player/job access
Quality resets after reconnectInventory persistence and weapon metadata
No such export GetWeaponDurabilityNot 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 · Config · Client events · Server events

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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website