# Weapons Config (/docs/es_extended/config/weapons)

`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 [#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](/docs/es_extended/shared)) |

## Config.Weapons [#configweapons]

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` ``. |

```lua title="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:

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

## Tints [#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 |

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

## Adding a custom weapon [#adding-a-custom-weapon]

<Steps>
<Step>
### Add the entry [#add-the-entry]

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

```lua
{
    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` },
    },
},
```
</Step>
<Step>
### Add a translation (optional) [#add-a-translation-optional]

If you use `TranslateCap("weapon_m4custom")`, add the key to the locale files in `es_extended/locales`. A plain string works too.
</Step>
<Step>
### Restart and test [#restart-and-test]

Restart the server and run `/giveweapon me weapon_m4custom 100`.
</Step>
</Steps>

## Common issues [#common-issues]

- **`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.

## Related [#related]

- [xPlayer weapon methods](/docs/es_extended/server/xplayer#weapons)
- [Shared functions](/docs/es_extended/shared)
- [Commands](/docs/es_extended/commands)
- [Main config](/docs/es_extended/config)