weapons.meta Explained: Damage, Range, Clip and Fire Rate

weapons.meta is the GTA V data file that defines a weapon: its name, model, sound, ammo type, damage, range, clip size and fire rate. In FiveM, an add-on weapon ships its own weapons.meta in a resource and loads it with a data_file 'WEAPONINFO_FILE' line, next to three smaller files: weaponarchetypes.meta, weaponanimations.meta and pedpersonality.meta.

Below are the fields add-on weapon authors change most, with the exact tags the Weapon Creator (beta) writes and the stock values of the 14 vanilla weapons it builds on. The examples come from a pistol-class add-on called WEAPON_TACTICAL_PISTOL. To build one from your own model, follow how to make custom weapons for FiveM.

How a GTA 5 weapons.meta file is laid out

weapons.meta is plain XML. Under the CWeaponInfoBlob root, SlotNavigateOrder gives the weapon's slot an order number, and each <Item type="CWeaponInfo"> under Infos is one weapon. This is the tactical pistol's file, with long runs of fields cut:

<CWeaponInfoBlob>
  <SlotNavigateOrder>
    <Item>
      <WeaponSlots>
        <Item>
          <OrderNumber value="5399" />
          <Entry>SLOT_WEAPON_TACTICAL_PISTOL</Entry>
        </Item>
      </WeaponSlots>
    </Item>
  </SlotNavigateOrder>
  <Infos>
    <Item>
      <Infos>
        <Item type="CWeaponInfo">
          <Name>WEAPON_TACTICAL_PISTOL</Name>
          <Model>tacticalpistol</Model>
          <Audio>AUDIO_ITEM_PISTOL</Audio>
          <Slot>SLOT_WEAPON_TACTICAL_PISTOL</Slot>
          <DamageType>BULLET</DamageType>
          <!-- ... -->
          <FireType>INSTANT_HIT</FireType>
          <WheelSlot>WHEEL_PISTOL</WheelSlot>
          <Group>GROUP_PISTOL</Group>
          <AmmoInfo ref="AMMO_PISTOL" />
          <AimingInfo ref="PISTOL_2H_BASE_STRAFE" />
          <ClipSize value="12" />
          <!-- ... -->
          <HeadShotDamageModifierPlayer value="20.000000" />
          <Damage value="26.000000" />
          <!-- ... -->
          <AnimReloadRate value="1.000000" />
          <BulletsPerAnimLoop value="1" />
          <TimeBetweenShots value="0.370000" />
          <!-- ... -->
          <LockOnRange value="55.000000" />
          <WeaponRange value="120.000000" />
          <!-- ... -->
          <HumanNameHash>WEAPON_TACTICAL_PISTOL</HumanNameHash>
          <!-- ... -->
          <HudDamage value="26" />
          <HudSpeed value="40" />
          <HudCapacity value="10" />
          <HudAccuracy value="40" />
          <HudRange value="25" />
        </Item>
      </Infos>
    </Item>
  </Infos>
  <!-- ... -->
</CWeaponInfoBlob>

A value is either a number in a value attribute (<ClipSize value="12" />), text between the tags (<FireType>INSTANT_HIT</FireType>) or a ref to an entry the game already defines (<AmmoInfo ref="AMMO_PISTOL" />).

Damage, range, clip and fire rate fields

The Weapon Creator has a control for each of these fields and keeps your value inside the range shown:

Field	What it sets	Stock pistol	Weapon Creator control
Damage	Damage of one bullet	26	Damage, 0 to 500
WeaponRange	How far a shot reaches, in meters	120	Range (m), 1 to 2,000
ClipSize	Rounds per magazine	12	Clip size, 1 to 15,000
TimeBetweenShots	Seconds between two shots	0.37	Rounds per minute, 1 to 6,000
AnimReloadRate	Speed of the reload animation	1.0	Reload speed ×, 0.1 to 5
HeadShotDamageModifierPlayer	Headshot damage multiplier	20	Headshot ×, 1 to 50
AmmoInfo	Ammo type	AMMO_PISTOL	Ammo type
Audio	Gunshot sound set	AUDIO_ITEM_PISTOL	Audio set

Numbers are written with six decimals, as in the game's files: a damage of 40 becomes 40.000000. The knife and bat classes have no clip size, fire rate, ammo or sound to edit.

Damage, pellets and falloff

BulletsInBatch is the number of pellets per shot: 8 on the pump shotgun and 1 on every other class. The RPG, knife and bat have Damage 0 in the vanilla files. The RPG's DamageType is EXPLOSIVE, so it hurts through its explosion. On the knife and bat, test any Damage change in game.

DamageFallOffRangeMin, DamageFallOffRangeMax and DamageFallOffModifier shape damage over distance: 40, 120 and 0.3 on the stock pistol. The Weapon Creator copies them from the class, so a longer WeaponRange doesn't move them. Edit them by hand if you want full damage farther out.

weapons.meta fire rate: TimeBetweenShots

There's no rounds-per-minute field. The fire rate is TimeBetweenShots, the seconds between two shots, so rounds per minute = 60 ÷ TimeBetweenShots. The stock pistol's 0.37 is about 162 rpm. The Weapon Creator writes 60 ÷ rpm, so 600 rpm becomes 0.100000, and a rate within half a round of the stock value keeps the stock number exactly.

A shorter TimeBetweenShots doesn't make a weapon full auto. That comes from the Automatic flag in WeaponFlags, which the Weapon Creator keeps from the class (see the Full auto column below).

Headshots, reload and lock-on

HeadShotDamageModifierPlayer is 20 on the pistol and combat pistol and 18 on the other templates. It's the only headshot field the editor writes. Others stay as they are, such as NetworkHeadShotPlayerDamageModifier (2.0 on the pistol) and MaxHeadShotDistancePlayer (40 m, or 300 m on the sniper rifle), so test headshots between two players before you balance them.

AnimReloadRate is 1.0 on every template, and higher values speed up the reload animation. LockOnRange (55 m on the pistol) is a separate lock-on distance that the editor leaves alone.

Ammo and sound

Weapons with the same AmmoInfo type share one ammo count, so a custom pistol on AMMO_PISTOL uses the stock pistols' rounds. The SMG and Machine Pistol classes can switch to pistol ammo, and the Machine Gun to rifle ammo. Audio picks the gunshot sound from 16 vanilla sets.

The HUD stat bars

HudDamage, HudSpeed, HudCapacity, HudAccuracy and HudRange are 0 to 100 values for the stat bars the game shows for the weapon (26, 40, 10, 40 and 25 on the stock pistol). As the names say, they're for the HUD: the gun's real behavior comes from the fields above, and the bars don't update when you change those by hand.

On gun classes, the Weapon Creator scales four bars by the same ratio as your stats, rounded and kept between 0 and 100. HudAccuracy stays as it is, because there's no accuracy control. For an Assault Rifle class weapon set to 40 damage, 600 rpm, a 45-round clip and a 200 m range:

Bar	Stock rifle	Calculation	Your weapon
HudDamage	30	30 × 40 ÷ 30	40
HudSpeed	60	60 × 0.158 ÷ 0.1	95
HudCapacity	40	40 × 45 ÷ 30	60
HudAccuracy	45	not changed	45
HudRange	45	45 × 200 ÷ 120	75

HudSpeed uses the ratio of the two TimeBetweenShots values, so a faster gun gets a longer bar. When the stock Damage is 0 (RPG, knife and bat), HudDamage keeps its stock value.

Name, Model and blocked base-game names

These fields tie the files, the model and your scripts together, so check them first when a weapon won't load:

• Name: the weapon hash, WEAPON_TACTICAL_PISTOL. You give the weapon by this name, and the other meta files use it too.
• Model: tacticalpistol, which must match the .ydr in stream/ and the modelName in weaponarchetypes.meta.
• Slot and Entry: SLOT_WEAPON_TACTICAL_PISTOL. Each installed weapon needs its own OrderNumber, so the Weapon Creator derives a fixed one from the weapon hash (5399 here).
• HumanNameHash: the text label of the in-game name, such as WT_PIST on the stock pistol. The export sets it to the weapon hash, and cl_weaponNames.lua adds the text with AddTextEntry.

Reusing a base-game Name or Model replaces that weapon or model for everyone on the server. So the Weapon Creator refuses 158 weapon names and 120 model names from the game's weapons meta files, including non-weapons the game uses as causes of damage, such as WEAPON_FALL and WEAPON_RUN_OVER_BY_CAR. It also refuses model names ending in _hi, which GTA keeps for high-detail models. Stock models such as w_pi_pistol are listed in the GTA V object catalog.

Stock values for 14 vanilla weapons

Apart from the fields above, the Weapon Creator copies every field unchanged from the vanilla weapon of the class, including FireType, DamageType, Group, WheelSlot, BulletsInBatch, the Explosion block, the cameras, WeaponFlags, and spread and recoil fields such as AccuracySpread and RecoilShakeHash. They go with that weapon's animations and effects, so change them only if you know what they do. These are the stock values of its 14 templates:

Class	Template	FireType	Damage	Range (m)	Clip	rpm	Full auto
Pistol (1-handed)	WEAPON_PISTOL	INSTANT_HIT	26	120	12	162	No
Combat Pistol	WEAPON_COMBATPISTOL	INSTANT_HIT	27	120	12	162	No
AP Pistol	WEAPON_APPISTOL	INSTANT_HIT	25	120	18	600	Yes
Assault Rifle	WEAPON_ASSAULTRIFLE	INSTANT_HIT	30	120	30	380	Yes
Carbine Rifle	WEAPON_CARBINERIFLE	INSTANT_HIT	32	120	30	444	Yes
SMG	WEAPON_SMG	INSTANT_HIT	22	120	30	508	Yes
Machine Pistol	WEAPON_MACHINEPISTOL	INSTANT_HIT	27	120	12	508	Yes
Shotgun	WEAPON_PUMPSHOTGUN	INSTANT_HIT	29 (8 pellets)	40	8	75	No
Sniper Rifle	WEAPON_SNIPERRIFLE	DELAYED_HIT	101	1,500	10	38	No
Machine Gun	WEAPON_COMBATMG	INSTANT_HIT	45	120	100	556	Yes
Minigun	WEAPON_MINIGUN	INSTANT_HIT	30	120	15,000	3,000	Yes
RPG / Launcher	WEAPON_RPG	PROJECTILE	0	85	1	75	No
Melee (knife)	WEAPON_KNIFE	MELEE	0	1.6	-	-	-
Melee (bat)	WEAPON_BAT	MELEE	0	1.6	-	-	-

The rpm column is 60 ÷ TimeBetweenShots, rounded. Group and WheelSlot don't always match: the combat MG is GROUP_MG in the WHEEL_SMG slot. The AP Pistol and Machine Pistol classes haven't been tested in game yet.

The other three weapon meta files

Three smaller files register the model and tell peds how to hold and carry the weapon. The Weapon Creator builds each one from the class's vanilla weapon, with your names in place.

weaponarchetypes.meta

Loaded with WEAPON_METADATA_FILE, it registers the model:

<CWeaponModelInfo__InitDataList>
  <InitDatas>
    <Item>
      <modelName>tacticalpistol</modelName>
      <txdName>tacticalpistol</txdName>
      <ptfxAssetName>NULL</ptfxAssetName>
      <lodDist value="30" />
    </Item>
  </InitDatas>
</CWeaponModelInfo__InitDataList>

txdName names the texture dictionary, the .ytd that holds a model's textures (see GTA 5 file formats explained). The Weapon Creator embeds the textures in the .ydr instead, so it ships no .ytd. lodDist is the vanilla weapon's draw distance: 30, 50 or 100 depending on the class.

weaponanimations.meta

Loaded with WEAPON_ANIMATIONS_FILE, it maps the weapon to animation clip sets in each animation set: eight for the pistol, from Default and Gang to FirstPersonScope. Every entry is keyed by your Name, and its clip sets are the vanilla weapon's. That's how an add-on weapon reuses the stock animations:

<Item key="Default">
  <WeaponAnimations>
    <Item key="WEAPON_TACTICAL_PISTOL">
      <!-- ... -->
      <MotionClipSetHash>weapons@pistol@pistol</MotionClipSetHash>
      <!-- ... -->
      <WeaponClipSetHash>weapons@pistol@pistol</WeaponClipSetHash>
      <!-- ... -->
    </Item>
  </WeaponAnimations>
</Item>

pedpersonality.meta

Loaded with PED_PERSONALITY_FILE, it sets the holster clips and movement clip sets peds use with the weapon. Your Name goes in every Weapons list, under the UNHOLSTER_ entries and movement modes such as DEFAULT_ACTION:

<Item>
  <Name>DEFAULT_ACTION</Name>
  <MovementModes>
    <Item>
      <Item>
        <Weapons>
          <Item>WEAPON_TACTICAL_PISTOL</Item>
        </Weapons>
        <ClipSets>
          <!-- MOVE_ACTION@P_M_ZERO@ARMED@CORE and other clip sets -->
        </ClipSets>
      </Item>
    </Item>
    <!-- ... -->
  </MovementModes>
</Item>

Loading weapons.meta in FiveM with WEAPONINFO_FILE

This is the fxmanifest.lua the Weapon Creator writes for one weapon:

fx_version 'cerulean'
game 'gta5'

author 'TeK - FiveM-Tools.com'
description 'Add-on weapon WEAPON_TACTICAL_PISTOL (generated by fivem-tools.com)'

files {
    'meta/**/*.meta',
}

data_file 'WEAPON_METADATA_FILE' 'meta/tacticalpistol/weaponarchetypes.meta'
data_file 'WEAPON_ANIMATIONS_FILE' 'meta/tacticalpistol/weaponanimations.meta'
data_file 'PED_PERSONALITY_FILE' 'meta/tacticalpistol/pedpersonality.meta'
data_file 'WEAPONINFO_FILE' 'meta/tacticalpistol/weapons.meta'

client_script 'cl_weaponNames.lua'

• files sends the meta files to every player.
• Each data_file line gives one file its type. weapons.meta is WEAPONINFO_FILE.
• The export lists weapons.meta last, and the Cfx.re forum's guide to streaming add-on weapons gives the same rule: components first, weapons.meta last.
• client_script runs the AddTextEntry line that names the weapon.

Some guides use WEAPONINFO_FILE_PATCH instead, and sources disagree on which one add-on weapons need. The Weapon Creator uses WEAPONINFO_FILE. Our fxmanifest.lua guide covers the other data_file types.

To install and test the resource:

1. Add ensure tactical-pistol (the resource's folder name) to server.cfg.
2. Restart the server. If you start the resource on a running server instead, reconnect before you test.
3. Give yourself the weapon by its Name, for example with GiveWeaponToPed(PlayerPedId(), GetHashKey("WEAPON_TACTICAL_PISTOL"), 250, false, true) in a client script.

The .meta files are plain XML, but the Weapon Creator's .ydr models are PC Legacy (Gen8, RSC7) files, the format classic FiveM servers use. FiveM for GTA V Enhanced loads assets from stream_enhanced, and Cfx.re offers a converter called Alchemist, but these exports haven't been verified on Enhanced servers (see the Legacy vs Enhanced notes).

Frequently asked questions

Where is weapons.meta in GTA 5?

In the base game it sits in update/update.rpf at common/data/ai/weapons.meta, and DLC packs add their own weapons meta files for the weapons they introduced. OpenIV or CodeWalker can open them. On a FiveM server you don't edit the game files: you ship your own weapons.meta in a resource and load it with a data_file 'WEAPONINFO_FILE' line.

Why doesn't my add-on weapon show up in FiveM?

Check the names first. The Name in weapons.meta, the Item keys in weaponanimations.meta, the weapon lists in pedpersonality.meta and your give command must all use the same WEAPON_ name, and the Model must match the .ydr file and the modelName in weaponarchetypes.meta. Then check that fxmanifest.lua lists every meta file with its data_file line and that server.cfg ensures the resource. If you started it on a running server, reconnect.

How do I make a weapon full auto in weapons.meta?

Full-auto fire comes from the Automatic flag in the WeaponFlags list, not from TimeBetweenShots, which only sets the time between two shots. The vanilla AP pistol, assault rifle, carbine, SMG, machine pistol, combat MG and minigun carry the flag. In the Weapon Creator, pick a class built on one of them. If you add the flag by hand to a semi-automatic weapon, test it in game.

What is the difference between weapons.meta and weaponarchetypes.meta?

weapons.meta defines how the weapon works: its name, model, ammo, sound, damage, range, clip size and fire rate. weaponarchetypes.meta registers the model itself: its model name, texture dictionary name and draw distance (lodDist). An add-on weapon needs both, plus weaponanimations.meta and pedpersonality.meta.

How do I change a stock weapon's damage in FiveM?

Copy that weapon's entry from the game's weapons.meta, change Damage or any other field, and load the file from a resource with a data_file line, as you would for an add-on weapon. Keeping the stock Name, such as WEAPON_PISTOL, replaces that weapon's data for everyone on the server. The Weapon Creator doesn't do this: it only makes add-on weapons and refuses base-game names.