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

# Regear Command Configuration for PerPlayerKit

> Configure the /regear and /rg commands: set command or shulker mode, cooldowns, combat timers, and which items players can restock from their kit.

The regear system lets players quickly restock consumables and key items from their currently loaded kit mid-match — no need to open inventories or visit the kit room. Both `/rg` and `/regear` are separate commands that you can configure independently, giving you the flexibility to assign different behaviors to each alias. Cooldowns and a post-damage timer prevent abuse in competitive formats.

## Modes

<CardGroup cols={2}>
  <Card title="Command Mode" icon="terminal">
    Directly restocks whitelisted items from the player's loaded kit into their inventory. Instant and invisible — no physical block required. The `command-cooldown` governs how often a player can trigger it.
  </Card>

  <Card title="Shulker Mode" icon="box">
    Gives the player a physical shulker box. The player places it, opens it, and clicks the items they want to take. The shulker disappears after use. Ideal when you want players to make deliberate item-by-item choices.
  </Card>
</CardGroup>

## Full Configuration Block

```yaml config.yml theme={null}
regear:
  rg-mode: "command"
  regear-mode: "command"
  command-cooldown: 5
  damage-timer: 5
  allow-while-using-elytra: true
  invert-whitelist: false
  whitelist:
    - ENDER_PEARL
    - END_CRYSTAL
    - OBSIDIAN
    - GLOWSTONE
    - RESPAWN_ANCHOR
```

## Configuration Reference

<ParamField path="rg-mode" type="string" default="command">
  Controls the behavior of the `/rg` command. Accepted values: `"command"` or `"shulker"`.
</ParamField>

<ParamField path="regear-mode" type="string" default="command">
  Controls the behavior of the `/regear` command. Accepted values: `"command"` or `"shulker"`. Configure this independently from `rg-mode` to assign different behaviors to each alias.
</ParamField>

<ParamField path="command-cooldown" type="integer" default="5">
  The number of **seconds** a player must wait between successive uses of the regear command. Set to `0` to remove the cooldown entirely.
</ParamField>

<ParamField path="damage-timer" type="integer" default="5">
  The number of **seconds** a player must wait after taking damage before they can use the regear command. This prevents players from immediately restocking during active combat. Set to `0` to disable the damage restriction.
</ParamField>

<ParamField path="allow-while-using-elytra" type="boolean" default="true">
  Set to `false` to block players from triggering the regear command while they are gliding with an elytra. Useful for servers where mid-air restocking would be an unfair advantage.
</ParamField>

<ParamField path="invert-whitelist" type="boolean" default="false">
  When `false`, the `whitelist` is treated as an **allowlist** — only items on the list can be restocked. When `true`, the list becomes a **blacklist** — all items *except* those listed can be restocked. Set `invert-whitelist: true` with an empty `whitelist` to allow every item in the player's kit to be restocked.
</ParamField>

<ParamField path="whitelist" type="list">
  A list of Bukkit Material names (uppercase, underscore-separated). Determines which items the regear command restocks, subject to the `invert-whitelist` setting. Add any valid [Bukkit Material](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) name.
</ParamField>

## Example Configurations

<Tabs>
  <Tab title="Both commands — same mode">
    The simplest setup: both `/rg` and `/regear` behave identically.

    ```yaml config.yml theme={null}
    regear:
      rg-mode: "command"
      regear-mode: "command"
      command-cooldown: 5
      damage-timer: 5
      allow-while-using-elytra: true
      invert-whitelist: false
      whitelist:
        - ENDER_PEARL
        - END_CRYSTAL
        - OBSIDIAN
    ```
  </Tab>

  <Tab title="Different modes per command">
    Give `/rg` the quick command restock for veterans while `/regear` hands out a shulker for newer players who prefer to pick items manually.

    ```yaml config.yml theme={null}
    regear:
      rg-mode: "command"       # /rg  → instant restock
      regear-mode: "shulker"   # /regear → physical shulker box
      command-cooldown: 3
      damage-timer: 5
      allow-while-using-elytra: false
      invert-whitelist: false
      whitelist:
        - ENDER_PEARL
        - OBSIDIAN
    ```
  </Tab>

  <Tab title="Allow all items">
    Invert the whitelist with an empty list to let players restock every item from their kit without restriction.

    ```yaml config.yml theme={null}
    regear:
      rg-mode: "command"
      regear-mode: "command"
      command-cooldown: 10
      damage-timer: 5
      allow-while-using-elytra: true
      invert-whitelist: true   # empty list = no blacklist = all items allowed
      whitelist: []
    ```
  </Tab>
</Tabs>

<Note>
  When using **shulker mode**, a `command-cooldown` of `0` or a very low value is recommended. Because the player must physically place and interact with the shulker box, the mechanic itself already introduces natural pacing — a long cooldown on top of that creates a frustrating experience.
</Note>