Add-on weapons in QBox

Use this guide for an existing QBox server running qbx_core and ox_inventory. You need a working FiveM add-on weapon resource, access to the server files and an administrator account for testing. These are game assets; check the download's Legacy or Enhanced requirements before installing it.

1. Start the weapon resource

Back up the files you will edit. Place the complete download inside resources/[weapons]/example_weapon. Keep its stream folder, metadata, scripts and supplied fxmanifest.lua together. Follow the general installation guide for downloading and placing a Cornerstone resource.

Find the weapon's identifier in the <Name> field of its CWeaponInfo entry in weapons.meta. The folder name and the inventory label are separate names. If the metadata is protected, use the identifier in the author's installation instructions.

Add the resource to server.cfg without duplicating your existing framework startup entries:

# Use the actual folder name from your download.
ensure example_weapon

Preserve the supplied manifest: its data_file declarations tell FiveM how to load the metadata. Do not replace it with a generic manifest that omits audio, animations or components. See the Cfx.re data-file reference.

2. Register the weapon in ox_inventory

Open ox_inventory/data/weapons.lua. Insert this entry inside its existing Weapons table; keep the surrounding return table and all existing entries. QBox's custom-weapon guide uses this registration path.

['WEAPON_EXAMPLEPISTOL'] = {
    label = 'Example Pistol',
    weight = 1000,
    durability = 0.1,
    ammoname = 'ammo-9',
},

The values above are sample balance settings. weight is in grams; choose ammunition that fits the actual weapon. ammo-9 is an existing inventory item for ordinary pistol ammunition, not the GTA metadata identifier AMMO_PISTOL. Check the Ammo table in your installed weapons.lua before selecting another ammo item.

For this setup, register the weapon here rather than creating a second ordinary item in data/items.lua. You do not need a QBCore-style weapon item entry to make ox_inventory equip it.

Melee weapons, including axes

For an add-on axe, use its actual identifier and omit ammoname. Insert this alternative into Weapons only if you are installing that melee weapon:

['WEAPON_EXAMPLEAXE'] = {
    label = 'Example Axe',
    weight = 1800,
    durability = 0.1,
},

The upstream weapon definitions provide separate firearm, melee and ammunition examples. Inventory settings do not change the streamed model, damage or animations.

3. Add the inventory image

With the default image configuration, put your PNG at:

ox_inventory/web/images/WEAPON_EXAMPLEPISTOL.png

Use WEAPON_EXAMPLEAXE.png for the melee example. Match the item name and filename case exactly, including on Linux. If your server sets a custom inventory:imagepath, upload the image to that location instead. The ox_inventory configuration reference documents this setting.

4. Register supplied attachments, if needed

Skip this step when the weapon has no attachments. For a supplied suppressor, add an entry to the existing Components table in the same file. Replace the component identifier with one actually registered by the resource's weaponcomponents.meta:

['examplepistol_suppressor'] = {
    label = 'Example Pistol Suppressor',
    weight = 120,
    type = 'muzzle',
    client = {
        component = {
            joaat('COMPONENT_EXAMPLEPISTOL_SUPP'),
        },
        usetime = 2500,
    },
},

Add examplepistol_suppressor.png to the image directory. The component definitions show the supported structure. Listing a component here does not make it compatible with every weapon; the asset must support it.

5. Restart and test through the inventory

Save a backup of your changes, perform a full server restart and reconnect. In game, use an administrator account permitted to run ox_inventory's giveitem command. Replace 12 with your current server player ID:

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

For the melee example, use /giveitem 12 WEAPON_EXAMPLEAXE 1 and skip ammunition. Give an attachment separately only after registering it.

Equip the item through the inventory, reload, fire or swing, then holster and equip it again. Reconnect once more to check that the weapon and its ammunition persist. Test any shop, crafting recipe or armoury separately; registration does not add the weapon to those menus automatically.

Keep the inventory running during this test. A client-side GiveWeaponToPed call bypasses item ownership and does not verify inventory persistence.

Troubleshooting

For a different setup, use the QBCore guide or ESX guide. If you need help, send the resource name, inventory version and relevant console error through Support.