# Replacing vanilla weapons or adding new ones

> The difference between replace and add-on weapons in FiveM: vanilla-name streaming versus new WEAPON_ names, data_file entries and the pros and cons.

Source: https://fam-tools.com/guides/fivem-replace-vs-addon-weapons · FAM Tools · published 2026-09-11 · updated 2026-09-11 · about 9 min

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

## Key points

- Replace = same filenames as vanilla; no meta needed.
- Add-on = new weapon name + meta files + `data_file` entries.
- Replaces change the weapon for everyone.
- Add-ons must be registered in your inventory.
- Skins from our studio are replaces for the vanilla weapon.

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.

## Side by side

|  | Replace | Add-on |
| --- | --- | --- |
| Weapon name | Vanilla (`WEAPON_PISTOL`) | New (`WEAPON_MYPISTOL`) |
| Files | `.ydr`/`.ytd` with vanilla names | Model, textures, meta files |
| Meta / data_file | Not needed for looks | Required |
| Inventory changes | None | New item and weapon entry |
| Both versions in game | No | Yes |
| Stats | Vanilla unless you also stream a meta | Your own |

## Replacing a vanilla weapon

*Resource layout*

```text
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](https://fam-tools.com/guides/codewalker-ytd-editing).

## Adding a new weapon

*fxmanifest.lua — add-on weapon*

```lua
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](https://fam-tools.com/guides/add-custom-weapons-to-fivem); then register it in [ox_inventory](https://fam-tools.com/guides/ox-inventory-weapon-setup), [QBCore](https://fam-tools.com/guides/qbcore-weapon-setup) or [ESX](https://fam-tools.com/guides/esx-weapon-setup).

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

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

## Related

- https://fam-tools.com/guides/add-custom-weapons-to-fivem
- https://fam-tools.com/guides/fivem-weapons-meta-explained
- https://fam-tools.com/guides/codewalker-ytd-editing
- https://fam-tools.com/guides/make-a-fivem-weapon-skin