# Building an ammo and weapon HUD

> Show weapon data in a custom FiveM HUD: read clip and reserve ammo, get weapon labels, hide GTA's ammo counter and update only when something changes.

Source: https://fam-tools.com/guides/fivem-weapon-hud-ammo-display · FAM Tools · published 2026-09-11 · updated 2026-09-11 · about 9 min

**Short answer.** Read the weapon with `GetSelectedPedWeapon(ped)`, rounds in the clip with `GetAmmoInClip(ped, weapon)` (it returns a success flag and the count), total rounds with `GetAmmoInPedWeapon(ped, weapon)` and clip size with `GetMaxAmmoInClip`. Hide GTA’s own counter with `DisplayAmmoThisFrame(false)` (or HUD component 2), poll a few times per second while armed, and send the UI a message only when a value changes. With ox_inventory, `ox_inventory:currentWeapon` tells you when the weapon changes.

## Key points

- `GetAmmoInClip` returns two values: ok, clip.
- `GetAmmoInPedWeapon` = total rounds for that weapon.
- Hide vanilla ammo with `DisplayAmmoThisFrame(false)` each frame.
- Send UI updates on change only.
- Sleep the loop when unarmed.

A clean ammo counter — weapon name, rounds in the clip, rounds left — is one of the most requested HUD elements. The data comes from a few natives; the craft is in updating the UI only when something changes, so the HUD costs nothing while you are just holding a gun.

## Reading ammo

*client.lua*

```lua
local last = {}

CreateThread(function()
    while true do
        local ped = PlayerPedId()
        local weapon = GetSelectedPedWeapon(ped)
        local armed = weapon ~= `WEAPON_UNARMED` and IsPedArmed(ped, 4)

        if armed then
            local _, clip = GetAmmoInClip(ped, weapon)
            local total = GetAmmoInPedWeapon(ped, weapon)
            local size = GetMaxAmmoInClip(ped, weapon, true)
            if weapon ~= last.weapon or clip ~= last.clip or total ~= last.total then
                last = { weapon = weapon, clip = clip, total = total }
                SendNUIMessage({ action = 'ammo', clip = clip, reserve = total - clip, size = size })
            end
            Wait(150)
        else
            if last.weapon then
                last = {}
                SendNUIMessage({ action = 'ammo', hide = true })
            end
            Wait(500)
        end
    end
end)
```

`GetAmmoInPedWeapon` includes the rounds in the clip, so reserve = total − clip. Performance habits: [NUI performance](https://fam-tools.com/guides/fivem-nui-performance).

## Hiding GTA’s counter

*client.lua*

```lua
CreateThread(function()
    while true do
        local sleep = 500
        if IsPedArmed(PlayerPedId(), 4) then
            sleep = 0
            DisplayAmmoThisFrame(false)
            HideHudComponentThisFrame(2) -- weapon icon
        end
        Wait(sleep)
    end
end)
```

## Weapon names

Use your inventory’s label (ox_inventory item label) or the game label from the weapon’s `HumanNameHash` with `GetLabelText` — see [weapon display names](https://fam-tools.com/guides/fivem-weapon-display-names-addtextentry).

## With ox_inventory

*client.lua*

```lua
AddEventHandler('ox_inventory:currentWeapon', function(weapon)
    if weapon then
        SendNUIMessage({ action = 'weapon', label = weapon.label, serial = weapon.metadata.serial })
    else
        SendNUIMessage({ action = 'weapon', hide = true })
    end
end)
```

ox_inventory keeps ammo in item metadata and sets it on the ped when a weapon is equipped, so the natives above still report the live numbers.

## Questions

### How do I get the ammo in the current clip?

`local ok, clip = GetAmmoInClip(ped, weaponHash)` — the second return value is the count.

### How do I hide GTA’s ammo counter?

Call `DisplayAmmoThisFrame(false)` every frame while armed (and hide HUD component 2 for the weapon icon).

### How often should the ammo HUD update?

Poll a few times per second while armed and send UI messages only when values change.

### Does this work with ox_inventory?

Yes; combine the natives with the `ox_inventory:currentWeapon` event for weapon changes.

## Related

- https://fam-tools.com/guides/fivem-infinite-ammo-and-reload
- https://fam-tools.com/guides/fivem-crosshair-reticle
- https://fam-tools.com/guides/fivem-weapon-display-names-addtextentry
- https://fam-tools.com/guides/fivem-ammo-types-and-items