Giving weapons to players in FiveM, the right way for your server

#Which method your server needs

#ox_inventory

In ox_inventory a weapon is an item whose name is the weapon name. Add it on the server; the inventory handles equipping, ammo, durability and saving.

-- Give a pistol with a serial and 12 rounds loaded
local ok, response = exports.ox_inventory:AddItem(source, 'WEAPON_PISTOL', 1, {
    ammo = 12,
    serial = 'POL' .. math.random(100000, 999999),
})

if not ok then
    print(('Could not give weapon to %s: %s'):format(source, response))
end

-- Give spare ammunition as its own item
exports.ox_inventory:AddItem(source, 'ammo-9', 48)

AddItem returns false and a reason when it fails — typically the player is too heavy or out of slots — so check it. The metadata fields ox_inventory understands for weapons, such as serial, ammo, durability and components, are covered in ox_inventory metadata, and full weapon setup in the ox_inventory weapon guide.

#QBCore (qb-inventory)

local QBCore = exports['qb-core']:GetCoreObject()

local Player = QBCore.Functions.GetPlayer(source)
if Player then
    Player.Functions.AddItem('weapon_pistol', 1, false, { serie = 'POL123456', quality = 100 })
    TriggerClientEvent('qb-inventory:client:ItemBox', source, QBCore.Shared.Items['weapon_pistol'], 'add')
end

QBCore item names are lowercase (weapon_pistol) and must exist in qb-core/shared/items.lua and shared/weapons.lua. The metadata field names differ between qb-inventory versions — older versions use serie for the serial. See QBCore shared items and QBCore shared weapons.

#ESX Legacy

local xPlayer = ESX.GetPlayerFromId(source)
if xPlayer then
    xPlayer.addWeapon('WEAPON_PISTOL', 12) -- name, ammo
end

-- Check before giving
if not xPlayer.hasWeapon('WEAPON_PISTOL') then
    xPlayer.addWeapon('WEAPON_PISTOL', 12)
end

This applies to ESX’s built-in loadout. Many ESX servers now run ox_inventory instead, in which case use the ox_inventory method above. ESX items and loadout explains the difference.

#The raw native (standalone servers)

GiveWeaponToPed gives a weapon directly to a ped. Its parameters are the ped, the weapon hash, the ammo count, whether the weapon is hidden, and whether to force it into the ped’s hand.

local ped = PlayerPedId()
GiveWeaponToPed(ped, `WEAPON_CARBINERIFLE`, 250, false, true)

-- Useful companions
SetPedAmmo(ped, `WEAPON_CARBINERIFLE`, 250)
SetCurrentPedWeapon(ped, `WEAPON_CARBINERIFLE`, true)
RemoveWeaponFromPed(ped, `WEAPON_CARBINERIFLE`)
RemoveAllPedWeapons(ped, true)

With OneSync you can call it on the server against a player’s ped: GiveWeaponToPed(GetPlayerPed(source), joaat('WEAPON_PISTOL'), 50, false, true). Server-side is preferable because a client cannot fake it.

#A safe admin give-weapon command

Admin commands are the most common way cheaters get weapons — through an unprotected event. Keep the whole command on the server and protect it with an ACE.

RegisterCommand('giveweapon', function(source, args)
    local target = tonumber(args[1])
    local weapon = args[2] and args[2]:upper()
    if not target or not weapon or not GetPlayerName(target) then
        return print('usage: /giveweapon <id> <WEAPON_NAME>')
    end
    local ok, why = exports.ox_inventory:AddItem(target, weapon, 1)
    print(('%s gave %s to %s: %s'):format(source, weapon, target, ok and 'ok' or why))
end, true) -- true = restricted: needs the ACE 'command.giveweapon'

add_ace group.admin command.giveweapon allow

The full server.cfg reference, including where add_ace lines go, is on the minimap studio: the FiveM server.cfg guide.

#Why client-side giving gets flagged

Anticheats — and ox_inventory itself — compare the weapons a ped holds with what the server says the player owns. A weapon that appears on the client without a matching server record is the signature of a mod menu. Scripts that give weapons from the client produce exactly that signature for honest players. Server-side weapon validation shows how to check it yourself.