How do I add an addon weapon to ESX?

Add an entry with name, label and components (and ammo and tints if it shoots) to Config.Weapons in shared/config/weapons.lua. The name must be the upper-case weapon name, for example WEAPON_MYRIFLE. Restart the server afterwards.

Do I need Config.Weapons when I use ox_inventory?

ox_inventory defines weapons as its own items, so the ESX loadout functions are disabled. es_extended still loads Config.Weapons, and shared helpers such as ESX.GetWeaponLabel keep using it.

Why does giving a weapon fail with "Invalid weapon name"?

ESX.GetWeapon and ESX.GetWeaponLabel assert that the name exists in Config.Weapons. Check spelling and add the weapon to the config if it is an addon weapon.

ESX Weapons Config (Config.Weapons)

How es_extended defines weapons, ammo types, components and tints in shared/config/weapons.lua, and how to add a custom or addon weapon to ESX Legacy.

shared/config/weapons.lua is the weapon catalog of es_extended. It defines which weapons exist in the default loadout system, their labels, ammo type, attachable components and tints. xPlayer weapon methods, the /giveweapon commands and the ESX.GetWeapon* helpers all read from it.

Overview

Fact	Value
File	`es_extended/shared/config/weapons.lua`
Side	Shared
Tables	`Config.DefaultWeaponTints`, `Config.MK2WeaponTints`, `Config.Weapons`
Entries	112 weapons and gadgets in 1.16.4
Helpers	`ESX.GetWeapon`, `ESX.GetWeaponFromHash`, `ESX.GetWeaponList`, `ESX.GetWeaponLabel`, `ESX.GetWeaponComponent` (shared functions)

Config.Weapons

An array of weapon definitions, grouped by comments into Melee, Handguns, Shotguns, SMG & LMG, Rifles, Sniper, Heavy / Launchers, Thrown and Tools.

Field	Type	Required	Description
`name`	`string`	Yes	Upper-case game name, for example `WEAPON_PISTOL`. Lookups convert input to upper case.
`label`	`string`	Yes	Display name, usually `TranslateCap("weapon_pistol")`.
`components`	`table[]`	Yes	Attachments, use `{}` for none. See below.
`ammo`	`table?`	No	`{ label, hash }`. `hash` is the ammo type hash, for example `AMMO_PISTOL`. Only for weapons that use ammo.
`tints`	`table?`	No	Tint labels by index. Usually `Config.DefaultWeaponTints` or `Config.MK2WeaponTints`. `xPlayer.setWeaponTint` only accepts indexes that exist here.
`throwable`	`boolean?`	No	`true` for grenades and similar. The weapon is removed from the loadout when its ammo reaches `0`.

Each component is { name, label, hash }:

Field	Type	Description
`name`	`string`	Short ESX name used in code and commands, for example `clip_extended`, `suppressor`, `flashlight`, `scope`, `grip`.
`label`	`string`	Display name.
`hash`	`number`	Game component hash, for example `COMPONENT_AT_PI_SUPP`.

shared/config/weapons.lua

{
    name = "WEAPON_COMBATPISTOL",
    label = TranslateCap("weapon_combatpistol"),
    ammo = { label = TranslateCap("ammo_rounds"), hash = `AMMO_PISTOL` },
    tints = Config.DefaultWeaponTints,
    components = {
        { name = "clip_default", label = TranslateCap("component_clip_default"), hash = `COMPONENT_COMBATPISTOL_CLIP_01` },
        { name = "clip_extended", label = TranslateCap("component_clip_extended"), hash = `COMPONENT_COMBATPISTOL_CLIP_02` },
        { name = "flashlight", label = TranslateCap("component_flashlight"), hash = `COMPONENT_AT_PI_FLSH` },
        { name = "suppressor", label = TranslateCap("component_suppressor"), hash = `COMPONENT_AT_PI_SUPP` },
    },
},

A melee weapon only needs the basics:

{ name = "WEAPON_BAT", label = TranslateCap("weapon_bat"), components = {} },

Tints

Table	Indexes	Used by
`Config.DefaultWeaponTints`	`0` to `7` (Default, Green, Gold, Pink, Army, LSPD, Orange, Platinum)	Regular weapons
`Config.MK2WeaponTints`	`0` to `32` (classic, contrast, bold and metallic finishes)	MK II weapons

xPlayer.setWeaponTint("WEAPON_PISTOL", 2) -- gold, from DefaultWeaponTints

Adding a custom weapon

Add the entry

Append your weapon to Config.Weapons. Use the exact spawn name from the weapon resource, in upper case.

{
    name = "WEAPON_M4CUSTOM",
    label = "M4 Custom",
    ammo = { label = TranslateCap("ammo_rounds"), hash = `AMMO_RIFLE` },
    tints = Config.DefaultWeaponTints,
    components = {
        { name = "clip_default", label = TranslateCap("component_clip_default"), hash = `COMPONENT_M4CUSTOM_CLIP_01` },
    },
},

Invalid weapon name! assertion: the weapon is not in Config.Weapons. ESX.GetWeapon, ESX.GetWeaponLabel and ESX.GetWeaponComponent all assert on unknown names.
Component cannot be added: the component name must exist in that weapon's components list, and the player must own the weapon.
Weapons from the old config disappeared after an update: loadout entries whose name is no longer in Config.Weapons are dropped when the character loads.

Frequently asked questions

Independent documentation

esx-fivem.com is a community project and is not affiliated with the ESX Framework team. Facts on this page were checked against the upstream source. Official resources: docs.esx-framework.org and github.com/esx-framework.

Weapons Config

Overview

Config.Weapons

Tints

Adding a custom weapon

Add the entry

Add a translation (optional)

Restart and test

Common issues

Frequently asked questions

On this page

Weapons Config

OverviewCopy Anchor Link

Config.WeaponsCopy Anchor Link

TintsCopy Anchor Link

Adding a custom weaponCopy Anchor Link

Add the entryCopy Anchor Link

Add a translation (optional)Copy Anchor Link

Restart and testCopy Anchor Link

Common issuesCopy Anchor Link

RelatedCopy Anchor Link

Frequently asked questions

How do I add an addon weapon to ESX?

Do I need Config.Weapons when I use ox_inventory?

Why does giving a weapon fail with "Invalid weapon name"?

On this page

Overview

Config.Weapons

Tints

Adding a custom weapon

Add the entry

Add a translation (optional)

Restart and test

Common issues

Related