Stream add-on weapons and custom loadouts

Custom weapons are second only to custom vehicles in popularity. The process is similar to vehicles but uses different metadata files. This lesson covers the full pipeline and the common mistakes that leave weapons invisible or unshootable.

You'll build: An add-on weapon resource with custom model, textures, and weapons.meta, then hand it out as an inventory item.
Time: ~20 minutes
You need: A local FiveM server, an add-on weapon download (folder with .yft/.ytd/weapons.meta).
You'll learn: Weapon asset types (.yft, .ytd, .meta), weapons.meta structure, data_file lines, and giving a weapon as an inventory item with /giveitem.

BEFORE YOU START

Build it

Prepare the resource

All files are in the right folders.

code

resources/my_weapon/
fxmanifest.lua
data/
weapons.meta
stream/
w_ar_myrifle.yft
w_ar_myrifle.ytd

An add-on weapon needs at minimum: the model (.yft), the textures (.ytd), and the metadata (.meta). Some downloads include sounds (.awc/.dat) - include those if present.

Check weapons.meta

You know the weapon's spawn name.

code

<Weapon type="WEAPON_MYRIFLE">
<modelName>w_ar_myrifle</modelName>
<animGroup>rifle</animGroup>
<ClipSize>30</ClipSize>
<Damage>35.000000</Damage>
<Recoil>0.350000</Recoil>
...
</Weapon>

The <modelName> is your spawn name. The <Weapon type> is a GTA weapon slot - adding to WEAPON_ASSAULTRIFLE means it shares ammo and animations with the assault rifle class.

Write fxmanifest

FiveM loads the weapon model, textures, and metadata.

code

fx_version 'cerulean'
game 'gta5'

files {
'data/weapons.meta',
'data/weaponanimations.meta',
'stream/*.yft',
'stream/*.ytd',
}

data_file 'WEAPONINFO_FILE_PATCH'    'data/weapons.meta'
data_file 'WEAPON_ANIMATIONS_FILE'   'data/weaponanimations.meta'

Use WEAPONINFO_FILE_PATCH (not the bare WEAPONINFO_FILE) for add-on weapons. WEAPONINFO_FILE replaces a whole weapon set; the _PATCH mounter adds your weapon on top of the existing set, which is what an add-on needs. The WEAPON_ANIMATIONS_FILE line loads weaponanimations.meta so the weapon is held and animated correctly. If your download has no weaponanimations.meta, drop that one line and its files {} entry.

Restart the resource. The weapon is now registered under the name in <Weapon type> (for example WEAPON_MYRIFLE), ready to be handed out as an inventory item in the next section.

Keep reading the full lesson

Still ahead in this lesson

Common failures