Add-on weapons in QBCore

This guide covers QBCore with qb-inventory and qb-weapons. Keep your installed resource versions together; third-party inventories may use different registration files. For QBox with ox_inventory, follow the QBox weapon guide.

1. Install and identify the weapon

Back up the files you will edit. Copy the full FiveM add-on resource into resources/[weapons]/example_weapon. Keep the original folder structure and fxmanifest.lua, including any audio or component files. Check that the asset supports your server's Legacy or Enhanced runtime.

Find the weapon identifier in the <Name> field of its CWeaponInfo entry in weapons.meta, or in the author's instructions when metadata is protected. A model filename or store listing title is not the weapon identifier.

Add this line to your existing startup configuration, using the actual resource folder name:

ensure example_weapon

Keep qb-core, qb-inventory and qb-weapons in their established dependency order. You are adding a streamed resource, not replacing that startup configuration. See installing a resource for the download and folder steps, and the Cfx.re manifest reference for resource loading.

2. Add the inventory item

Open qb-core/shared/items.lua and insert this entry inside QBShared.Items. Leave all existing items and the table's outer braces in place:

weapon_examplepistol = {
    name = 'weapon_examplepistol',
    label = 'Example Pistol',
    weight = 1000,
    type = 'weapon',
    ammotype = 'AMMO_PISTOL',
    image = 'weapon_examplepistol.png',
    unique = true,
    useable = false,
    description = 'A custom add-on pistol.',
},

Use a lowercase inventory key and name, matching the weapon identifier. type = 'weapon' selects the weapon handling path. Keep unique = true so weapons can hold their own serial number, ammunition and quality. The spelling useable matches QBCore's schema; the standard pistol uses false because the inventory has separate weapon handling. Compare the official shared items.

Copy your PNG to this location, matching the image field and filename case:

qb-inventory/html/images/weapon_examplepistol.png

The sample weight and description are yours to adjust.

3. Register the weapon hash

Add the following entry inside QBShared.Weapons in qb-core/shared/weapons.lua:

[`weapon_examplepistol`] = {
    name = 'weapon_examplepistol',
    label = 'Example Pistol',
    weapontype = 'Pistol',
    ammotype = 'AMMO_PISTOL',
    damagereason = 'Shot',
},

The backticks are FiveM Lua's hash syntax. Do not replace this key with a quoted string: the weapon registry is indexed by hash. ammotype must agree with your weapon's metadata and its inventory entry. See the official weapon registry.

4. Set durability and ammunition

In qb-weapons/config.lua, add a matching key inside the existing Config.DurabilityMultiplier table:

weapon_examplepistol = 0.15,

This is a sample wear setting. The current qb-weapons implementation reads this value when reducing quality; an omitted entry can cause an arithmetic error.

For a normal AMMO_PISTOL weapon, the standard pistol_ammo item is handled by Config.AmmoTypes. Check your installed qb-weapons configuration before selecting a different ammunition type. Adding an inventory item named after arbitrary ammunition is not enough to implement reloading.

Melee weapons, including axes

For an axe, add its own entry to QBShared.Items with type = 'weapon', ammotype = nil, unique = true, useable = false and an image such as weapon_exampleaxe.png. Use the actual lowercase weapon name in both item fields.

Then add its hash entry to QBShared.Weapons:

[`weapon_exampleaxe`] = {
    name = 'weapon_exampleaxe',
    label = 'Example Axe',
    weapontype = 'Melee',
    ammotype = nil,
    damagereason = 'Struck with an axe',
},

Give it a durability entry such as weapon_exampleaxe = 0.15 in the same multiplier table. Skip ammo items and reloading. Compare your server's existing weapon_battleaxe entries when adapting the examples.

5. Restart and test as an administrator

Back up the edited files, perform a full server restart and reconnect so shared tables and client weapon data reload together. Use the inventory's administrator-only giveitem command, replacing 12 with your current player ID:

/giveitem 12 weapon_examplepistol 1
/giveitem 12 pistol_ammo 1

For the axe, use /giveitem 12 weapon_exampleaxe 1 instead. Equip through qb-inventory, use the ammo item for the pistol, and check firing or melee attacks. Holster and re-equip, then reconnect and check that the weapon, ammunition and quality persist.

Shops, crafting recipes, police armouries and attachments have their own configuration. Add those only after basic inventory use works. A custom attachment must be registered by the asset and mapped in your weapon system; a default pistol attachment is not automatically compatible.

Troubleshooting

Keep these edits in your server's version control so a framework update does not silently overwrite them. For an ESX server, use the ESX guide. Include your inventory version and console error when asking for support.