Removing and confiscating weapons in FiveM

#Three different things called "remove"

Before writing any code, decide which of these you mean. Most bug reports about weapons "coming back" or "disappearing forever" are really about picking the wrong one.

On a standalone server without an inventory, the ped is the only place weapons live, so the natives are the whole story. On ox_inventory, qb-inventory or ESX, the inventory or loadout is the source of truth and the ped just holds a copy.

#The natives: RemoveWeaponFromPed and RemoveAllPedWeapons

RemoveWeaponFromPed(ped, weaponHash) removes one weapon. RemoveAllPedWeapons(ped, p1) removes everything; the reference notes that the second parameter is not used by the game, and scripts conventionally pass true. Both have server-side equivalents when OneSync is enabled, which is where they belong.

local function stripPed(src, weaponName)
    local ped = GetPlayerPed(src)
    if ped == 0 then return end

    if weaponName then
        RemoveWeaponFromPed(ped, joaat(weaponName))
    else
        RemoveAllPedWeapons(ped, true)
    end
end

On the client the same calls work against PlayerPedId(), but a client-side removal is only as trustworthy as the client. A cheater can simply not run it. When removal is a punishment or a rule, do it from the server.

#Holstering without removing anything

Often you do not want to take anything, you want the gun out of the player's hands: they walked into a clothing store, opened a phone, or started an animation. Switch the ped to unarmed.

SetCurrentPedWeapon(PlayerPedId(), `WEAPON_UNARMED`, true)

On ox_inventory, do not fight the inventory with that native, because it tracks the equipped weapon and will log that the weapon was "forcibly unequipped". Ask ox_inventory to disarm instead. It exposes a client event for it that a server can trigger:

TriggerClientEvent('ox_inventory:disarm', src, true) -- true skips the holster animation

To keep weapons unusable for a while (cuffed, in a safe zone, during a cutscene), ox_inventory reads a player state bag called canUseWeapons. When it turns false, the current weapon is disarmed and weapon items refuse to equip until it is true again.

local function setWeaponsAllowed(src, allowed)
    Player(src).state:set('canUseWeapons', allowed, true)
end

The ox documentation shows the client-side form, LocalPlayer.state.canUseWeapons = false. Setting it from the server is better for anything a player should not be able to undo.

#ox_inventory: RemoveItem, ClearInventory and confiscation

With ox_inventory, a weapon is an item named after the weapon (WEAPON_PISTOL). Removing the item removes the weapon; if it happens to be equipped, ox_inventory disarms it.

local ox = exports.ox_inventory

-- one specific weapon
ox:RemoveItem(src, 'WEAPON_PISTOL', 1)

-- a specific serial only, for evidence
ox:RemoveItem(src, 'WEAPON_PISTOL', 1, { serial = 'POL482913' })

-- everything except a few items
ox:ClearInventory(src, { 'phone', 'id_card' })

The export signatures from the ox documentation are RemoveItem(inv, item, count, metadata, slot, ignoreTotal, strict) and ClearInventory(inv, keep). Passing metadata lets you remove the exact gun an officer is booking into evidence rather than whichever pistol comes first.

For jail and hospital flows use the pair that exists for it. ConfiscateInventory(source) takes the whole inventory and stores it; ReturnInventory(source) gives it back.

RegisterNetEvent('jail:sentence', function(target, minutes)
    local src = source
    if not IsPlayerAceAllowed(src, 'jail.sentence') then return end

    exports.ox_inventory:ConfiscateInventory(target)
    SetTimeout(minutes * 60000, function()
        if GetPlayerName(target) then
            exports.ox_inventory:ReturnInventory(target)
        end
    end)
end)

In a real jail script the sentence should be stored, so a player who relogs mid-sentence is handled; the timeout above is only there to show the two calls.

#QBCore and qb-inventory

QBCore weapons are lowercase items (weapon_pistol) with type = 'weapon' in shared/items.lua. Remove them like any other item, through the player object or the inventory export whose signature is RemoveItem(identifier, item, amount, slot, reason).

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

local function removeAllWeapons(src)
    local Player = QBCore.Functions.GetPlayer(src)
    if not Player then return end

    for _, item in pairs(Player.PlayerData.items) do
        if item and item.type == 'weapon' then
            exports['qb-inventory']:RemoveItem(src, item.name, item.amount, item.slot, 'weapons-confiscated')
        end
    end
    RemoveAllPedWeapons(GetPlayerPed(src), true)
end

qb-inventory also has ClearInventory(source, filterItems), which wipes everything except the item names you pass and removes the weapon currently in the player's hands. Item field details are in QBCore shared items.

#ESX Legacy loadout

ESX without ox_inventory keeps weapons in xPlayer.loadout. xPlayer.removeWeapon(weaponName) removes the attached components, calls RemoveWeaponFromPed, zeroes the ammo and deletes the entry from the loadout, which is everything you want in one call.

local function stripLoadout(src)
    local xPlayer = ESX.GetPlayerFromId(src)
    if not xPlayer then return end

    local names = {}
    for _, weapon in ipairs(xPlayer.getLoadout()) do
        names[#names + 1] = weapon.name
    end
    for _, name in ipairs(names) do
        xPlayer.removeWeapon(name)
    end
end

The names are collected first because getLoadout() returns the live loadout table and removeWeapon removes entries from it; removing while iterating the same table skips every other weapon. If the server runs ox_inventory on top of ESX, ignore the loadout functions entirely and use the ox exports.

#Taking ammo or attachments instead of the gun

Sometimes the weapon should stay and only part of it should go: an officer unloads a seized rifle, a mechanic strips a suppressor, an event hands everyone an empty pistol. The natives for that are as simple as the removal ones.

All three have server-side versions under OneSync. On ox_inventory, ammo and attachments are stored in the weapon item's metadata (ammo and components), so change them there or the inventory will restore them on the next equip. Find the slot with Search, edit the metadata and write it back with SetMetadata(inv, slot, metadata).

local function unloadWeapons(src, weaponName)
    local slots = exports.ox_inventory:Search(src, 'slots', weaponName)
    for _, item in pairs(slots or {}) do
        local meta = item.metadata or {}
        meta.ammo = 0
        exports.ox_inventory:SetMetadata(src, item.slot, meta)
    end
end

Hand the removed rounds back as ammo items if the scene calls for it; an officer who unloads a pistol should end up holding the magazine, not deleting it. Ammo types and items lists the ox ammo item names, and attachments covers the component items.

#A protected disarm command

Staff need a quick way to disarm someone mid-scene. Keep the command on the server and restrict it with an ACE so a client event cannot be abused.

RegisterCommand('disarm', function(source, args)
    local target = tonumber(args[1])
    if not target or not GetPlayerName(target) then
        return print('usage: /disarm <id>')
    end

    if GetResourceState('ox_inventory') == 'started' then
        TriggerClientEvent('ox_inventory:disarm', target, true)
    else
        SetCurrentPedWeapon(GetPlayerPed(target), `WEAPON_UNARMED`, true)
    end
    print(('%s disarmed %s'):format(source, target))
end, true)

add_ace group.admin command.disarm allow

This only holsters the weapon. A separate /confiscate command that calls ConfiscateInventory is a better fit for anything that should actually take property away, and it should write to a log.

#Why removed weapons come back

• Removed with a native on an inventory server. The item is still in the inventory, so the next time the player uses it, it is equipped again. Remove the item.
• Given with a native, removed by the inventory. The mirror image: ox_inventory disarms weapons it did not equip when its inventory:weaponmismatch convar is on (the default). That is why a GiveWeaponToPed "gift" disappears. See giving weapons.
• Removed on the client only. Another resource or a relog restores the loadout from the database.
• Removed before the player finished loading. A disarm fired on join can run before the inventory has equipped anything. Trigger removals after your framework's player-loaded event.