How to Add Custom Weapons to Your FiveM Server (Addon vs Replace)

Custom weapons are the fastest way to make your server feel custom-built instead of copy-pasted. But "adding guns" covers two very different approaches, and picking the wrong one causes most of the problems people bring to our Discord.

Addon vs replace: know the difference

Replace weapons overwrite a vanilla GTA weapon's model. The M4 skin replaces the Carbine Rifle everywhere, for everyone.

• Zero new configuration — but you lose the original weapon
• One replace per base gun, so your arsenal is capped
• Damage, recoil and audio stay vanilla unless you hack the base metas

Addon weapons are entirely new weapons with their own name, stats, sounds and animations, sitting alongside the vanilla arsenal.

• Unlimited arsenal — vanilla stays untouched
• Per-weapon tuning: recoil, damage, audio, attachments
• The only approach that scales for a serious RP server

Every Kyros weapon pack is addon-based for exactly this reason — you can stack multiple packs into a 260-weapon arsenal without a single conflict.

What's actually inside a weapon resource

You don't need to touch these files with an escrowed pack, but knowing what they do makes debugging trivial:

• weapons.meta — the weapon's identity: hash, damage, range, clip size
• weaponarchetypes.meta — links the weapon to its model
• weaponanimations.meta — which animation set the weapon uses
• pedpersonality.meta — how peds hold and react to it
• Audio files — custom awc/dat sound banks for fire, tails and reloads
• Model/texture files — the .ydr/.ytd assets that stream to clients

Cheap packs skip proper audio banks and animation links — that's the "custom gun with vanilla pistol sound" effect you've heard on budget servers.

Installing a pack (the short version)

With an escrow-protected pack it's genuinely three steps: download from the Cfx.re Portal, drop into resources, add ensure to your server.cfg. The full install walkthrough covers escrow linking and the one entitlement error people hit.

Giving weapons to players

Addon weapons register with a spawn name (e.g. WEAPON_KYROS_AK). From there:

• QBCore: add the weapon to your qb-core/shared/weapons.lua (or use a pack that ships the file), then /giveitem [player] weapon_kyros_ak 1
• ESX: register it in your weapons table and grant via your admin menu or giveweapon
• QBox / ox_inventory: drop the provided item definitions into ox_inventory/data/weapons.lua
• Standalone: giveweapon from any admin resource, or the native GiveWeaponToPed

Quality packs ship these framework files for you. Kyros packs include ready-made definitions for QBCore, ESX, QBox and OX — check the framework tags on any product page.

Ammo, attachments and balancing

Three things to decide before launch day:

1. Ammo economy. Addon weapons use ammo types from their meta — make sure your inventory's ammo items match, or guns arrive empty.
2. Attachments. Good packs expose attachment components (suppressors, optics, grips) your inventory can attach as items.
3. Damage balance. Don't ship a 2x-damage rifle into an economy where guns are cheap. Tune damage in config or control access through pricing and crafting.

Troubleshooting the classics

• Invisible weapon: the model isn't streaming — check the resource started cleanly and you're not over the entity budget.
• Vanilla sound: the audio bank didn't load; confirm ensure order (audio resources often need to start before the weapon pack).
• "Attempted to load invalid weapon": typo in the spawn name, or the framework item doesn't match the weapon hash.
• Entitlement error: wrong Cfx.re account — the server key and the purchase must live on the same account.

Do it once, properly

Replace packs are a weekend experiment. Addon packs are infrastructure. If you want an arsenal with real recoil, layered audio and animations that match the gun in hand — built to stay green on resmon — browse the weapon packs, or grab a bundle and outfit the whole city at once.