# The GTA weapon wheel in FiveM: categories, slots and HUD natives

> Control the GTA 5 weapon wheel in FiveM: move add-on weapons between categories with WheelSlot, set their order, and use the HUD weapon wheel natives.

Source: https://fam-tools.com/guides/fivem-weapon-wheel-slots-categories · FAM Tools · published 2026-09-19 · updated 2026-09-19 · about 12 min

**Short answer.** The wheel has eight categories set by each weapon's `WheelSlot` in weapons.meta: `WHEEL_UNARMED_MELEE`, `WHEEL_PISTOL`, `WHEEL_SMG`, `WHEEL_RIFLE`, `WHEEL_SNIPER`, `WHEEL_SHOTGUN`, `WHEEL_HEAVY` and `WHEEL_THROWABLE_SPECIAL`. `Group` is a different field and does not decide the segment. Order inside a segment comes from the slot's `OrderNumber` in `SlotNavigateOrder`. At runtime, `HudWeaponWheelGetSelectedHash` reads the highlighted weapon, `HudWeaponWheelIgnoreSelection` blocks selection for a frame, `HudSetWeaponWheelTopSlot` pre-selects, and HUD components 19 and 20 are the wheel and its stats.

## Key points

- `WheelSlot` decides the wheel segment; `Group` and `Slot` do not.
- Vanilla examples: machine guns sit in the SMG segment and the stun gun in the pistol segment.
- Give every add-on weapon a unique `Slot` and an `OrderNumber`.
- Number keys 1 to 9 select segments through controls 157 to 165.
- ox_inventory disables the wheel; its `weaponWheel` export turns it back on for special cases.

Some servers remove the weapon wheel entirely and let an inventory take over. Many do not: freeroam, PvP and lighter roleplay servers keep the wheel and simply want add-on weapons to land in the right segment, in a sensible order, with the ability to block a weapon from being picked when the rules say so. All of that is controlled by a few fields in weapons.meta and a handful of HUD natives.

## The eight segments

The weapon wheel is divided into eight segments. Each weapon names its segment in the `WheelSlot` field of its weapons.meta entry.

*WheelSlot values*

| WheelSlot | Segment | Vanilla examples |
| --- | --- | --- |
| `WHEEL_UNARMED_MELEE` | Fists and melee | Knife, bat, machete, knuckle dusters |
| `WHEEL_PISTOL` | Handguns | Pistol, combat pistol, stun gun |
| `WHEEL_SMG` | SMGs and machine guns | SMG, micro SMG, MG |
| `WHEEL_RIFLE` | Assault rifles | Carbine rifle, assault rifle |
| `WHEEL_SNIPER` | Snipers | Sniper rifle, heavy sniper |
| `WHEEL_SHOTGUN` | Shotguns | Pump shotgun |
| `WHEEL_HEAVY` | Heavy weapons | RPG, grenade launcher |
| `WHEEL_THROWABLE_SPECIAL` | Throwables and specials | Pipe bomb, ball |

Two vanilla placements surprise people and are useful to know when you design add-ons: the MG uses `WHEEL_SMG`, so machine guns share the SMG segment, and the stun gun uses `WHEEL_PISTOL`, so it sits with the handguns. Melee weapons share the fists segment.

## WheelSlot, Group and Slot are different things

A weapons.meta entry has three fields that sound alike:

*Three fields, three jobs*

| Field | Example | Controls |
| --- | --- | --- |
| `WheelSlot` | `WHEEL_RIFLE` | Which wheel segment the weapon appears in |
| `Group` | `GROUP_RIFLE` | Weapon family for scripts, stats and damage logic |
| `Slot` | `SLOT_CARBINERIFLE` | The weapon's own slot identity in the loadout |

The native reference for `GetWeapontypeGroup` spells it out: the group is not the same as the location on the weapon wheel. A script that checks `GROUP_SMG` to find "everything in the SMG segment" misses the machine guns, which are `GROUP_MG` but sit in the SMG segment.

`Slot` is the one that causes the most trouble with add-on weapons. It should be unique per weapon. An add-on that reuses a vanilla weapon's slot competes with it for the same place, and players see one weapon replace the other.

## Moving an add-on weapon to another segment

The most common wheel complaint on servers with weapon packs is an add-on sitting in the wrong segment, usually because it was copied from a vanilla weapon of a different class. The fix is one line in the add-on's weapons.meta:

*weapons.meta (excerpt)*

```xml
<Item type="CWeaponInfo">
  <Name>WEAPON_MYBULLPUPSMG</Name>
  <Model>w_sb_mybullpupsmg</Model>
  <Slot>SLOT_MYBULLPUPSMG</Slot>
  <WheelSlot>WHEEL_SMG</WheelSlot>
  <Group>GROUP_SMG</Group>
</Item>
```

Change `WheelSlot` to move it on the wheel. Change `Group` as well only if scripts should treat it as that family, for example a drive-by script that allows SMGs. When in doubt, copy both from the vanilla weapon it should behave like. The full field list is in [weapons.meta explained](https://fam-tools.com/guides/fivem-weapons-meta-explained).

## Order inside a segment

When several weapons share a segment, the player cycles through them in an order defined at the top of weapons.meta, in the `SlotNavigateOrder` block. Each weapon's slot gets an `OrderNumber`; files commonly contain two lists under `SlotNavigateOrder` and one under `SlotBestOrder`.

*weapons.meta (top of file)*

```xml
<CWeaponInfoBlob>
  <SlotNavigateOrder>
    <Item>
      <WeaponSlots>
        <Item>
          <OrderNumber value="133" />
          <Entry>SLOT_MYBULLPUPSMG</Entry>
        </Item>
      </WeaponSlots>
    </Item>
    <Item>
      <WeaponSlots>
        <Item>
          <OrderNumber value="98" />
          <Entry>SLOT_MYBULLPUPSMG</Entry>
        </Item>
      </WeaponSlots>
    </Item>
  </SlotNavigateOrder>
  <SlotBestOrder>
    <WeaponSlots>
      <Item>
        <OrderNumber value="263" />
        <Entry>SLOT_MYBULLPUPSMG</Entry>
      </Item>
    </WeaponSlots>
  </SlotBestOrder>
</CWeaponInfoBlob>
```

`SlotBestOrder`, as the name suggests, ranks weapons for the game's "best weapon" choice, used when the ped picks a weapon automatically. If an add-on does not appear in cycling at all, or jumps to an odd position, a missing or duplicated `Entry` in these lists is the usual cause. Take the numbers from a vanilla weapon near the position you want and adjust by one or two.

## Number keys and wheel controls

On keyboard, the number keys select wheel segments directly. They are ordinary controls, so you can disable them individually.

*Weapon selection controls*

| Control | Name | Key |
| --- | --- | --- |
| 37 | INPUT_SELECT_WEAPON | Tab (opens the wheel) |
| 157 | INPUT_SELECT_WEAPON_UNARMED | 1 |
| 158 | INPUT_SELECT_WEAPON_MELEE | 2 |
| 160 | INPUT_SELECT_WEAPON_SHOTGUN | 3 |
| 164 | INPUT_SELECT_WEAPON_HEAVY | 4 |
| 165 | INPUT_SELECT_WEAPON_SPECIAL | 5 |
| 159 | INPUT_SELECT_WEAPON_HANDGUN | 6 |
| 161 | INPUT_SELECT_WEAPON_SMG | 7 |
| 162 | INPUT_SELECT_WEAPON_AUTO_RIFLE | 8 |
| 163 | INPUT_SELECT_WEAPON_SNIPER | 9 |
| 14, 15 | INPUT_WEAPON_WHEEL_NEXT / PREV | Scroll wheel |

Servers with an inventory hotbar on keys 1 to 5 often disable 157 to 165 so a key press does not do two things at once. Scroll-wheel weapon switching, a common complaint in PvP, is controls 14 to 17 and 261 and 262.

## The HUD weapon wheel natives

*Weapon wheel natives*

| Native | What it does |
| --- | --- |
| `HudWeaponWheelGetSelectedHash()` | Hash of the weapon highlighted in the wheel |
| `HudWeaponWheelIgnoreSelection()` | Called each frame, stops the wheel giving the player the weapon |
| `HudSetWeaponWheelTopSlot(weaponHash)` | Makes that weapon the active one in its segment |
| `HudWeaponWheelGetSlotHash(index)` | Weapon active in a given wheel segment |
| `HudForceWeaponWheel(show)` | Forces the wheel to show or hide |
| `HideHudComponentThisFrame(19)` | Hides the wheel for a frame |
| `HideHudComponentThisFrame(20)` | Hides the wheel stats panel |

`HudWeaponWheelIgnoreSelection` also appears under the alias `BlockWeaponWheelThisFrame` in older scripts. `HudWeaponWheelGetSlotHash` takes a segment index; if you rely on it, print the results for indices 0 to 7 once on your build to confirm which index is which segment.

## Example: blocking specific weapons from the wheel

Blocking selection is more useful than hiding the wheel. This keeps the wheel working but refuses restricted weapons, for example weapons reserved for an event, or heavy weapons inside the city.

*client.lua*

```lua
local RESTRICTED = {
    [`WEAPON_RPG`] = true,
    [`WEAPON_MINIGUN`] = true,
    [`WEAPON_GRENADELAUNCHER`] = true,
}

CreateThread(function()
    while true do
        if IsControlPressed(0, 37) then
            local highlighted = HudWeaponWheelGetSelectedHash()
            if RESTRICTED[highlighted] then
                HudWeaponWheelIgnoreSelection()
            end
            Wait(0)
        else
            Wait(100)
        end
    end
end)
```

While Tab is held the script checks the highlighted weapon every frame and cancels the selection if it is restricted, so releasing Tab on it does nothing. The number keys bypass the wheel, so disable the matching segment key (164 for heavy weapons) as well if the rule must be absolute. On a server that gives weapons through an inventory, restrict them where they are issued instead.

## Inventory servers and the wheel

ox_inventory is built around items, so it disables the wheel: each tick it calls `HudWeaponWheelIgnoreSelection` and disables control 37 unless the wheel has been enabled. Its client export `exports.ox_inventory:weaponWheel(true)` enables the wheel while disabling inventory weapons, which the documentation describes as mostly for weaponised vehicles or minigames; call it again with `false` afterwards.

If you want the wheel gone on a server without such an inventory, [disabling the weapon wheel](https://fam-tools.com/guides/fivem-disable-weapon-wheel) has the complete recipe.

## Troubleshooting wheel problems

*Common weapon wheel problems*

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Add-on in the wrong segment | `WheelSlot` copied from another class | Set the right `WHEEL_` value |
| Add-on missing from cycling | No `SlotNavigateOrder` entry for its slot | Add an `Entry` with an `OrderNumber` |
| Getting one weapon removes another | Two weapons share a `Slot` | Give each weapon a unique `SLOT_` name |
| Wheel does not open at all | Inventory or script disables control 37 | Check ox_inventory or other HUD resources |
| Wheel opens but selection does nothing | `HudWeaponWheelIgnoreSelection` running | Find the script calling it every frame |
| Stats panel shows odd bars | `Hud` values in weapons.meta | Adjust `HudDamage`, `HudSpeed`, `HudCapacity`, `HudAccuracy`, `HudRange` |

The last row is worth a note: the bars in the wheel's stats panel are not calculated from the real damage or fire rate. They come from the `HudDamage`, `HudSpeed`, `HudCapacity`, `HudAccuracy` and `HudRange` fields in weapons.meta, so an add-on can show a tiny damage bar while hitting harder than any vanilla gun. Set them to sensible values, or hide the panel with `HideHudComponentThisFrame(20)` if your players should not rely on it.

When a weapon pack touches the wheel in ways you cannot trace, start the server with only the base game weapons and add packs back one by one. That quickly shows which pack's meta file is responsible.

## Questions

### How do I change which weapon wheel category a weapon is in?

Edit the `WheelSlot` field in the weapon's weapons.meta, for example `WHEEL_SMG` or `WHEEL_RIFLE`. Changing `Group` does not move it on the wheel.

### Why is my add-on weapon in the wrong weapon wheel slot?

It was probably copied from a vanilla weapon of another class and kept that weapon's `WheelSlot`. Set the correct value and give it a unique `Slot`.

### How many categories does the GTA 5 weapon wheel have?

Eight: unarmed and melee, pistol, SMG, rifle, sniper, shotgun, heavy, and throwable or special.

### How do I get the weapon the player highlighted in the wheel?

Call `HudWeaponWheelGetSelectedHash()` while the wheel is open. It returns the hash of the highlighted weapon.

### How do I stop players selecting a weapon from the wheel?

Call `HudWeaponWheelIgnoreSelection()` every frame while the restricted weapon is highlighted, and disable the matching number-key control.

## Related

- https://fam-tools.com/guides/fivem-disable-weapon-wheel
- https://fam-tools.com/guides/fivem-weapons-meta-explained
- https://fam-tools.com/guides/add-custom-weapons-to-fivem
- https://fam-tools.com/guides/fivem-weapon-hud-ammo-display
- https://fam-tools.com/guides/fivem-disable-combat-roll-quickswap