Custom FiveM weapon skins — how they actually work

A weapon in GTA V is a fragment model (`.yft`) plus one or more texture dictionaries (`.ytd`), described by metadata files that tell the game its name, its stats, its components and how it appears in the inventory. A skin changes the textures; an add-on weapon changes everything.

There are two ways to give players a different-looking gun, and they have very different costs.

local weapon = GetSelectedPedWeapon(cache.ped)
SetPedWeaponTintIndex(cache.ped, weapon, 3)

Most "weapon skin" packs sold for FiveM are actually add-on weapons: a copy of the base model with a new texture and a new name, so the skinned version can exist alongside the original as a separate inventory item.

fx_version 'cerulean'
game 'gta5'

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

data_file 'WEAPONINFO_FILE'       'meta/weapons.meta'
data_file 'WEAPON_METADATA_FILE'  'meta/weaponarchetypes.meta'
data_file 'WEAPON_COMPONENTS_FILE' 'meta/weaponcomponents.meta'

1. 1Put the yft and ytd files in `stream/`.
2. 2Declare every meta file in `files` and register it with the matching `data_file` type.
3. 3Give the weapon a unique name — collisions with another pack silently break both.
4. 4Restart the server fully. Weapon metadata is only parsed at startup.
5. 5Test spawning it, aiming, reloading and every attachment before you give it to players.

This trips up nearly everyone who edits a weapon texture for the first time. Many weapon models include emissive shells — extra geometry that draws light on top of the body, using shaders like `emissivestrong`. The glow mask usually lives in the texture's alpha channel, not its colour.

• If you paint over the diffuse of an emissive shell, the whole gun lights up white.
• If you flatten the alpha channel while re-saving a YTD, the glow mask disappears or covers everything.
• Some models reuse the opaque body texture on an additive shell — editing it doubles the body and blows out the highlights.
• The fix is to identify which textures belong to glow geometry and leave their alpha intact, or edit only the non-emissive diffuse maps.

The practical rule: open the model, find which drawables use emissive shaders, and treat their textures as off-limits unless you specifically want to change the glow.

A streamed weapon that the inventory does not know about shows as a missing item. ox_inventory keeps weapons in its own weapons file, and every entry needs a matching square image.

['WEAPON_PTY_STORMBORN'] = {
  label = 'Stormborn Rifle',
  weight = 3200,
  durability = 0.03,
  ammoname = 'ammo-rifle',
  components = { 'at_scope_medium', 'at_suppressor_light' },
},

• The key must exactly match the weapon name in weapons.meta, including case.
• Item images go in ox_inventory's images folder as PNG, named in lowercase after the item — 512×512 with a transparent background is the safe standard.
• Set a sensible weight. A rifle that weighs the same as a pistol makes the whole weight system feel arbitrary.
• If you use a different inventory, the concept is identical: an item definition plus an image.

• Every add-on weapon is permanent client memory, loaded whether anyone owns it or not.
• Twenty to forty custom weapons is a comfortable catalogue. Two hundred is a memory problem you will not diagnose easily.
• Prefer a small set of high-quality signature weapons over every free pack you can find.
• Audit any free weapon pack the same way you audit any other resource — check for scripts you did not expect.

Skins built from real-world brand logos, football club badges or other people's artwork are a takedown waiting to happen, and they are a recurring reason servers get reported. Use original artwork, commissioned designs, or your own server's identity. It is also better branding — a gun with your gang's emblem on it means something; a gun with a sportswear logo does not.