Add-on weapons in ESX

An add-on weapon needs its game files loaded and its ownership registered with your server's weapon system. On ESX, that second step depends on which inventory you run.

This guide covers ESX Legacy's built-in loadout and an existing ESX + ox_inventory installation. Follow the matching alternative. Ox replaces the loadout with weapon items, so the two registration and grant methods are different. Other inventories need their own integration instructions. Ox Inventory's ESX integration explains that distinction.

Load the weapon resource

Back up the files you will edit, then follow Installing a resource. Put the supplied resource in your server's resources directory, keeping its fxmanifest.lua, metadata and streamed files together. Preserve the author's manifest and dependencies; do not replace it with a generic manifest.

Add its startup line before your existing framework and inventory entries. Keep their dependencies and established order intact.

ensure example_weapon
# Your existing framework and inventory startup entries follow.

Confirm the download supports your server's FiveM game build. If its metadata is protected, use the spawn identifier in the author's installation instructions. Register only the weapon you actually installed; the pistol and axe below illustrate two different types.

Alternative A: ESX Legacy's built-in loadout

In current ESX Legacy, open es_extended/shared/config/weapons.lua. Insert the following entries inside the existing Config.Weapons table, preserving its other entries and surrounding braces. This matches the structure in ESX's weapon configuration. Older releases may place this table elsewhere; locate Config.Weapons in your installed es_extended rather than creating an unused file.

-- Add inside Config.Weapons = { ... }
{
    name = 'WEAPON_EXAMPLEPISTOL',
    label = 'Example Pistol',
    ammo = { label = 'Rounds', hash = joaat('AMMO_PISTOL') },
    components = {},
},
{
    name = 'WEAPON_EXAMPLEAXE',
    label = 'Example Axe',
    components = {},
},

The firearm example assumes the supplied weapon uses AMMO_PISTOL. Match the actual metadata when it uses another ammo type. A melee weapon does not need an ammo entry. Add attachments or tint options only when the download supports them; an empty components table is sufficient for this example.

Restart the full server and reconnect before testing. From an account already authorized for ESX's giveweapon command, replace 12 with your test character's current server ID:

/giveweapon 12 WEAPON_EXAMPLEPISTOL 24
/giveweapon 12 WEAPON_EXAMPLEAXE 0

The last argument is the ammunition count. ESX's command implementation grants through xPlayer.addWeapon, which is the documented loadout API. A generic SQL item entry is not this loadout registration. Inventory thumbnails depend on your UI; the ox image folder below does not apply to the built-in loadout.

Alternative B: ESX with ox_inventory

Use this section when ox_inventory already manages your ESX inventory. Preserve that integration. Current ESX automatically detects ox_inventory in its main configuration; do not toggle Config.CustomInventory just to install a weapon.

Open ox_inventory/data/weapons.lua and insert these entries inside its existing Weapons table. Preserve the separate Ammo and Components tables. Weapons belong here, rather than being duplicated in data/items.lua. The upstream weapon definitions show the supported structure.

-- Add inside Weapons = { ... }
['WEAPON_EXAMPLEPISTOL'] = {
    label = 'Example Pistol',
    weight = 1000,
    durability = 0.1,
    ammoname = 'ammo-9',
},
['WEAPON_EXAMPLEAXE'] = {
    label = 'Example Axe',
    weight = 2000,
    durability = 0.1,
},

Weights and durability are example balance values. ammo-9 references an existing ox ammo item; choose the item appropriate to your installed firearm. It does not change the weapon's underlying game metadata. Omit ammoname for the melee weapon.

With ox's default image path, add these PNG files, matching the uppercase weapon keys exactly:

ox_inventory/web/images/WEAPON_EXAMPLEPISTOL.png
ox_inventory/web/images/WEAPON_EXAMPLEAXE.png

If your server uses a custom image host, upload them there instead. The inventory image lookup uses the configured image path and item name unless an image override is supplied.

After a full server restart and reconnect, use ox's existing authorized admin command:

/giveitem 12 WEAPON_EXAMPLEPISTOL 1
/giveitem 12 ammo-9 24
/giveitem 12 WEAPON_EXAMPLEAXE 1

Here the last argument is the item quantity, not ammunition loaded into the weapon. Equip the pistol and reload using its ammo item. Ox's give-item command is restricted to group.admin; keep that restriction. Do not use ESX's loadout grant method for this alternative.

Verify before adding it to a shop

1. Check the server console and client F8 console for resource, metadata or Lua errors.
2. Equip, holster and re-equip the weapon. Verify its model, label, firing or melee action, and firearm reload behavior.
3. Disconnect normally, reconnect, and confirm the same character still owns it. Check ammunition and, with ox, durability and the item image.
4. Repeat the ownership check after a normal server shutdown and restart, allowing your framework or inventory to save first.

If the item exists but the model does not appear, recheck the resource startup and weapon identifier. An invalid weapon or item error points to the registration table or a stale server session. A missing image points to the filename, case or image host. A weapon that disappears after reconnect needs its framework or inventory save path checked; a temporary client-side weapon grant does not prove persistence.

Once these checks pass, add the registered weapon to the shop or crafting system that belongs to your installed inventory. For other frameworks, see QBox add-on weapons or QBCore add-on weapons.