> For the complete documentation index, see [llms.txt](https://docs.rainmad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rainmad.com/resources/gta-dual-wield-two-handed-weapons/configuration/weapons.md).

# Weapons

All dual weapons live in `cfg.weapons`. The table key is the **item name**: `rm_appistol_dual` is both the config key and the inventory item.

***

### Normal entries

Both hands hold the same weapon. All fields sit at the top level:

```lua
rm_appistol_dual = {
    label = 'AP Pistol', weapon = 'weapon_appistol', weaponHash = 584646201,
    animSet = 'small', ammo = 'dual_pistol_ammo',
    magazine_capacity = 18, max_ammo = 100, reload_time_ms = 1500,
    shot_interval = 80, recoilData = { recoil = 0.5, screenShake = 0.1 },
},
```

| Field               | Meaning                                                     |
| ------------------- | ----------------------------------------------------------- |
| `label`             | Display name in the HUD and notifications                   |
| `weapon`            | Vanilla weapon name                                         |
| `weaponHash`        | Numeric hash, must match `weapon`                           |
| `animSet`           | Which animation set to use (see below)                      |
| `ammo`              | Ammo item name that reloads this weapon                     |
| `magazine_capacity` | Rounds per magazine, **per hand**, before a reload triggers |
| `max_ammo`          | Total ammo cap per hand (magazine + reserve)                |
| `reload_time_ms`    | How long the reload animation locks the player              |
| `shot_interval`     | Minimum milliseconds between shots from the **same** hand   |
| `recoilData`        | `{ recoil, screenShake }`, reserved, not applied yet        |

{% hint style="info" %}
`magazine_capacity` and `max_ammo` are **per hand**. `max_ammo = 100` on a dual pistol means 100 rounds in the left gun and 100 in the right, 200 total.
{% endhint %}

***

### Combined entries

A different weapon in each hand. Per-side fields move into `left` and `right` subtables; everything shared stays at the top:

```lua
rm_chaos_dual = {
    label = 'Chaos (RPG + Minigun)',
    animSet = 'mini',              -- shared: favour the minigun's posture
    ammo = 'dual_minigun_ammo',    -- shared: one ammo item reloads both sides
    recoilData = { recoil = 0.5, screenShake = 0.1 },
    left = {
        weapon = 'weapon_rpg', weaponHash = 2982836145, label = 'RPG',
        magazine_capacity = 1, max_ammo = 5, reload_time_ms = 3500,
        shot_interval = 1500,
    },
    right = {
        weapon = 'weapon_minigun', weaponHash = 1119849093, label = 'Minigun',
        magazine_capacity = 5000, max_ammo = 20000, reload_time_ms = 4000,
        shot_interval = 30,
    },
},
```

**Shared at the top level:** `label`, `animSet`, `ammo`, `recoilData` **Per side:** `weapon`, `weaponHash`, `label`, `magazine_capacity`, `max_ammo`, `reload_time_ms`, `shot_interval`

Six combined weapons ship by default:

| Item                   | Left hand | Right hand        |
| ---------------------- | --------- | ----------------- |
| `rm_microassault_dual` | Micro SMG | Assault Rifle     |
| `rm_desperado_dual`    | Revolver  | Sawed-Off Shotgun |
| `rm_chaos_dual`        | RPG       | Minigun           |
| `rm_breacher_dual`     | SMG       | Pump Shotgun      |
| `rm_pyro_dual`         | Firework  | Grenade Launcher  |
| `rm_akimbo_dual`       | AP Pistol | Micro SMG         |

{% hint style="warning" %}
Combined weapons share **one** ammo item and **one** ammo pool split across the two sides. A `dual_minigun_ammo` item used on `rm_chaos_dual` fills both the RPG and the minigun. Pick the ammo item that matches the side you want players to resupply most.
{% endhint %}

***

### Animation sets

`animSet` picks the pose. Six sets ship in `stream/`:

| Set     | Posture                | Typical weapons                      |
| ------- | ---------------------- | ------------------------------------ |
| `small` | Relaxed two-hand       | Pistols, SMGs, compacts              |
| `gang`  | Sideways gangster hold | Heavy pistols, revolvers, micro SMGs |
| `long`  | Braced, longer weapons | Rifles, shotguns, railgun            |
| `mg`    | Machine gun stance     | MG                                   |
| `mini`  | Minigun stance         | Minigun                              |
| `rpg`   | Shoulder-fired         | RPG, homing launcher, firework       |

For combined weapons, use the set that suits the **larger** of the two weapons.

The `gang`, `mg` and `long` sets also override the walk clipset while moving. This exists to cancel the "sassy walk" that GTA otherwise blends in.

***

### Adding a weapon

1. Add an entry to `cfg.weapons`, keyed by your new item name.
2. Add the same item name to all three files in `[items]/`.
3. Make sure `weaponHash` matches `weapon`. A mismatch means that hand ends up holding the wrong gun.
4. Point `ammo` at an existing ammo item, or create a new one and add it to the item files too.

```lua
rm_carbinerifle_dual = {
    label = 'Carbine Rifle',
    weapon = 'weapon_carbinerifle', weaponHash = -2084633992,
    animSet = 'long', ammo = 'dual_rifle_ammo',
    magazine_capacity = 30, max_ammo = 250, reload_time_ms = 2000,
    shot_interval = 70, recoilData = { recoil = 1.0, screenShake = 0.2 },
},
```

{% hint style="info" %}
No client changes are needed. The weapon table is read at runtime on both sides and the animation set is looked up by name, so a restart is enough.
{% endhint %}

***

### Balancing notes

`shot_interval` is the single most important number for balance. It is a **hard floor between shots on one hand**, so the real DPS of a dual weapon is roughly:

```
shots per second = 2000 / shot_interval     (both hands firing)
```

A dual minigun at `shot_interval = 30` therefore produces about 66 shots per second. That is also the worst case for network traffic. See Rate Limits.

The default fire rates range from 30 ms (minigun) to 1500 ms (launchers).