# weaponanimations.meta: how a weapon is held and handled

> What weaponanimations.meta controls in FiveM: animation sets, clip sets for movement, cover and reloads, fire-rate modifiers and wrong-grip fixes.

Source: https://fam-tools.com/guides/fivem-weaponanimations-meta · FAM Tools · published 2026-09-11 · updated 2026-09-11 · about 9 min

**Short answer.** weaponanimations.meta groups entries by animation set — `Default`, `FirstPerson`, `FirstPersonAiming`, `FirstPersonRNG`, `FirstPersonScope`, `Ballistic`, `MP_F_Freemode`, `Female`, `Fat`, `SuperFat`, `GangFemale` — and in each lists, per weapon name, the clip sets it uses. The easy and reliable approach is to copy the entries of the vanilla weapon your addon resembles and change only the weapon key.

## Key points

- It maps a weapon to **existing** animation clip sets; it does not add new animations.
- Each animation set (Default, FirstPerson…) needs its own entry for your weapon.
- A missing FirstPerson entry is the usual cause of broken first-person views.
- Copy the vanilla weapon closest in size and grip, then rename the key.

When an addon rifle is held like a pistol, a first-person view shows arms floating in the air, or reloads look like another weapon’s, the cause is almost always weaponanimations.meta. The file does not contain animations — it points each weapon at existing GTA V animation sets for every situation: standing, moving, in cover, in first person, for different ped types.

## Animation sets

The file’s top level is a list of animation sets, each containing entries keyed by weapon name. A real addon rifle defines an entry for its weapon in each of these sets:

| Set | Used for |
| --- | --- |
| `Default` | Standard third-person handling |
| `FirstPerson` | First-person idle and movement |
| `FirstPersonAiming` | First-person aiming |
| `FirstPersonRNG` | First-person run-and-gun |
| `FirstPersonScope` | First-person scoped aiming |
| `MP_F_Freemode` | The female online character model |
| `Ballistic` | Heavy armour (Juggernaut-style) movement |
| `Female`, `GangFemale`, `Fat`, `SuperFat` | Other ped body types |

## What one entry contains

*weaponanimations.meta (excerpt of one entry)*

```xml
<Item key="WEAPON_MYRIFLE">
  <CoverMovementClipSetHash>cover@move@base@2h</CoverMovementClipSetHash>
  <CoverWeaponClipSetHash>Cover_Wpn_RifleLo</CoverWeaponClipSetHash>
  <MotionClipSetHash>weapons@rifle@lo@carbine</MotionClipSetHash>
  <MotionFilterHash>BothArms_filter</MotionFilterHash>
  <WeaponClipSetHash>weapons@rifle@lo@carbine</WeaponClipSetHash>
  <AnimFireRateModifier value="1.000000" />
  <AnimBlindFireRateModifier value="1.000000" />
  <UseFromStrafeUpperBodyAimNetwork value="true" />
  <AimingDownTheBarrel value="true" />
  <WeaponSwapData ref="SWAP_DEFAULT" />
</Item>
```

- `MotionClipSetHash` / `WeaponClipSetHash` — the core holding and handling animations (here the carbine’s).
- `CoverMovementClipSetHash` / `CoverWeaponClipSetHash` — behaviour in cover.
- `AnimFireRateModifier` — speeds up or slows the firing animation.
- `WeaponSwapData` — how switching to and from the weapon animates.

## The reliable method: copy a vanilla weapon

1. Pick the vanilla weapon closest in shape and grip (carbine for AR-style rifles, SMG for compact guns, pistol for handguns).
2. Extract the game’s weaponanimations.meta with OpenIV or CodeWalker and find that weapon’s entries in every set.
3. Copy each entry into your file and change only the `key` to your weapon’s name.
4. Register the file with `data_file 'WEAPON_ANIMATIONS_FILE' '**/weaponanimations.meta'`.

> **Do not skip the first-person sets** — Many addon packs only define `Default`. The weapon looks fine in third person and broken the moment a player switches to first person. Copy all of the sets the vanilla weapon has.

## Holstering animations

Drawing and holstering use clips defined in pedpersonality.meta rather than here. If the unholster animation looks wrong, check the weapon is listed in the right `UNHOLSTER_*` groups there. Scripted holster animations for roleplay are covered in [holster and draw animations](https://fam-tools.com/guides/fivem-holster-draw-animation).

## Questions

### Why is my addon rifle held like a pistol?

Its weaponanimations.meta entry points at pistol clip sets, or the entry is missing and the game falls back. Copy a vanilla rifle’s entries for your weapon.

### Why is first person broken for my addon weapon?

The weapon has no entries in the FirstPerson, FirstPersonAiming, FirstPersonRNG and FirstPersonScope sets. Add them.

### Can weaponanimations.meta add new animations?

No. It only chooses among animation clip sets that exist in the game or are streamed separately.

### Which data_file loads weaponanimations.meta?

`data_file 'WEAPON_ANIMATIONS_FILE' 'path/weaponanimations.meta'`.

## Related

- https://fam-tools.com/guides/fivem-weapons-meta-explained
- https://fam-tools.com/guides/fivem-weaponarchetypes-meta
- https://fam-tools.com/guides/fivem-holster-draw-animation
- https://fam-tools.com/guides/add-custom-weapons-to-fivem