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

# Keybind Listeners

> Intercept standard Minecraft key inputs and execute actions.

Keybind listeners allow you to repurpose standard Minecraft keys for custom server mechanics. Each keybind supports enabled/disable, cancel action, delay, cooldown, drop count, hotbar slot targeting, and criteria conditions.

## ⌨ Available Input Types

### SWAP\_HAND — F Key

Historically used to swap items between main and off-hand.

* **Common Use Case:** Dedicated "Skill" or "Menu" key.
* **Pro Tip:** Enable `cancelAction` to prevent players from accidentally moving items while triggering custom mechanics.

### DROP — Q Key

Used to drop the item currently in hand.

* **Logic:** The extension detects the drop attempt. If `cancelAction` is true, the default drop is cancelled and replaced with custom logic.
* **Custom Drop Count:** Set `dropCount` to `1` (single item), `-1` (full stack), or `N` (N items).

### SNEAK — Shift Key

Fires when the player starts sneaking (not on release).

* **Common Use Case:** Ability activation, toggling walk mode.
* **Pro Tip:** Pair with `cooldown` to prevent spam.

### SPRINT — Ctrl Key

Fires when the player starts sprinting (not on release).

* **Common Use Case:** Sprint-triggered abilities.
* **Pro Tip:** Same as SNEAK — add cooldown for spam prevention.

### CHAT — T Key

Fires when the player opens the chat window.

* **Common Use Case:** Trigger a custom UI or warning before chat opens.

### COMMAND — / Key

Fires when the player types `/`.

* **Common Use Case:** Check permissions or modify command behavior.

### HOTBAR\_SLOT — Number Keys 1-9

Fires when the player selects a specific hotbar slot.

* **Configuration:** Set `hotbarSlot` (0-8) to target a specific slot.
* **Common Use Case:** Equip-specific weapon triggers or slot-based abilities.

## Input Type Quick Reference

| InputType     | Key   | CancelAction | Custom Fields           |
| :------------ | :---- | :----------: | :---------------------- |
| `SWAP_HAND`   | F     |       ✓      | —                       |
| `DROP`        | Q     |       ✓      | `dropCount: Int`        |
| `SNEAK`       | Shift |       ✓      | —                       |
| `SPRINT`      | Ctrl  |       ✓      | —                       |
| `CHAT`        | T     |       ✓      | —                       |
| `COMMAND`     | /     |       ✓      | —                       |
| `HOTBAR_SLOT` | 1-9   |       —      | `hotbarSlot: Int (0-8)` |

## How it Works

The extension uses standard Bukkit events — no packet library required. Each input type maps to a dedicated event handler:

| InputType     | Bukkit Event                   |
| :------------ | :----------------------------- |
| `SWAP_HAND`   | `PlayerSwapHandItemsEvent`     |
| `DROP`        | `PlayerDropItemEvent`          |
| `SNEAK`       | `PlayerToggleSneakEvent`       |
| `SPRINT`      | `PlayerToggleSprintEvent`      |
| `CHAT`        | `AsyncChatEvent`               |
| `COMMAND`     | `PlayerCommandPreprocessEvent` |
| `HOTBAR_SLOT` | `PlayerItemHeldEvent`          |

## Per-Trigger Options

Each keybind definition includes these fields:

| Field          | Type            |   Default   | Description                        |
| :------------- | :-------------- | :---------: | :--------------------------------- |
| `type`         | `InputType`     | `SWAP_HAND` | The input type to listen for       |
| `enabled`      | `Boolean`       |   `false`   | Enable/disable this handler        |
| `cancelAction` | `Boolean`       |   `false`   | Cancel the original game action    |
| `actions`      | `ActionEntry[]` |     `[]`    | Actions to execute                 |
| `delay`        | `Long`          |     `0`     | Delay in ticks before execution    |
| `cooldown`     | `Long`          |     `0`     | Cooldown in ticks between triggers |
| `dropCount`    | `Int`           |     `1`     | For DROP: 1=single, -1=stack, >1=N |
| `hotbarSlot`   | `Int`           |     `0`     | For HOTBAR\_SLOT: slot index (0-8) |
| `criteria`     | `Criteria[]`    |     `[]`    | Conditions for the trigger to fire |