# Adding a custom weapon to an ESX server

> Streaming the model, registering the weapon and wiring the item into whichever inventory your ESX server runs. The whole path, in order.

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

**Short answer.** Streaming the model, registering the weapon and wiring the item into whichever inventory your ESX server runs. The whole path, in order.

ESX servers vary more than QBCore ones, because the inventory is a separate choice. The streaming half is identical everywhere; the item half depends on what you run.

## The part that is the same on every ESX server

1. Put the weapon resource in your resources folder, ideally inside a category folder so load order is explicit.
2. Add it to server.cfg with ensure, before your inventory resource.
3. Confirm at boot that it started without an error in the console.
4. Spawn the weapon with an admin command to prove the model and metadata loaded.

If the weapon appears in hand at this point, streaming is done and everything left is inventory work. If it appears as a default pistol, the model did not stream but the definition did.

## If you run ox_inventory

This is the most common setup on a modern ESX server, and it is the simplest: one entry in data/weapons.lua and one PNG in web/images named after the item in lowercase.

*data/weapons.lua*

```lua
['WEAPON_YOURITEM'] = {
    label = 'Your Weapon',
    weight = 1000,
    durability = 0.03,
    ammoname = 'ammo-9',
},
```

## If you run a database-driven inventory

Older ESX setups keep items in a SQL table rather than a Lua file. The weapon still needs a row there, with the name matching the weapon exactly, or the inventory will refuse to hold it even though the weapon works in hand.

> **Worth knowing** — Insert the row and restart, rather than editing the table while the server is running. Most of these inventories read the item list once at start.

## Ammo

A weapon with an ammo type that does not exist on your server can be equipped and never fired. Point the weapon at an ammo item you already have rather than inventing a new one, unless you are prepared to add and distribute that item too.

## Questions

### Does this work on ESX Legacy?

Yes. The weapon resource is a plain addon weapon and does not depend on the framework version. Only the item registration differs between setups.

### Do I have to edit weapons.meta?

Only to change how the weapon behaves — damage, range, recoil. To simply add it, the metadata that ships with it is enough.

### Where do I put the inventory image on ESX?

Wherever your inventory keeps them. ox_inventory uses web/images; older ESX inventories usually use an html/img folder. The name must match the item.

## 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/weapon-not-showing-in-inventory