FAM Tools
Sign in
Weaponsbeginner9 min readupdated 11 Sept 2026

Replacing vanilla weapons or adding new ones

The short answer

A replace streams files with vanilla names (for example w_pi_pistol.ydr/.ytd), so the existing WEAPON_PISTOL changes look for everyone — no meta files needed. An add-on adds a new WEAPON_… with its own model, weapons.meta, weaponarchetypes.meta, weaponanimations.meta and data_file lines, and must be added to your inventory. Use replaces for skins and vanilla overhauls; add-ons when players should have both.

There are two ways to get a new gun into FiveM. You can replace a vanilla weapon — every Pistol now looks like your model — or add a brand-new weapon with its own name that sits next to the originals. Replacing is simpler; add-ons are more flexible. Most servers use both.

Replacing vanilla weapons or adding new ones — illustrated with a FiveM-compatible minimap render

#Side by side

ReplaceAdd-on
Weapon nameVanilla (WEAPON_PISTOL)New (WEAPON_MYPISTOL)
Files.ydr/.ytd with vanilla namesModel, textures, meta files
Meta / data_fileNot needed for looksRequired
Inventory changesNoneNew item and weapon entry
Both versions in gameNoYes
StatsVanilla unless you also stream a metaYour own

#Replacing a vanilla weapon

Resource layout
pistol_skin/
  fxmanifest.lua   -- fx_version, game
  stream/
    w_pi_pistol.ydr
    w_pi_pistol.ytd
    w_pi_pistol+hi.ytd

Files in stream/ with vanilla names override the originals. Include the +hi files the vanilla weapon uses, or first-person view keeps the old look — see editing YTDs.

#Adding a new weapon

fxmanifest.lua — add-on weapon
fx_version 'cerulean'
game 'gta5'

files {
    'meta/weapons.meta',
    'meta/weaponarchetypes.meta',
    'meta/weaponanimations.meta',
}

data_file 'WEAPONINFO_FILE' 'meta/weapons.meta'
data_file 'WEAPON_METADATA_FILE' 'meta/weaponarchetypes.meta'
data_file 'WEAPON_ANIMATIONS_FILE' 'meta/weaponanimations.meta'

Some weapons also ship pedpersonality.meta (PED_PERSONALITY_FILE), loadouts.meta (LOADOUTS_FILE) or weaponcomponents.meta (WEAPONCOMPONENTSINFO_FILE). The full walkthrough is in adding custom weapons; then register it in ox_inventory, QBCore or ESX.

#Which to choose

  • Want the police Pistol to look better? Replace.
  • Want a Glock and the vanilla Pistol available separately? Add-on.
  • Want different damage for one variant? Add-on (or a meta override for the vanilla weapon).
  • Selling skins? Replaces are the easiest for buyers.
Share this guideXRedditFacebook

Questions

What is a replace weapon in FiveM?
Model and texture files streamed with vanilla names, so an existing weapon looks different for everyone.
What is an add-on weapon?
A new weapon with its own name, model and meta files that exists alongside the vanilla ones.
Do replace weapons need weapons.meta?
Not for the look. You only stream a meta if you also want to change stats.
Why does my add-on weapon not appear in the inventory?
It must be added to your inventory’s weapon and item lists, not only streamed.

Ready to pick a map?

Twelve themes on three base map styles, $8 each, instant download.

Relevant to what you just read

Look it up while you work

The reference tables this guide leans on, free and without an account.