# Adding a weapon to ox_inventory

> Add a custom weapon to ox_inventory: the exact data/weapons.lua entry, what every field does, where the item image goes and the mistakes that break it.

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

**Short answer.** Add a custom weapon to ox_inventory: the exact data/weapons.lua entry, what every field does, where the item image goes and the mistakes that break it.

ox_inventory keeps weapons in their own table, separate from ordinary items, and it expects the weapon to already exist in the game. If you have not streamed the weapon into the server yet, do that first — nothing here will make an unstreamed weapon appear.

## Where the entry goes

Open ox_inventory/data/weapons.lua. It exports three tables — Weapons, Ammo and Components. Yours goes in Weapons, keyed by the uppercase weapon name exactly as it appears in weapons.meta.

*ox_inventory/data/weapons.lua*

```lua
return {
    Weapons = {
        ['WEAPON_MYGUN'] = {
            label = 'My Gun',
            weight = 1200,
            durability = 0.03,
            ammoname = 'ammo-9',
        },

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

Add your entry inside the existing Weapons table rather than creating a second one. A duplicated table silently replaces the first, which is how people accidentally delete every stock weapon on their server.

## What each field does

- label — the name players see. This is the only field that is purely cosmetic.
- weight — grams. A pistol is around 1200, a rifle 3300, a machine gun 6000. It counts against the player's carry limit, so keep it proportionate to the rest of your list.
- durability — how much condition is lost per shot. 0.03 is a normal firearm; 0.1 suits melee weapons, which lose condition per swing rather than per bullet.
- ammoname — which ammo item feeds it: ammo-9, ammo-rifle, ammo-shotgun, ammo-sniper or ammo-rocket. Omit it entirely for melee and thrown weapons.
- throwable — set true for grenades and similar, and leave durability out.

> **Worth knowing** — Pick ammoname to match the weapon's AmmoInfo in weapons.meta. If the meta says AMMO_RIFLE and you write ammo-9, players will hold ammunition the gun refuses to load.

## The item image

1. Render or export a transparent PNG of the weapon, 512x512 is plenty.
2. Name it exactly like the item key — WEAPON_MYGUN becomes WEAPON_MYGUN.png, the same uppercase naming ox_inventory’s own images use. On a Linux server the case must match.
3. Put it in ox_inventory/web/images/.
4. Restart ox_inventory, then hard-refresh the NUI in game (or restart the client) so the browser cache lets go of the old image list.

A question mark or blank square in the slot almost always means the filename does not match the item name. Wrong capitalisation (it works on Windows, then breaks on a Linux host), a .jpg extension, or a trailing space are the usual culprits — check the actual file on disk rather than trusting your memory of it.

## Checking it worked

Give yourself the weapon with your admin command and look at three things: it appears in the inventory grid, it shows the correct image, and the weight matches what you set. If it appears but weighs nothing, ox_inventory did not read your entry — you have almost certainly edited a copy of weapons.lua rather than the one the resource actually loads.

## Questions

### Do I add weapons to items.lua as well?

No. Weapons live only in data/weapons.lua. Adding a weapon to items.lua creates a separate, unusable item with the same name and causes confusing duplicates.

### Why does my weapon show but weigh nothing and have no label?

ox_inventory did not find your entry and fell back to defaults. The key must be the uppercase WEAPON_ name in quotes and square brackets, and it must be inside the existing Weapons table.

### Can I use ox_inventory on QBCore?

Officially ox_inventory supports ox_core, ESX, Qbox and ND_Core, not plain QBCore — QBCore-based servers run it through Qbox or a community fork. If you run ox_inventory, follow this guide and ignore the qb-core weapon list entirely — registering the weapon in both places causes conflicting definitions.

### How do I add attachments or components?

Components go in the Components table of the same file, each naming the weapons it fits. The component itself also has to exist as a streamed model and be declared in weaponcomponents.meta.

## Related

- https://fam-tools.com/guides/add-custom-weapons-to-fivem
- https://fam-tools.com/guides/qbcore-weapon-setup
- https://fam-tools.com/guides/fivem-weapon-item-images
- https://fam-tools.com/guides/qbox-weapon-setup