The GTA weapon wheel in FiveM: categories, slots and 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.

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:

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:

<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.

#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.

<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.

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

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.

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 has the complete recipe.

#Troubleshooting wheel problems

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.