How to Add Custom Weapons to Your FiveM Server (2026)

Custom weapons are one of the fastest ways to give your FiveM server its own identity. Stock GTA weapons feel familiar to the point of being invisible — a custom Desert Eagle with unique animations, sounds, and stats tells players immediately that this is not just another default server.

The actual process involves three distinct layers: streaming the weapon model and textures to players, registering the weapon's stats via meta files, and optionally integrating it with your framework inventory (ESX or QBCore) so players can own, buy, and drop it. Each layer has its own failure modes. Here is how to handle all of them.

How Custom Weapon Streaming Works

FiveM streams assets to players in real time as they need them. When a player picks up or equips a custom weapon, the game client downloads the weapon's model, textures, and meta data from your server. If any piece of that is missing or misconfigured, the weapon either defaults to a GTA stock weapon, becomes invisible, or crashes the client.

Three types of files make a custom weapon work:

• Model files (.ydr) — the 3D geometry of the weapon
• Texture dictionary (.ytd) — the textures applied to the model
• Meta files (weapons.meta, weaponanimations.meta, weaponarchetypes.meta, weaponcomponents.meta) — the stats, animations, damage values and slot definitions

You need all of them. The model without meta files gives you a floating, non-functional prop. The meta files without a model crash clients.

Setting Up the Resource Folder

Create a dedicated resource for your weapon pack. Mixing weapon streaming assets into an unrelated resource makes future updates painful and debugging difficult.

resources/
└── [weapons]/
    └── custom-weapons/
        ├── fxmanifest.lua
        ├── stream/
        │   ├── w_pi_customdeagle.ydr
        │   ├── w_pi_customdeagle.ytd
        │   └── w_pi_customdeagle+hi.ytd   ← high-res texture (optional)
        └── data/
            ├── weapons.meta
            ├── weaponanimations.meta
            ├── weaponarchetypes.meta
            └── weaponcomponents.meta

The stream/folder is processed by FiveM's asset streaming system. Every file in here is automatically sent to clients. The data/ folder holds the meta files that define how the weapon behaves.

Writing the fxmanifest.lua

This is the file FiveM reads to understand your resource. For a weapon streaming resource, it looks like this:

fx_version 'cerulean'
game 'gta5'

name 'custom-weapons'
description 'Custom weapon pack'
version '1.0.0'

-- Tell FiveM about the data files
data_file 'WEAPONINFO_FILE_PATCH'     'data/weapons.meta'
data_file 'WEAPON_ANIMATIONS_FILE'    'data/weaponanimations.meta'
data_file 'WEAPONARCHETYPES_FILE'     'data/weaponarchetypes.meta'
data_file 'WEAPONCOMPONENTSINFO_FILE' 'data/weaponcomponents.meta'

-- Files list is automatically handled by stream/
files {
  'stream/**'
}

The data_file entries are critical. Each one uses a specific type keyword that FiveM uses to categorise the meta data. Using the wrong type for a file — or omitting a required one — results in weapons that load but behave incorrectly: wrong animations, invisible attachments, or crashes on equip.

The weapons.meta File

This is where you define the weapon's stats: damage, range, fire rate, reload time, accuracy, and the hash name FiveM and GTA use to identify the weapon internally. A minimal entry looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<CWeaponInfoBlob>
  <Infos>
    <Item type="CWeaponInfo">
      <Name>WEAPON_CUSTOMDEAGLE</Name>
      <Model>w_pi_customdeagle</Model>
      <Slot>PISTOL</Slot>
      <FireType>INSTANT_HIT</FireType>
      <Damage value="55.0" />
      <Speed value="1000.0" />
      <Capacity value="9" />
      <ReloadTimeMP value="1.8" />
      <AccuracySpread value="0.1" />
      <Range value="50.0" />
    </Item>
  </Infos>
</CWeaponInfoBlob>

The Name field is the weapon hash. It must be written in all-caps with underscores and begin with WEAPON_. This is how your framework scripts will reference the weapon — get it wrong and item lookups fail silently.

The Model field must exactly match the filename of your .ydr file without the extension.

Framework Integration — ESX

On ESX, weapons are items in the items database table. To make your custom weapon usable as a proper inventory item, add it to the database:

INSERT INTO items (name, label, weight, rare, can_remove)
VALUES ('weapon_customdeagle', 'Custom Deagle', 1500, 0, 1);

The name column must be the lowercase version of your weapon hash — ESX converts everything to lowercase when checking item names. Then in your weapon-giving script or shop:

-- Give a player the weapon with ammo
exports['es_extended']:getSharedObject(function(ESX)
  ESX.TriggerServerCallback('esx:giveWeapon', function()
    -- weapon given
  end, GetHashKey('WEAPON_CUSTOMDEAGLE'), 50)
end)

Framework Integration — QBCore

QBCore manages weapons through its item definitions in qb-core/shared/items.lua. Add your weapon there:

['weapon_customdeagle'] = {
  name         = 'weapon_customdeagle',
  label        = 'Custom Deagle',
  weight       = 1500,
  type         = 'weapon',
  ammotype     = 'AMMO_PISTOL',
  image        = 'weapon_customdeagle.png',  -- add image to qb-inventory
  unique       = true,
  useable      = false,
  shouldClose  = true,
  combinable   = nil,
  description  = 'A custom-built semi-automatic pistol.'
},

Drop the weapon image (a transparent-background PNG, 200×200px is standard) into qb-inventory/html/images/. Without the image, the inventory UI shows a broken image icon — the weapon still works, but it looks unfinished.

Common Errors and What They Mean

• Weapon spawns as a stock GTA weapon — the model name in weapons.meta does not match the .ydr filename in the stream folder. Both must be identical.
• Client crash on weapon equip — a meta file is missing or malformed. Check that all four meta files are present and that their XML is valid (no unclosed tags, no stray characters).
• Weapon is invisible / floating hands animation — the animation meta file references an animation that does not exist. Either add the animation file or reference an existing vanilla animation set.
• Wrong damage/fire rate — you have multiple weapons.meta entries defining the same weapon hash. FiveM loads them both and one overwrites the other. Make sure the hash is unique across all your resources.
• Weapon not appearing in inventory — the item name in your database or items.lua does not exactly match (lowercase, underscores) the hash used when giving the weapon.

Streaming Multiple Weapons Cleanly

A single resource can stream as many weapons as you like — there is no technical reason to split each weapon into its own resource. Keep all related weapons in one pack, with one manifest that declares all the data files. This keeps your server.cfg clean and reduces startup time.

The only reason to split weapons into separate resources is if you want to enable or disable specific weapon sets independently via txAdmin, which some servers do for seasonal or event-specific weapons.

If you want custom weapons without the setup headache, the weapon pack in this shop comes with 15 custom weapons fully configured — models, textures, meta files, and framework integration for both ESX and QBCore out of the box. Every weapon is tested in-game before release and includes a one-click install guide.