How to add a custom weapon to a FiveM server

#What an addon weapon actually is

An addon weapon is a normal FiveM resource that streams a model and registers a weapon definition with the game engine. Nothing about it is special — it is a folder in resources/ with an fxmanifest.lua, exactly like a script. What makes it a weapon is the metadata it declares.

A complete weapon resource has three kinds of file, and every one of them matters:

• The model files (.ydr) — the geometry of the gun itself, plus one per attachment or magazine.
• The texture dictionary (.ytd) — the images painted onto that geometry. This is the file a skin changes.
• The meta files (.meta) — XML that tells the engine the weapon's name, damage, ammo type, clip size and which model to use.

#Install it, step by step

1. Copy the weapon folder into your server's resources/ directory. Most servers group content, so resources/[weapons]/my_weapon is a good home.
2. Open the folder and confirm it has an fxmanifest.lua. If it does not, the pack is not a resource yet and you will need to write one — see the manifest section below.
3. Add ensure my_weapon to your server.cfg. Use the folder name exactly, including case.
4. Restart the server fully the first time. A refresh + ensure works for script changes, but streamed assets and meta files are only read at startup.
5. Watch the server console as it boots. A weapon resource that loads cleanly says nothing; a broken one names the file it could not read.
6. Join the server and give yourself the weapon to confirm the model appears before you touch the inventory side.

That last step is the one people skip, and it is the one that saves the most time. If the model shows up in your hands, the streaming and meta side is done and any remaining problem is inventory configuration. If it does not, the problem is in the files and no amount of inventory editing will help.

#The fxmanifest, and why weapons need data_file lines

A script resource only needs to list its Lua files. A weapon resource additionally has to hand its meta files to the engine using data_file entries, and it has to do so with the correct type for each file. Get the type wrong and the file is silently ignored.

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

name 'my_weapon'
author 'Your name'
description 'Custom addon weapon'
version '1.0.0'

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

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

Two rules catch people out. Every meta file must appear twice — once in the files block so it is packaged, and once in a data_file line so it is registered. And the model files never need listing at all: anything inside a stream/ folder is picked up automatically.

#Registering it in your inventory

The engine now knows the weapon. Your framework does not. Which file you edit depends on what you run, and this is the only part that differs between servers:

• ox_inventory — add an entry to data/weapons.lua and drop a PNG into web/images/.
• QBCore — add an entry to qb-core/shared/weapons.lua and drop a PNG into your inventory's images folder.
• ESX — modern setups run ox_inventory, so follow that; older ones register the weapon in their own weapon list.
• No framework — nothing to do. The weapon already works with give-weapon commands.

Whichever you use, the item name must match the weapon's Name value from weapons.meta exactly. On ox_inventory that is the uppercase name itself (WEAPON_MYGUN); on QBCore it is the same name lowercased (weapon_mygun). A mismatch here is the single most common reason a weapon exists in game but cannot be given.

#The weapon is invisible or the player holds nothing

The model did not stream. Check that the .ydr files are inside a stream/ folder, that the resource actually started (look for it in the console output), and that the Model value in weapons.meta matches the .ydr filename without its extension.

#The weapon is solid pink or bright white

The model loaded but its textures did not. Either the .ytd is missing from stream/, or another resource is streaming a texture dictionary with the same name and winning. Renaming the dictionary is the reliable fix.

#The console says the weapon is not valid

The meta files did not register. Nine times out of ten a data_file line is missing, misspelled, or points at a path that does not exist. Compare yours against the manifest above line by line.

#It works for you but not for other players

You almost certainly have the files cached locally from testing. Ask someone who has never joined before, or clear your own FiveM cache, before concluding it works.

#A shortcut, if you want one

Everything above is the manual route, and it is worth understanding once. If you would rather not assemble it by hand, every weapon in our library exports as a finished resource — manifest written, data_file lines correct, item images rendered and inventory entries generated for ox_inventory, QBCore and ESX. Your first weapon is free, so you can compare a working resource against your own and see exactly what differs.