> For the complete documentation index, see [llms.txt](https://oph3zdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oph3zdev.gitbook.io/docs/paid-scripts/inventory/configuration/weapons.md).

# Weapons

Everything in <mark style="color:$primary;">config/weapons.lua</mark> - the workbench, attachments, repairs and serial filing. Where workbenches stand in the world (`Config.Workbenches`, `Config.WorkbenchRequired`, `Config.NoModifyWeapons`) is set in <mark style="color:$primary;">config/config.lua</mark>. The weapon items themselves live in <mark style="color:$primary;">`config/weapons_items.lua`</mark>.

### Workbench

The 3D weapon workbench where attachments are mounted, paints applied and repairs done.

* `enabled` - `false` = no workbench anywhere, weapons are plain items.
* `strictComponents` - `true` = hide attachments the game says do not fit that weapon model.

```lua
Config.WeaponWorkbench = {
    enabled = true,
    strictComponents = false
}
```

### Draw and holster animations

Played when a weapon is drawn or put away. `default` is the fallback, `groups` overrides per game weapon group. `enabled = false` skips them all.

```lua
Config.WeaponAnimations = {
    enabled = true,

    default = {
        equip = { dict = "reaction@intimidation@1h", clip = "intro", time = 1200 },
        holster = { dict = "reaction@intimidation@1h", clip = "outro", time = 1400 }
    },

    groups = {
        GROUP_MELEE = {
            equip = { dict = "melee@holster", clip = "unholster", time = 200 },
            holster = { dict = "melee@holster", clip = "holster", time = 600 }
        },
        GROUP_PISTOL = {
            equip = { dict = "reaction@intimidation@cop@unarmed", clip = "intro", time = 400 },
            holster = { dict = "reaction@intimidation@cop@unarmed", clip = "outro", time = 450 }
        }
    }
}
```

### Attachment anchors

Where attachment previews snap onto the weapon model in the workbench view. The bone names are read from the weapon model per slot - most servers never touch this.

```lua
Config.WeaponAnchorBones = {
    muzzle = { "WAPSupp", "WAPSupp_2", "gun_muzzle" },
    clip = { "WAPClip", "WAPClip_2", "gun_magazine" },
    flashlight = { "WAPFlshLasr", "WAPFlshLasr_2", "WAPFlsh", "WAPLasr" },
    scope = { "WAPScop", "WAPScop_2", "WAPScop_3" },
    grip = { "WAPGrip", "WAPGrip_2" },
    paint = { "gun_root", "WAPGrip" }
}
```

Fine tune a single weapon when a preview sits slightly off.

```lua
Config.WeaponAnchors = {
    -- weapon_pistol = { muzzle = vector3(0.0, 0.0, 0.02) }
}
```

### Weapon tints

`false` = the paint slot is hidden everywhere and paint items cannot be applied.

```lua
Config.WeaponTints = {
    enabled = true
}
```

### Attachment effects

Real gameplay effects on top of what the game does. `clip` adds extra rounds to the magazine, `damage` is a damage multiplier. `items` sets the effect per attachment, `slots` is the fallback for a whole slot. `enabled = false` = attachments only do what GTA does natively.

```lua
Config.AttachmentEffects = {
    enabled = true,
    items = {
        ["at_clip_extended_pistol"] = { clip = 6 },
        ["at_clip_drum_rifle"] = { clip = 70 },
        ["at_suppressor_light"] = { damage = 0.9 },
        ["at_barrel"] = { damage = 1.1 }
    },
    slots = {
        clip = { clip = 10 }
    }
}
```

### Weapon repair

Weapons lose durability with use and can be repaired with kit items.

* `requireWorkbench` - repairing always needs a workbench, even when modifying does not.
* `time` + `animation` - how long the repair takes (milliseconds) and the animation played.
* `kits` - which items repair, how much durability each restores, and whether the kit is consumed.
* `brokenBlocksModify` / `brokenBlocksLoad` - a broken weapon cannot be modified or loaded until repaired.

```lua
Config.WeaponRepair = {
    enabled = true,
    requireWorkbench = true,
    time = 8000,
    animation = { dict = "mini@repair", clip = "fixing_a_ped", flag = 49 },
    kits = {
        repairkit_weapon = { restore = 50, consume = true },
        repairkit_weapon_pro = { restore = 100, consume = true }
    },
    brokenBlocksModify = true,
    brokenBlocksLoad = true
}
```

### Serial filing

A criminal feature, off by default: file the serial number off a weapon so it cannot be traced.

* `tool` + `consumeTool` - the item needed and whether it is used up.
* `time` + `animation` - how long it takes (milliseconds) and the animation played.

```lua
Config.SerialFiling = {
    enabled = false,
    requireWorkbench = true,
    tool = "weapon_file",
    consumeTool = false,
    time = 12000,
    animation = { dict = "mini@repair", clip = "fixing_a_ped", flag = 49 }
}
```