Tuning the taser (stun gun) on a FiveM server

#What the vanilla taser does

Knowing the stock values makes it obvious which one to change. These come from the taser's CWeaponInfo entry in weapons.meta:

Its weapon flags include NonLethal, OnlyFireOneShot, DisplayRechargeTimeHUD and CanPerformArrest. There is also a separate WEAPON_STUNGUN_MP in the game files with the same model and damage type; most servers use the classic WEAPON_STUNGUN, and inventories such as ox_inventory ship that one (labelled "Tazer").

#Changing how long players stay down

Four seconds is barely enough to holster a taser, let alone cuff someone. SetPedMinGroundTimeForStungun(ped, minTimeInMs) overrides the minimum time a ped stays on the ground after being stunned. According to the native reference:

• it applies to the ped you call it on, meaning the ped being stunned, not the officer;
• changing it while the ped is already stunned does not alter the current stun, only future ones;
• passing -1 resets it so the weapon's own DamageTime is used again;
• despite the name, it works for any weapon whose DamageType is ELECTRIC.

Because it is a property of the victim, every client sets it on its own ped. Re-apply it after respawn, since a new ped starts with defaults.

local STUN_MS = 8000

local function applyStunTime()
    SetPedMinGroundTimeForStungun(PlayerPedId(), STUN_MS)
end

AddEventHandler('playerSpawned', applyStunTime)

CreateThread(function()
    local lastPed = 0
    while true do
        local ped = PlayerPedId()
        if ped ~= lastPed then
            lastPed = ped
            applyStunTime()
        end
        Wait(2000)
    end
end)

The ped check catches model changes from character selection and clothing menus, which replace the player ped without a spawn event. Between six and ten seconds is the usual roleplay range: long enough to approach and cuff, short enough that being tased is not a free arrest from across the street.

#Blocking actions while stunned

A stunned ped is ragdolled, but players still find ways to act in the frames around it: firing the moment they land, or opening the inventory. IsPedBeingStunned(ped, 0) reports the state, and a short lockout after it ends closes the gap.

local lockedUntil = 0

CreateThread(function()
    while true do
        local ped = PlayerPedId()
        if IsPedBeingStunned(ped, 0) then
            lockedUntil = GetGameTimer() + 1500
        end

        if GetGameTimer() < lockedUntil then
            DisablePlayerFiring(PlayerId(), true)
            DisableControlAction(0, 24, true)  -- INPUT_ATTACK
            DisableControlAction(0, 25, true)  -- INPUT_AIM
            DisableControlAction(0, 140, true) -- INPUT_MELEE_ATTACK_LIGHT
            Wait(0)
        else
            Wait(100)
        end
    end
end)

On ox_inventory you can go further and set the canUseWeapons state bag to false during the lockout, which disarms the player and stops them equipping another weapon.

#Range and recharge in weapons.meta

Range and fire rate are not exposed through natives; they are fields of the weapon definition. To change them for the vanilla taser, ship a patched copy of its CWeaponInfo entry and load it with WEAPONINFO_FILE_PATCH, which is the same data file type qb-weapons uses to patch a vanilla pistol.

<Item type="CWeaponInfo">
  <Name>WEAPON_STUNGUN</Name>
  <Model>w_pi_stungun</Model>
  <DamageType>ELECTRIC</DamageType>
  <DamageTime value="6.000000" />
  <TimeBetweenShots value="3.500000" />
  <WeaponRange value="15.000000" />
  <!-- keep every other field from the vanilla entry -->
</Item>

fx_version 'cerulean'
game 'gta5'

files { 'stungun.meta' }
data_file 'WEAPONINFO_FILE_PATCH' 'stungun.meta'

Start from the complete vanilla entry and change only the fields you mean to change. The excerpt above is shortened for reading; do not rely on the game filling in fields you left out, because a trimmed entry is one of the most common causes of a taser that stops working after a meta edit. Field meanings are covered in weapons.meta explained.

Be conservative with range. Fifteen metres already changes how arrests play: suspects who ran from a 10 metre taser will be tased mid-sprint.

#Taser cartridges as an inventory item

ox_inventory defines WEAPON_STUNGUN without an ammoname, so it has unlimited shots. A popular roleplay change is a cartridge item that each shot consumes. The pattern is a new item, a client check that blocks firing when there are none, and a server event that removes one per shot.

['taser_cartridge'] = {
    label = 'Taser Cartridge',
    weight = 50,
    stack = true,
    description = 'One shot for a department taser.',
},

local STUNGUN = `WEAPON_STUNGUN`
local nextShot = 0

CreateThread(function()
    while true do
        local ped = PlayerPedId()
        if GetSelectedPedWeapon(ped) ~= STUNGUN then
            Wait(250)
        else
            if exports.ox_inventory:GetItemCount('taser_cartridge') < 1 then
                DisablePlayerFiring(PlayerId(), true)
            elseif IsPedShooting(ped) and GetGameTimer() > nextShot then
                nextShot = GetGameTimer() + 1000
                TriggerServerEvent('taser:usedCartridge')
            end
            Wait(0)
        end
    end
end)

RegisterNetEvent('taser:usedCartridge', function()
    local src = source
    if GetSelectedPedWeapon(GetPlayerPed(src)) ~= `WEAPON_STUNGUN` then return end
    exports.ox_inventory:RemoveItem(src, 'taser_cartridge', 1)
end)

The one-second debounce stops a single shot being counted twice, since IsPedShooting may report true on more than one frame for the same shot. The server check refuses the event unless the player is actually holding a taser. Stock cartridges in the police armory next to the taser itself; see the police armory setup.

#Stopping chain-tasing on the server

With a longer stun time comes a new problem: two officers alternating tasers can keep someone on the ground indefinitely, and so can a single officer if the recharge is short. A server-side cooldown per victim fixes it without touching the weapon. With OneSync, weaponDamageEvent fires before damage is applied, carries the weapon hash in weaponType, and names the victim through hitGlobalId, which is the victim's network id.

local STUNGUN = `WEAPON_STUNGUN`
local COOLDOWN = 15000
local lastStun = {}

AddEventHandler('weaponDamageEvent', function(sender, data)
    if data.weaponType ~= STUNGUN then return end

    local victim = NetworkGetEntityFromNetworkId(data.hitGlobalId)
    if victim == 0 or not IsPedAPlayer(victim) then return end

    local now = GetGameTimer()
    if lastStun[victim] and now - lastStun[victim] < COOLDOWN then
        CancelEvent()
        return
    end
    lastStun[victim] = now
end)

The table is keyed by ped entity, which changes when a player respawns, so stale entries simply stop matching. On a long-running server, clear it every few minutes to keep it small. Fifteen seconds between stuns on the same person gives the suspect a window to comply or run, which is what makes taser scenes interesting rather than a guaranteed takedown.

#Keeping tasers with the police

The taser's value on a roleplay server comes from who has it. Control that where items are created:

• Sell or issue it only from a job-restricted armory or shop (ox_inventory shops take a groups table).
• Leave it out of general stores and crafting recipes.
• If civilians may own one, require a licence, as described in the weapon licence system.
• Do not rely on a client check that removes the taser from non-police. It is trivially skipped and punishes the wrong people when a job update is slow.

#Troubleshooting