> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/cas-gunsmith/configuration/weapons.md).

# Weapon Catalogue

The CAS Gunsmith weapon catalogue — the default 24 weapons, weapon definition fields, part categories, helper functions, and how to add or remove weapons.

Only weapons defined in `Config.Weapons` appear on the bench. A weapon in the player's inventory is recognised when its item name matches the `hash` field.

## Default weapons

| Class    | Weapons                                                             |
| -------- | ------------------------------------------------------------------- |
| Revolver | Cattleman, Double-Action, Schofield, LeMat, Navy                    |
| Pistol   | Mauser, Semi-Automatic, Volcanic, M1899                             |
| Repeater | Carbine, Litchfield, Evans, Lancaster                               |
| Rifle    | Varmint, Springfield, Bolt Action, Elephant, Carcano, Rolling Block |
| Shotgun  | Pump-Action, Repeating, Double-Barreled, Sawed-Off, Semi-Auto       |

## Weapon fields

```lua
cattleman = {
  hash = 'WEAPON_REVOLVER_CATTLEMAN', class = 'revolver', arm = 'SHORTARM', label = 'Cattleman Revolver',
  caliber = '.45 Long Colt', maker = 'Pickett & Sons Arms Co.', icon = 'weapon_revolver_cattleman',
  base = { damage = 52, accuracy = 46, range = 40, fireRate = 50, reload = 44 }, ammo = ammoSet('REVOLVER'),
  parts = {
    barrel = barrels('REVOLVER_CATTLEMAN', 32), sight = sights('REVOLVER_CATTLEMAN'), rifling = rifling('SHORTARM'),
    grip = grips('REVOLVER_CATTLEMAN', { 'IRONWOOD', 'EBONY', 'BURLED', 'PEARL' }),
  },
  vertdata = { C('SHORTARM_ROLE_ENGRAVING_CATTLEMAN_LEGENDARY') },
},
```

| Field              | Description                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hash`             | In-game weapon name. Must be the same as the item name in the inventory.                                                                                             |
| `class`            | `revolver`, `pistol`, `repeater`, `rifle` or `shotgun`. Sets the supported categories, the metal parts and the carry limit.                                          |
| `arm`              | Shared component group: `SHORTARM` or `LONGARM`. Finish, tint and engraving components are chosen by this group.                                                     |
| `label`            | Name shown in the interface when the inventory has no custom name.                                                                                                   |
| `caliber`, `maker` | Shown on the record card.                                                                                                                                            |
| `icon`             | Weapon image. The file name in `web/dist/tex/items/` without `.png`.                                                                                                 |
| `base`             | Base values in the statistics panel (0 to 100).                                                                                                                      |
| `ammo`             | Selectable ammo types. The first type is the factory ammo.                                                                                                           |
| `parts`            | Part categories and options.                                                                                                                                         |
| `wraps`            | Optional. The weapon's wrap components.                                                                                                                              |
| `vertdata`         | Optional. Special edition engraving components. They break the other colours, so they are removed from the displayed model only. The player's weapon is not touched. |

{% hint style="info" %}
`base` and `stats` values are shown in the statistics panel. The weapon's in-game behaviour is set by the game component that is fitted.
{% endhint %}

## Part categories

Categories allowed in `parts`: `barrel`, `rifling`, `sight`, `scope`, `forend`, `grip`, `stock`. A category not defined on the weapon shows as **Unavailable** in the interface.

Each option takes these fields:

| Field          | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `id`           | Unique id within the weapon.                                           |
| `name`, `desc` | Name and description shown in the interface.                           |
| `comp`         | Game component to fit. If `nil`, no component is fitted.               |
| `stock`        | If `true`, this is the factory part and it is free.                    |
| `price`        | Price in dollars.                                                      |
| `stats`        | Stat effect, for example `{ accuracy = 5, range = 9, fireRate = -2 }`. |
| `lock`         | Optional rank lock, `{ rank = N }`.                                    |

## Helper functions

Most weapons build their part lists with the functions below. Edit these functions to change prices and descriptions in one place.

| Function                      | List it builds                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| `barrels(prefix, longPrice)`  | Standard and long barrel.                                                                  |
| `sights(prefix)`              | Narrow and wide sight.                                                                     |
| `rifling(arm)`                | Standard and re-cut rifling.                                                               |
| `grips(prefix, list)`         | Handgun grips: `IRONWOOD`, `EBONY`, `BURLED`, `PEARL`.                                     |
| `stocks(prefix, list)`        | Long gun stocks: `IRONWOOD`, `ENGRAVED`, `BURLED`, `EBONY`, `EXOTIC`.                      |
| `forends(prefix, kind, list)` | Forends. `kind` is `CLIP` or `MAG`, depending on the in-game component name.               |
| `SCOPES`                      | Iron sights plus short, medium and long scope.                                             |
| `wraps(prefix, names)`        | The weapon's wrap components. The order matches the `slot` numbers in `Config.WrapStyles`. |

`prefix` is the part of the component name after `COMPONENT_`, for example `REVOLVER_CATTLEMAN`.

## Adding and removing weapons

To remove a weapon, delete its table. The weapon no longer appears on the bench. The weapon in the player's inventory is not affected.

To add a new weapon:

1. Add a table with a new key to `Config.Weapons`.
2. Set `hash` to the same name as the inventory item.
3. In the part lists, use only game components that really exist on that weapon. A component that does not belong to the weapon will not show in game.
4. Make sure an image for `icon` exists in `web/dist/tex/items/`.
5. Restart the resource.