# weapons.meta explained, field by field

> A practical FiveM weapons.meta reference: Name, Model, Slot, FireType, ClipSize, Damage, falloff, recoil, WeaponFlags, AttachPoints and the data_file lines.

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

**Short answer.** weapons.meta holds `CWeaponInfo` items inside a `CWeaponInfoBlob`. The fields you will edit most are `Name`, `Model`, `Slot`, `AmmoInfo`, `ClipSize`, `Damage`, `HeadShotDamageModifierPlayer`, `DamageFallOffRange*`, `TimeBetweenShots`, `WeaponRange`, the recoil shake values, `WeaponFlags` and `AttachPoints`. Load it with `data_file 'WEAPONINFO_FILE' '**/weapons.meta'` alongside the other weapon meta files.

## Key points

- `Name` is the weapon’s spawn name (and the hash everything else uses); `Model` is the drawable it shows.
- `Damage`, `HeadShotDamageModifierPlayer` and the falloff fields decide lethality.
- `TimeBetweenShots` sets fire rate: 0.135 s ≈ 444 rounds per minute.
- `WeaponFlags` is a space-separated list that switches behaviour on (Automatic, TwoHanded…).
- `AttachPoints` lists which components fit and on which bone.

Every GTA V weapon — vanilla or addon — is defined by a CWeaponInfo entry in a weapons.meta file. It decides what the weapon is called, which model it uses, how hard it hits, how fast it fires, how far it reaches and which attachments fit. The file is long and intimidating, but only a few dozen of its fields matter in practice. This reference explains those, using a real addon rifle’s meta as the example.

## How the file is loaded

An addon weapon resource ships several meta files and registers each with a `data_file` line. This is the set the weapon studio writes for every export:

*fxmanifest.lua*

```lua
fx_version 'cerulean'
game 'gta5'

files {
    '**/weaponcomponents.meta',
    '**/weaponarchetypes.meta',
    '**/weaponanimations.meta',
    '**/pedpersonality.meta',
    '**/weapons.meta',
}

data_file 'WEAPONCOMPONENTSINFO_FILE' '**/weaponcomponents.meta'
data_file 'WEAPON_METADATA_FILE'      '**/weaponarchetypes.meta'
data_file 'WEAPON_ANIMATIONS_FILE'    '**/weaponanimations.meta'
data_file 'PED_PERSONALITY_FILE'      '**/pedpersonality.meta'
data_file 'WEAPONINFO_FILE'           '**/weapons.meta'
```

| File | data_file type | Defines |
| --- | --- | --- |
| weapons.meta | `WEAPONINFO_FILE` | The weapon itself (this guide) |
| weaponarchetypes.meta | `WEAPON_METADATA_FILE` | Model archetypes: model, texture dictionary, LOD — see [weaponarchetypes.meta](/guides/fivem-weaponarchetypes-meta) |
| weaponanimations.meta | `WEAPON_ANIMATIONS_FILE` | Which animation sets it uses — see [weaponanimations.meta](/guides/fivem-weaponanimations-meta) |
| weaponcomponents.meta | `WEAPONCOMPONENTSINFO_FILE` | Its attachments and magazines |
| pedpersonality.meta | `PED_PERSONALITY_FILE` | Holster/unholster clips for peds |

> **The order matters** — Components must be known before the weapon that references them, which is why `WEAPONCOMPONENTSINFO_FILE` comes first. A weapon whose components fail to load often spawns without its magazine or crashes when an attachment is added.

## The structure

*weapons.meta (skeleton)*

```xml
<CWeaponInfoBlob>
  <SlotNavigateOrder>…</SlotNavigateOrder>
  <Infos>
    <Item>
      <Infos>
        <Item type="CWeaponInfo">
          <Name>WEAPON_MYRIFLE</Name>
          <Model>w_ar_myrifle</Model>
          <!-- … every field below … -->
        </Item>
      </Infos>
    </Item>
  </Infos>
  <Name>MY_WEAPON_PACK</Name>
</CWeaponInfoBlob>
```

`SlotNavigateOrder` places the weapon in the weapon wheel’s order; each `CWeaponInfo` is one weapon. One file can define several weapons.

## Identity: name, model, slot, group

| Field | Example | Meaning |
| --- | --- | --- |
| `Name` | `WEAPON_MYRIFLE` | The weapon’s spawn name. Hashed with joaat, it is the ID inventories and natives use. |
| `Model` | `w_ar_myrifle` | The model (must match an archetype in weaponarchetypes.meta). |
| `Audio` | `AUDIO_ITEM_CARBINE_SPECIAL` | Which vanilla sound set to use — see [addon weapon sounds](/guides/fivem-addon-weapon-sounds). |
| `Slot` | `SLOT_WEAPON_MYRIFLE` | Unique inventory slot; must be unique per weapon. |
| `WheelSlot` | `WHEEL_RIFLE` | Which weapon-wheel section it appears in. |
| `Group` | `GROUP_RIFLE` | Weapon class, used by the game for animations, stats and AI. |
| `HumanNameHash` | `WEAPON_MYRIFLE` | Text label key for the display name — see [display names](/guides/fivem-weapon-display-names-addtextentry). |
| `DamageType` | `BULLET` | BULLET, EXPLOSIVE, MELEE, FIRE, ELECTRIC… |
| `FireType` | `INSTANT_HIT` | INSTANT_HIT (bullets), PROJECTILE (rockets, grenades), MELEE… |

> **Copy a vanilla weapon of the same class** — The safest way to build a new weapon is to start from the vanilla entry closest to it (a carbine for an AR-15 style rifle) and change only what differs. Groups, animations and audio then already agree with each other.

## Damage, headshots and falloff

| Field | Example | Meaning |
| --- | --- | --- |
| `Damage` | `34.75` | Base damage per bullet. |
| `HeadShotDamageModifierPlayer` | `18.0` | Multiplier for headshots on players. |
| `MinHeadShotDistancePlayer` / `MaxHeadShotDistancePlayer` | `5` / `40` | Distances over which the headshot bonus applies. |
| `HitLimbsDamageModifier` | `0.5` | Damage scale for arm and leg hits. |
| `NetworkHitLimbsDamageModifier` | `0.8` | Limb scale in multiplayer. |
| `LightlyArmouredDamageModifier` | `0.75` | Scale against lightly armoured targets. |
| `NetworkPlayerDamageModifier` | `1.0` | Overall scale against players online. |
| `NetworkHeadShotPlayerDamageModifier` | `1.7` | Headshot scale against players online. |
| `DamageFallOffRangeMin` / `Max` | `47.5` / `120` | Damage starts dropping at Min and reaches the minimum at Max. |
| `DamageFallOffModifier` | `0.3` | Damage multiplier at the far end of the falloff. |

Values are illustrative from a real addon rifle; tune against your own server’s health and armour. For server-wide balance without editing files, [damage modifiers](https://fam-tools.com/guides/fivem-weapon-damage-modifier) are often simpler, and headshots have their own guide: [headshot damage settings](https://fam-tools.com/guides/fivem-headshot-damage-settings).

## Magazine, fire rate, range and accuracy

| Field | Example | Meaning |
| --- | --- | --- |
| `AmmoInfo ref` | `AMMO_RIFLE` | Which ammo type it uses (shared pools between weapons). |
| `ClipSize` | `30` | Rounds per magazine. |
| `TimeBetweenShots` | `0.135` | Seconds between shots — 60 / 0.135 ≈ 444 RPM. |
| `WeaponRange` | `120` | Maximum range in metres. |
| `LockOnRange` | `65` | Lock-on distance for aim assist. |
| `AccuracySpread` | `3.0` | Base spread; lower is more accurate. |
| `RecoilAccuracyMax` | `0.5` | How much sustained fire degrades accuracy. |
| `BulletsInBatch` / `BatchSpread` | `1` / `0` | Pellets per shot and their spread — shotguns use several. |
| `Penetration` | `0.1` | How well bullets pass through thin materials. |
| `Speed` | `2000` | Projectile speed. |
| `ReloadTimeMP` | `-1` | Override reload time; −1 uses the animation. |

## Recoil shake and cameras

| Field | Example | Meaning |
| --- | --- | --- |
| `RecoilShakeHash` | `ASSAULT_RIFLE_RECOIL_SHAKE` | Third-person camera shake per shot |
| `RecoilShakeHashFirstPerson` | `FPS_ASSAULT_RIFLE_RECOIL_SHAKE` | First-person camera shake per shot |
| `RecoilShakeAmplitude` | `0.333` | Strength of that shake |
| `MinTimeBetweenRecoilShakes` | `150` | Milliseconds between shakes |
| `DefaultCameraHash` | `DEFAULT_THIRD_PERSON_PED_AIM_CAMERA` | Aim camera |
| `FirstPersonScopeFov` | `20` | Field of view through a scope in first person |

The shake is visual; it does not move where bullets go. Scripted recoil that actually lifts the aim is covered in [recoil scripts](https://fam-tools.com/guides/fivem-recoil-script).

## WeaponFlags

`<WeaponFlags>` is a single space-separated list. Each word switches on a behaviour. From the example rifle:

*weapons.meta*

```xml
<WeaponFlags>CarriedInHand Automatic Gun CanLockonOnFoot CanLockonInVehicle CanFreeAim TwoHanded AnimReload AnimCrouchFire UsableOnFoot UsableInCover LongWeapon UseFPSAimIK</WeaponFlags>
```

| Flag | Effect |
| --- | --- |
| `Automatic` | Fires while the trigger is held |
| `TwoHanded` | Held with both hands |
| `LongWeapon` | Treated as a long gun (affects holstering and animations) |
| `CanFreeAim` | Can be aimed without lock-on |
| `UsableInCover` | Can be used from cover |
| `UsableOnFoot` | Can be used while on foot |
| `AnimReload` | Uses a reload animation |

## AttachPoints: which components fit

*weapons.meta*

```xml
<AttachPoints>
  <Item>
    <AttachBone>WAPClip</AttachBone>
    <Components>
      <Item><Name>COMPONENT_MYRIFLE_CLIP_01</Name><Default value="true" /></Item>
      <Item><Name>COMPONENT_MYRIFLE_CLIP_02</Name><Default value="false" /></Item>
    </Components>
  </Item>
  <Item>
    <AttachBone>WAPSupp</AttachBone>
    <Components>
      <Item><Name>COMPONENT_AT_AR_SUPP</Name><Default value="false" /></Item>
    </Components>
  </Item>
</AttachPoints>
```

Each attach point is a bone on the model (`WAPClip` for magazines, `WAPSupp` for suppressors, `WAPFlshLasr` for lights, `WAPScop` for scopes, `WAPGrip` for grips). A component only fits if it is listed here — which is why an attachment item does nothing on some addon guns. [Weapon components](https://fam-tools.com/guides/fivem-weapon-components-attachments) explains the scripting side.

## The HUD stats

`HudDamage`, `HudSpeed`, `HudCapacity`, `HudAccuracy` and `HudRange` (0–100) only fill the stat bars in the game’s weapon wheel and shop menus. They do not change how the weapon behaves; set them to reflect the real values so players are not misled. To see what each field starts at without opening a file, [a weapons.meta editor](https://fam-tools.com/free-tools/weapons-meta-editor) reads the real values out of the game data and writes the changed lines back.

## Questions

### What is weapons.meta?

The GTA V file that defines weapons: name, model, damage, fire rate, range, ammo, flags and attachments. Addon weapons ship their own and load it with `data_file 'WEAPONINFO_FILE'`.

### How do I change fire rate in weapons.meta?

Edit `TimeBetweenShots` (seconds between shots). Lower is faster: 0.1 is 600 rounds per minute.

### How do I change magazine size?

Edit `ClipSize`. If the weapon uses component magazines, the component’s own clip size in weaponcomponents.meta applies when that magazine is attached.

### Why does my addon weapon not load?

A meta file failed to parse (often a typo in the XML), a `data_file` line points at the wrong path, or the model named in `Model` is not streamed. Check the F8 console for errors on join.

### Do the HudDamage values change damage?

No. They only draw the stat bars in menus. Real damage is `Damage` and the modifiers.

### Which data_file lines does an addon weapon need?

`WEAPONCOMPONENTSINFO_FILE`, `WEAPON_METADATA_FILE`, `WEAPON_ANIMATIONS_FILE`, `PED_PERSONALITY_FILE` and `WEAPONINFO_FILE`, pointing at the matching meta files.

## Related

- https://fam-tools.com/guides/fivem-katana-addon-weapon
- https://fam-tools.com/guides/fivem-weaponarchetypes-meta
- https://fam-tools.com/guides/fivem-weaponanimations-meta
- https://fam-tools.com/guides/fivem-weapon-damage-modifier
- https://fam-tools.com/guides/add-custom-weapons-to-fivem