> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shdevelopment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# sh-weaponspawner: ACE-Gated Weapon Spawner for FiveM

> sh-weaponspawner provides an ACE-permission-gated weapon spawner menu for authorized players. Configurable categories, ammo, and access levels.

sh-weaponspawner gives your server's staff and authorized groups an in-game menu for spawning weapons directly to their inventory, organized into named categories such as pistols and rifles. Like sh-vehiclespawner, access is controlled entirely through FiveM's native ACE permission system — no framework dependency, no database, and no additional UI library beyond WarMenu. You define which groups see which categories, and the resource enforces it server-side.

<Note>
  sh-weaponspawner follows the same ACE permission model as [sh-vehiclespawner](/fivem/sh-vehiclespawner). If you have already configured ACE groups for sh-vehiclespawner, you can reuse those groups here with only the node names changed.
</Note>

## Requirements

sh-weaponspawner depends on [warmenu](https://github.com/warxander/warmenu). Ensure `warmenu` is started **before** `sh-weaponspawner` in your `server.cfg`. No SQL import is required.

## Installation

<Steps>
  <Step title="Download and place the resource">
    Copy the `sh-weaponspawner` folder into your server's `resources` directory alongside `warmenu`.
  </Step>

  <Step title="Add to server.cfg">
    ```cfg server.cfg theme={null}
    ensure warmenu
    ensure sh-weaponspawner
    ```
  </Step>

  <Step title="Configure config.lua">
    Open `sh-weaponspawner/config.lua` and define your categories, weapon entries, and ammo amounts as described below.
  </Step>

  <Step title="Add ACE permission nodes">
    Grant the appropriate ACE nodes to your staff and player groups as shown in the [Permissions](#permissions) section.
  </Step>

  <Step title="Restart the resource">
    Run `refresh` then `restart sh-weaponspawner` in the server console, or perform a full server restart.
  </Step>
</Steps>

## Core Configuration

The table below covers the top-level options in `config.lua`. All values shown are the shipped defaults.

```lua config.lua theme={null}
Config.Debug                = false  -- Enable debug prints to server console
Config.Keybind              = 'F6'
Config.MenuTitle            = 'Weapon Spawner'

-- Menu appearance (RGBA; set to nil to use WarMenu defaults)
Config.MenuBackgroundColor       = {r=0, g=0, b=0, a=160}
Config.MenuTitleColor            = {r=255, g=255, b=255, a=255}
Config.MenuTitleBackgroundColor  = nil
Config.MenuTitleBackgroundImage  = {td = 'images', name = 'menubg'}
Config.MenuTextColor             = {r=255, g=255, b=255, a=255}
Config.MenuFocusColor            = {r=255, g=255, b=255, a=100}
Config.MenuFocusTextColor        = {r=0, g=0, b=0, a=255}
Config.MenuWidth                 = nil   -- 0.0–1.0, nil = WarMenu default (~0.23)
Config.MenuX                     = 0.77  -- 0.0 = left edge, 1.0 = right edge

Config.CloseMenuOnWeaponGrab = true  -- Auto-close the menu after grabbing a weapon

-- Notification system
Config.NotifySystem  = 'sh-notify'  -- 'mythic_notify' | 'ox_lib' | 'sh-notify' | nil (print fallback)
Config.NotifyType    = 'error'
Config.DenyMessage   = "No permission to open menu! Check permissions."
```

The menu opens with the **F6** key by default. Players can remap this in the GTA V pause menu under **Settings → Key Bindings → FiveM**.

## Permissions

sh-weaponspawner uses the same three-tier ACE pattern as sh-vehiclespawner: an **open** node to access the menu at all, an **all** node to bypass category restrictions, and individual **category** nodes for granular control.

<Tabs>
  <Tab title="server.cfg">
    ```cfg server.cfg theme={null}
    # Admins: full access to every weapon category
    add_ace group.admin weaponspawner.open   allow
    add_ace group.admin weaponspawner.all    allow

    # Police: menu access plus rifles only (pistols are open to all menu users)
    add_ace group.police weaponspawner.open    allow
    add_ace group.police weaponspawner.rifles  allow
    ```
  </Tab>

  <Tab title="config.lua (permission nodes)">
    ```lua config.lua theme={null}
    Config.EnablePermissions       = true
    Config.OpenPermission          = 'weaponspawner.open'
    Config.AllCategoriesPermission = 'weaponspawner.all'

    Config.CategoryPermissions = {
        pistols = nil,                    -- No permission required for this category
        rifles  = 'weaponspawner.rifles', -- Requires this ACE node
        -- Add entries for any additional categories you define
    }
    ```
  </Tab>
</Tabs>

<Note>
  `weaponspawner.all` bypasses every category-level check. Reserve this node for server owners and senior staff only.
</Note>

## Defining Weapon Categories

Weapons are defined in `Config.Weapons` as a list of category objects. Each category has a `name` that maps to the permission key in `Config.CategoryPermissions`, and a `list` of weapon entries. The category `name` must match its key in `Config.CategoryPermissions` exactly.

```lua config.lua theme={null}
Config.Weapons = {
    { name = "pistols", list = {
        { label = "Pistol",        value = "WEAPON_PISTOL",        ammo = 250 },
        { label = "Combat Pistol", value = "WEAPON_COMBATPISTOL",  ammo = 250 },
        { label = "AP Pistol",     value = "WEAPON_APPISTOL",      ammo = 250 },
    }},
    { name = "rifles", list = {
        { label = "Assault Rifle", value = "WEAPON_ASSAULTRIFLE",  ammo = 500 },
        { label = "Carbine Rifle", value = "WEAPON_CARBINERIFLE",  ammo = 500 },
        { label = "Sniper Rifle",  value = "WEAPON_SNIPERRIFLE",   ammo = 100 },
    }},
    -- Add more categories as needed (melee, heavy, etc.)
}
```

### Weapon Entry Fields

| Field   | Type    | Description                                               |
| ------- | ------- | --------------------------------------------------------- |
| `label` | string  | Display name shown in the spawner menu                    |
| `value` | string  | GTA V weapon hash name (all caps, e.g. `WEAPON_PISTOL`)   |
| `ammo`  | integer | Ammo amount added alongside the weapon; use `0` for melee |

<Tip>
  A full list of GTA V weapon hash names is available through the [FiveM natives reference](https://docs.fivem.net/docs/game-references/weapon-models/). Always use the all-caps `WEAPON_` prefixed hash string, not the numeric hash.
</Tip>

## Pairing with sh-vehiclespawner

<Accordion title="Consistent ACE group setup for admin tooling">
  If you run both sh-weaponspawner and sh-vehiclespawner on the same server, use identical group names for both resources so a single `add_principal` or `add_ace` line covers a player's access across both scripts.

  ```cfg server.cfg theme={null}
  # Admin group — full vehicle and weapon spawner access
  add_ace group.admin vehiclespawner.open allow
  add_ace group.admin vehiclespawner.all  allow
  add_ace group.admin weaponspawner.open  allow
  add_ace group.admin weaponspawner.all   allow

  # Assigning a player to the admin group
  add_principal identifier.license:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX group.admin
  ```

  This pattern scales cleanly: define your groups once, then add ACE nodes as you install new SH Development resources.
</Accordion>

<Warning>
  sh-weaponspawner spawns weapons directly into the player's inventory without a confirmation prompt. Do not grant `weaponspawner.open` to regular players on a roleplay server where weapon possession is roleplayed — restrict it to staff and whitelisted groups only.
</Warning>