# Adding a weapon to QBCore

> Add a custom weapon to QBCore: the exact qb-core/shared/weapons.lua entry, the backtick gotcha, and where the inventory image goes. Copy-paste ready.

Source: https://fam-tools.com/guides/qbcore-weapon-setup · FAM Tools · published 2026-10-25 · updated 2026-10-25 · about 6 min

**Short answer.** Add a custom weapon to QBCore: the exact qb-core/shared/weapons.lua entry, the backtick gotcha, and where the inventory image goes. Copy-paste ready.

QBCore keeps its weapon list in qb-core/shared/weapons.lua, keyed by weapon hash. The syntax is unusual — the key is wrapped in backticks, not quotes — and getting that wrong is the most common reason an otherwise correct entry does nothing.

## The entry

Open qb-core/shared/weapons.lua and add your weapon inside the existing Weapons table. The key is the lowercase weapon name in backticks, which Lua evaluates as the weapon's hash.

*qb-core/shared/weapons.lua*

```lua
QBShared.Weapons = {
    [`weapon_mygun`] = {
        ['name'] = 'weapon_mygun',
        ['label'] = 'My Gun',
        ['weapontype'] = 'Pistols',
        ['ammotype'] = 'AMMO_PISTOL',
        ['damagereason'] = 'Killed',
    },

    -- ... the weapons that were already here
}
```

> **Worth knowing** — Those are backticks, not apostrophes. [`weapon_mygun`] compiles to a hash; ['weapon_mygun'] is a plain string key and QBCore will never match it.

## Choosing weapontype and ammotype

weapontype groups the weapon in menus and decides which animations and stats QBCore applies. ammotype has to match the weapon's AmmoInfo from weapons.meta or reloading breaks. Use these pairings:

- Pistols — AMMO_PISTOL
- Sub Machine Guns — AMMO_SMG
- Rifles — AMMO_RIFLE
- Light Machine Guns — AMMO_MG
- Shotguns — AMMO_SHOTGUN
- Sniper Rifles — AMMO_SNIPER
- Heavy Weapons — AMMO_RPG or AMMO_GRENADELAUNCHER
- Melee Weapons — no ammotype at all
- Thrown Weapons — the weapon's own name as the ammo type

## The inventory image

1. Export a transparent PNG named after the item in lowercase: weapon_mygun.png.
2. Copy it into qb-inventory/html/images/. Some forks use a different path — check where the existing weapon images live and match that.
3. Restart qb-inventory and rejoin, so the NUI reloads its image list.

## If you run ox_inventory on QBCore

Some QBCore-based servers run ox_inventory instead of qb-inventory — officially through Qbox, which keeps QBCore compatibility, or through a community fork. If yours does, skip this guide entirely and register the weapon in ox_inventory/data/weapons.lua instead. Adding it to both produces two competing definitions, and which one wins depends on load order — which is exactly the kind of bug that only appears on a full restart at the worst moment.

## Questions

### My weapon is in shared/weapons.lua but /giveitem says invalid.

Either the key uses quotes instead of backticks, or the name field does not match the key. Both must be the lowercase weapon name, and the weapon must already be streamed into the server.

### Do I need to add ammo as a separate item?

Only if your ammo system uses items. QBCore's stock setup handles ammunition through the weapon's ammotype, so a matching ammotype value is all most servers need.

### Where does damagereason show up?

In the kill feed and death logs. It is cosmetic, but leaving it out makes deaths from that weapon read oddly in logs, so it is worth setting.

## Related

- https://fam-tools.com/guides/add-custom-weapons-to-fivem
- https://fam-tools.com/guides/ox-inventory-weapon-setup
- https://fam-tools.com/guides/fivem-weapon-pink-textures
- https://fam-tools.com/guides/qbox-weapon-setup
- https://fam-tools.com/guides/esx-weapon-setup