How to Make Custom Weapons for FiveM From a 3D Model

Most FiveM weapon guides show you how to install a gun someone else made. This one shows how to make custom weapons for FiveM from your own 3D model: a pistol, rifle, launcher or melee weapon that is new to your server, not a skin over a stock gun.

The short version: choose a weapon class, line the model's grip up with the in-game hand, place the muzzle and shell eject, set the stats and export. Then start the resource from server.cfg and give yourself the weapon by its WEAPON_ name. You need:

• a gun or melee model in .glb, .gltf, .obj, .fbx or .stl, with PNG, JPEG or WebP textures, that you have the right to use;
• a FiveM server where you can edit server.cfg;
• a Discord account to sign in to the Weapon Creator, which is in beta. Free accounts get one export per day.

Add-on weapon or replacement skin

A replacement streams a file with the same name as a base-game asset, such as w_pi_pistol.ydr. Every stock pistol on the server then uses your model.

An add-on weapon has its own name, such as WEAPON_TACTICAL_PISTOL, and its own model, so the stock weapons stay as they are. This guide builds add-ons. The Weapon Creator refuses the 158 base-game weapon names and 120 weapon model names, because reusing one would replace that weapon for the whole server. Stock model names such as w_pi_pistol are listed in the GTA V object catalog.

How a GTA V add-on weapon works

An add-on weapon is a .ydr model with a small skeleton, plus four data files. Three bones do most of the work:

• Gun_GripR: where the right hand holds the weapon. In every animation, the game lines this bone up with the ped's right-hand bone, PH_R_Hand. If the mesh sits wrong relative to it, the gun floats next to the hand or points the wrong way.
• Gun_Muzzle: where the muzzle flash and the bullets start.
• Gun_VFX_Eject: where spent shells fly out.

The firing effects look these bones up, and a weapon model with no skeleton can crash the game when it fires. The four data files are:

File	Manifest type	What it does
weapons.meta	WEAPONINFO_FILE	The weapon itself: name, model, ammo, sound, damage, range, clip size and fire rate
weaponarchetypes.meta	WEAPON_METADATA_FILE	Registers the model name, its texture dictionary name and its draw distance
weaponanimations.meta	WEAPON_ANIMATIONS_FILE	The animation clip sets a ped uses to hold, aim, fire and reload the weapon
pedpersonality.meta	PED_PERSONALITY_FILE	Movement and holster animations for peds carrying it

By hand, you copy a vanilla weapon's entries into all four files and rename every reference (our weapons.meta guide explains each field). The Weapon Creator builds them from the vanilla weapon of the class you pick, so your weapon keeps that weapon's skeleton, animations, sounds and firing behavior.

How to make custom weapons for FiveM in 7 steps

Steps 2 to 7 happen in the Weapon Creator, where one project becomes one FiveM resource.

Step 1: Prepare your model

• 16 materials at most per weapon. Merge them first: the editor warns you when a model has more.
• Power-of-two textures (512, 1024, 2048 or 4096 px). Other sizes are rounded down on each side, so 1000 px becomes 512 px. Free exports cap textures at 1024 px, Supporter exports at 4096 px.
• A light mesh. The export simplifies meshes above 150,000 triangles and halves a model's textures until they fit in 60 MB. Every player has to stream the weapon.
• Matching texture names. Textures are matched to the model by file name: a model that asks for wood.tga picks up a dropped wood.png. The editor can't load TGA files, so convert them to PNG.
• Only the weapon. Delete helper and stand-in meshes before you export the file from your 3D app.

Step 2: Import the model and pick the weapon class

Sign in, then create a project by name, or drop the model with its textures on Drop your 3D model here (up to 100 MB per file). The project name becomes the resource folder (Gang weapons gives gang-weapons) and must start with a letter, so for a file like 1911.glb, create the project by name first. Add more weapons to the same resource with the Add weapon drop zone.

The editor turns each model barrel-forward and lines it up with the class's vanilla weapon. It rescales a gun only if it's under half or over double the vanilla length, and a knife or bat only if it's under 10 cm or over 1.5 m.

New weapons start in the Pistol class. Once the model has loaded, pick its class under Weapon class. The class sets the animations, sounds, fire behavior and weapon wheel slot. Changing it resets the stats, audio and ammo, so pick the class before you tune anything.

Class in the editor	Built on	Wheel slot	Full auto
Pistol (1-handed)	WEAPON_PISTOL	Pistols	No
Combat Pistol	WEAPON_COMBATPISTOL	Pistols	No
AP Pistol	WEAPON_APPISTOL	Pistols	Yes
Assault Rifle	WEAPON_ASSAULTRIFLE	Rifles	Yes
Carbine Rifle	WEAPON_CARBINERIFLE	Rifles	Yes
SMG	WEAPON_SMG	SMGs and MGs	Yes
Machine Pistol	WEAPON_MACHINEPISTOL	SMGs and MGs	Yes
Shotgun	WEAPON_PUMPSHOTGUN	Shotguns	No
Sniper Rifle	WEAPON_SNIPERRIFLE	Snipers	No
Machine Gun	WEAPON_COMBATMG	SMGs and MGs	Yes
Minigun	WEAPON_MINIGUN	Heavy	Yes
RPG / Launcher	WEAPON_RPG	Heavy	No
Melee (knife)	WEAPON_KNIFE	Melee	-
Melee (bat)	WEAPON_BAT	Melee	-

"Full auto" means the vanilla weapon carries the Automatic weapon flag, which the export keeps. All 14 classes are open on every account. AP Pistol and Machine Pistol haven't been tested in game yet.

Step 3: Fit the grip in the hand

The viewport shows a GTA V ped holding your model in the class's real aiming pose. Switch to Idle (bottom right) to check the relaxed hold too. The red Palm point is the vanilla weapon's Gun_GripR: move the model until its handle sits on it.

• Click the model and use Move (W), Rotate (E) and Scale (R), along the weapon's own axes (Local) or the world axes (Global).
• For exact values, use the Transform section: position is in meters, with X along the barrel, Y to the left and Z up.
• Leave Vanilla reference: outline and box on (it's on by default) to compare your model with the stock weapon of that class.
• On two-handed classes the left-hand point stays where the vanilla weapon has it, so line your foregrip up with the vanilla outline.

The preview uses the game's own grip rule, confirmed in game, so the hold you set here is the hold you get on the server.

Step 4: Place the muzzle and shell eject

Click the orange Muzzle label and drag it to the end of your barrel, then drag the yellow Shell eject label to the ejection port. Each label has a reset button that puts it back where the vanilla weapon has it. Only these two bones move: the rest of the vanilla skeleton is exported unchanged.

The RPG has a muzzle but no shell eject, and its rocket bones move with the muzzle. The knife and the bat have neither point.

Step 5: Set damage, range, clip size and fire rate

The Stats section starts at the vanilla values of the class. For the Pistol that's 26 damage, a 120 m range, 12 rounds and 162 rounds per minute. Each control writes one field of weapons.meta:

Control	Range	Writes
Damage	0 to 500	Damage
Range (m)	1 to 2,000	WeaponRange
Clip size	1 to 15,000	ClipSize
Rounds per minute	1 to 6,000	TimeBetweenShots (60 ÷ rpm)
Reload speed ×	0.1 to 5	AnimReloadRate
Headshot ×	1 to 50	HeadShotDamageModifierPlayer
Ammo type	The class's ammo types	AmmoInfo

The Audio set menu picks the gunshot sound from 16 vanilla sets. The knife and the bat hide clip size, fire rate, ammo and audio. The export also scales the weapon's stat bars to match your numbers. A higher fire rate doesn't make a class full auto: that comes from the class itself. Our guide weapons.meta explained covers each field and the stock values of all 14 classes.

Step 6: Name the weapon and pick a wheel icon

Under Weapon Configuration, the display name comes from the file name, and the weapon hash and model name follow it until you edit them:

• Display name (weapon wheel): what players see, up to 64 characters.
• Weapon hash: the name you give the weapon by, WEAPON_ plus up to 40 capital letters, digits or underscores. "Tactical Pistol" becomes WEAPON_TACTICAL_PISTOL.
• Model name (.ydr / spawn): the name of the .ydr and its meta folder, here tacticalpistol. It takes 3 to 63 lowercase letters, digits or underscores, and can't end in _hi, which GTA keeps for high-detail models.

Base-game names get a live warning such as "WEAPON_PISTOL is a base-game weapon". Names must be unique in the project, and clashes get a number, so knife.glb becomes WEAPON_KNIFE_2.

The wheel icon is optional and in beta. In Weapon Wheel Icon, turn on Show this weapon in the wheel (it's off for new weapons), then keep the default icon, the FiveM Tools logo, or drop a PNG, JPEG or WebP. Images are trimmed and scaled down to fit the slot, never up, so use a large side view on a transparent background.

Step 7: Export the resource

Click Export. The Export weapon pack window lists each weapon, for example Tactical Pistol: WEAPON_TACTICAL_PISTOL · tacticalpistol · Pistol (1-handed). A red line (a repeated or base-game name, or more than 16 materials) keeps the Export button disabled until you fix it. If a weapon uses a wheel icon, an Enable hud.gfx switch appears, on by default.

The server builds the models and sends you a zip named after the project. One export covers every weapon in the project (up to 5 on a free account, 50 for Supporters), and a failed export doesn't use up your daily export.

What's in the exported resource

A project called Gang weapons with two weapons exports this folder:

gang-weapons/
  fxmanifest.lua
  cl_weaponNames.lua
  README.txt
  meta/
    tacticalpistol/
      weapons.meta
      weaponarchetypes.meta
      weaponanimations.meta
      pedpersonality.meta
    desertrifle/
      (the same four files)
  stream/
    tacticalpistol.ydr
    desertrifle.ydr
    hud.gfx            (only when wheel icons are on)

The fxmanifest.lua registers every meta file with a data_file line, grouped by type, with weapons.meta last:

fx_version 'cerulean'
game 'gta5'

author 'TeK - FiveM-Tools.com'
description '2 add-on weapons (generated by fivem-tools.com)'

files {
    'meta/**/*.meta',
}

data_file 'WEAPON_METADATA_FILE' 'meta/tacticalpistol/weaponarchetypes.meta'
data_file 'WEAPON_METADATA_FILE' 'meta/desertrifle/weaponarchetypes.meta'
data_file 'WEAPON_ANIMATIONS_FILE' 'meta/tacticalpistol/weaponanimations.meta'
data_file 'WEAPON_ANIMATIONS_FILE' 'meta/desertrifle/weaponanimations.meta'
data_file 'PED_PERSONALITY_FILE' 'meta/tacticalpistol/pedpersonality.meta'
data_file 'PED_PERSONALITY_FILE' 'meta/desertrifle/pedpersonality.meta'
data_file 'WEAPONINFO_FILE' 'meta/tacticalpistol/weapons.meta'
data_file 'WEAPONINFO_FILE' 'meta/desertrifle/weapons.meta'

client_script 'cl_weaponNames.lua'

Files in stream/ are streamed automatically, so the models need no line. Our fxmanifest.lua guide covers the rest of the manifest.

cl_weaponNames.lua gives each weapon its display name. The export sets HumanNameHash in weapons.meta to the weapon hash, so this text is what the weapon wheel shows:

AddTextEntry("WEAPON_TACTICAL_PISTOL", "Tactical Pistol")
AddTextEntry("WEAPON_DESERT_RIFLE", "Desert Rifle")

Each weaponarchetypes.meta holds one entry that registers the model:

<CWeaponModelInfo__InitDataList>
  <InitDatas>
    <Item>
      <modelName>tacticalpistol</modelName>
      <txdName>tacticalpistol</txdName>
      <ptfxAssetName>NULL</ptfxAssetName>
      <lodDist value="30" />
    </Item>
  </InitDatas>
</CWeaponModelInfo__InitDataList>

lodDist is the draw distance of the class's vanilla weapon: 30, 50 or 100. The textures are embedded in the .ydr, so there is no separate .ytd.

Each .ydr is your mesh on the class's vanilla skeleton, at one detail level, with DXT1 or DXT5 textures. It's a PC Legacy (Gen8, RSC7) file, the format classic FiveM servers stream. FiveM for GTA V Enhanced loads assets from stream_enhanced, and Cfx.re offers a converter called Alchemist, but these exports haven't been tested on Enhanced servers (see the Legacy vs Enhanced notes). For the file types in general, read GTA V file formats explained.

How to add custom weapons to FiveM: install and test

1. Copy the gang-weapons folder from the zip into your server's resources folder.
2. Add ensure gang-weapons to server.cfg.
3. Restart the server, or run refresh and then ensure gang-weapons in the server console. If the weapon doesn't show up after a live start, reconnect.
4. Give yourself the weapon by its weapon hash, not its model name.

The README in the zip lists the native call for each weapon. It gives your ped the weapon with 250 rounds and puts it in your hand:

GiveWeaponToPed(PlayerPedId(), GetHashKey("WEAPON_TACTICAL_PISTOL"), 250, false, true)

The README also mentions /giveweapon WEAPON_TACTICAL_PISTOL, but the resource registers no commands, so that only works if your admin menu or framework has one. On a private test server, a small client command does the job:

-- Test servers only: any player can run this command.
RegisterCommand('testgun', function()
    GiveWeaponToPed(PlayerPedId(), GetHashKey('WEAPON_TACTICAL_PISTOL'), 250, false, true)
end, false)

Frameworks and inventories such as ESX, qb-core and ox_inventory keep their own weapon and item lists, and the export doesn't touch them. Add the weapon there, as your framework's docs describe, before players can carry it as an item.

Then test it the way players will: aim, idle, walk, run, first person (V), cover, a full magazine and a reload.

Troubleshooting custom weapons

Problem	Cause and fix
Giving the weapon does nothing	Use the weapon hash, not the model name. Check that the resource started, and reconnect after a live start.
The gun floats, sits sideways or is the wrong size	Put the handle on the Palm point, match the vanilla outline (resize with Scale, R), check the Aiming and Idle poses, and export again.
Muzzle flash or shells in the wrong place	Move the Muzzle or Shell eject point and export again.
Parts of the model are one flat color	Those materials had no diffuse texture, and the export window warns about it. Drop the textures with the model and convert TGA files to PNG.
Textures look blurry	Power-of-two rounding (1000 px becomes 512 px), the 1024 px free cap, or halving when one model needs more than 60 MB.
No icon in the weapon wheel	Turn on Show this weapon in the wheel, keep Enable hud.gfx on, reconnect, and check that no other resource streams a hud.gfx.
Another pack's wheel icons disappeared	Only one hud.gfx works per server. Put all your weapons in one project, or export with Enable hud.gfx off.
The Export button stays disabled	Fix the red line in the export window: a repeated or base-game name, or more than 16 materials.

Limits of the Weapon Creator

• No attachments or components. No weaponcomponents.meta is generated, so there are no suppressors, scopes, flashlights or extended clips.
• One detail level and no collision. Each weapon is a single model, with no _hi version and no collision mesh.
• The material tint is baked in. It colors the texture. It isn't GTA's weapon tint system.
• No framework setup. The export doesn't add the weapon to ESX, qb-core or ox_inventory, and it registers no /giveweapon command.
• Beta parts. The tool and the wheel icon (one hud.gfx per server, built for game build 3889) are in beta, and the AP Pistol and Machine Pistol classes haven't been tested in game.
• Plan limits. Free: 1 export per day (reset at midnight UTC), 5 weapons per project and 1024 px textures. Supporter ($15/month): unlimited exports, 50 weapons per project and 4096 px textures. See pricing.

Frequently asked questions

Do I need ZModeler, OpenIV or CodeWalker to make a FiveM weapon?

Not with the Weapon Creator. You fit the model in the browser editor, and the server builds the .ydr and all four meta files. By hand, you build the .ydr with Blender and the Sollumz add-on or with ZModeler 3, take the skeleton from a vanilla weapon with OpenIV or CodeWalker, and write the meta files yourself.

Can I add attachments like a suppressor or a scope to a custom weapon?

Not in the current Weapon Creator, which writes no weaponcomponents.meta. By hand, each attachment needs its own model, an entry in weaponcomponents.meta and an attach point in the weapon's weapons.meta, and the components file has to load before weapons.meta.

Can I make a custom melee weapon for FiveM?

Yes. Pick the Melee (knife) or Melee (bat) class, which reuse the animations of the vanilla knife or bat. Melee classes have no clip size, fire rate, ammo type, sound set, muzzle or shell eject, and the vanilla knife and bat have a Damage value of 0, so test any damage change in game.

Can I give a custom FiveM weapon its own gunshot sound?

Not with the Weapon Creator. Its Audio set menu picks one of 16 vanilla sound sets, from Pistol to Combat MG and RPG, and the export writes that choice to the Audio field of weapons.meta. A new gunshot sound needs its own game audio files and audio data, which the tool does not make.

Can I change a weapon's stats after exporting it?

Yes. Open the weapons.meta in the weapon's meta folder (for example meta/tacticalpistol/weapons.meta), change values such as Damage, ClipSize or TimeBetweenShots (60 divided by the rounds per minute), then restart the resource and reconnect. You can also change the stats in the editor and export again, which uses your daily export on a free account.