ox_inventory weapons and ammo: data/weapons.lua and weapons vanishing

You give a player a pistol with an admin menu or a job script. They disconnect, come back, and the pistol is gone. With ox_inventory, weapons are not a separate loadout: they are items, and anything that is not an item is removed. This article explains how weapons and ammo work, how to give them correctly, and where to tune durability and attachments.

#Weapons are items

In ox_inventory the item name of a weapon is its hash name, for example WEAPON_PISTOL. They are defined in ox_inventory/data/weapons.lua, not in items.lua. The file returns three groups:

return {
    Weapons = {
        ['WEAPON_PISTOL'] = {
            label = 'Pistol',
            weight = 1130,
            durability = 0.1,
        },
        -- ...
    },
    Components = {
        -- attachments
    },
    Ammo = {
        -- ammo definitions
    },
}

Open the file in your install: each default weapon has a ready entry, and that is the reference for the exact fields of your version. A weapon missing from Weapons is simply not a valid item.

#Why weapons vanish on reconnect

Old ESX and QBCore scripts give weapons with natives such as GiveWeaponToPed, or with ESX's xPlayer.addWeapon. That puts the weapon in the ped's hands for that session, but it is not an item and nothing saves it. ox_inventory also removes weapons that are not in the inventory, so they disappear on reconnect or even sooner.

The fix is to give weapons as items, from the server:

local success = exports.ox_inventory:AddItem(source, 'WEAPON_PISTOL', 1)
if not success then
    print('Could not give the weapon: inventory full or unknown weapon')
end

Replace every script call that grants a weapon with a native, addWeapon or Player.Functions.AddItem('weapon_pistol', ...) by an AddItem call with the uppercase weapon name. A script that only works through a native, such as a shop that spawns a weapon in hand, needs that change before it works on a server using ox_inventory.

Tip: weapon names are case sensitive in item lists, and WEAPON_PISTOL is the form ox_inventory uses. An old script that sends weapon_pistol can fail for that reason.

#Ammo items

Ammo is an item too. The ammo type is named by a weapon's ammoname in its entry, for example ammo-9 for 9 mm:

exports.ox_inventory:AddItem(source, 'ammo-9', 60)

When a player uses an ammo item with a weapon equipped that accepts it, ox_inventory loads it into the weapon, and the weapon keeps its own ammo count in its metadata. Ammo shows as an item in the inventory when it is not loaded.

Check the item names on your version in data/items.lua and data/weapons.lua. The pattern is ammo-<type>, for example ammo-9, ammo-rifle, ammo-shotgun, and an item that does not exist cannot be added.

#Durability and degrade

Weapons wear when they are fired. The durability value in the weapon entry sets how fast: a higher number means it degrades quicker. A weapon at zero durability does not work until it is repaired.

['WEAPON_PISTOL'] = {
    label = 'Pistol',
    weight = 1130,
    durability = 0.05,
},

Lower the number to make a weapon last longer. Repair is a gameplay choice: many servers use a repair item, a crafting recipe or a mechanic, and you can set durability back with SetMetadata (see item metadata in ox_inventory).

#Attachments (components)

Attachments such as a flashlight, a suppressor or a clip are items listed in the Components group, and they have their own entries in items.lua. A player puts one on by using it while the weapon is equipped. The component is stored on the weapon item, so it survives a reconnect.

If an attachment does nothing, check these three things:

• the component item exists in data/items.lua
• it is listed for that weapon in data/weapons.lua
• the weapon is equipped when the component is used

You can also add a component from the server through weapon metadata, for example when you sell a pre-built weapon, but test it with a normal pistol first, since the metadata format depends on your version.

#Selling weapons in shops

Weapons appear in a shop like any item, with the same name:

{ name = 'WEAPON_PISTOL', price = 2500, license = 'weapon' },

See ox_inventory shops for the rest of the shop format. If a shop script still gives weapons by native, it needs the change shown above.

#Other scripts that touch weapons

Admin menus, police scripts, loadout scripts and gang systems often use natives. Search your resources for these calls and replace them:

GiveWeaponToPed(...)
GiveDelayedWeaponToPed(...)
xPlayer.addWeapon(...)

Search the resources folder for addWeapon and GiveWeaponToPed, then switch each hit to exports.ox_inventory:AddItem. If you do it for all of them once, weapons stop disappearing.

#Checklist