KeyCaster

Overview

KeyCaster listens to Minecraft's server-side events to detect when players press specific
keys or key combinations. When a configured combination is triggered, it runs any list of
commands (messages, player commands, or console commands) with full cooldown, permission,
and per-world support.

Everything is configured through config.yml with no coding required.

Features

• Detect 25+ keys and key combinations with no client mod
• Run any number of commands per combo: messages, player commands, or console commands
• Per-combo cooldowns with a configurable cooldown message
• Per-combo permissions
• Per-combo world filter
• Cancel the triggering event (e.g. suppress item drops on Q-press combos)
• Color code support (&a, &c, &e, etc.) in messages
• Placeholders: {player}, {world}, {x}, {y}, {z}
• Hot-reload via /keycaster reload
• Debug mode for testing

Detectable Keys

Modifier Keys
These are "held" states used to build combinations. They also fire as triggers on their own.

Key	Config name	Notes
Shift	SNEAK	Fires on press
Ctrl / Sprint	SPRINT	See limitations

Action Keys

Key	Config name	Notes
Q	DROP	Drop single item
Ctrl+Q	CTRL_DROP	Drop whole stack; detected by amount > 1
F	SWAP_HANDS	Swap main/off hand
Right click	RIGHT_CLICK	Right click on block or in air; see limitations
Scroll up	SCROLL_UP	See limitations
Scroll down	SCROLL_DOWN	See limitations
1–9 (hotbar)	HOTBAR_1 … HOTBAR_9	See limitations
W	MOVE_FORWARD	Approximate; see limitations
S	MOVE_BACKWARD	Approximate; see limitations
A	MOVE_LEFT	Approximate; see limitations
D	MOVE_RIGHT	Approximate; see limitations
Space	JUMP	Detected on ground-to-air transition

Configuration

config.yml

Keys field

List any combination of key names. Keys that are modifiers ( SNEAK, SPRINT) are
treated as "held" requirements. All other keys are triggers.

A combo fires when:

• The trigger key is pressed
• All listed modifier keys are currently held

Command prefixes

Prefix	Behavior
[MESSAGE] ...	Send a chat message to the player
[PLAYER] ...	Run a command as the player
[CONSOLE] ...	Run a command from the console
(no prefix)	Same as [CONSOLE]

Placeholders

Available in all command types:

Placeholder	Value
{player}	Player's name
{world}	World name
{x}	Block X coordinate
{y}	Block Y coordinate
{z}	Block Z coordinate

Color codes: use & followed by a standard Minecraft color/format code (e.g. &a, &c, &l).

All config options per combo

Option	Type	Default	Description
keys	list	required	Key names to match
commands	list	required	Commands to run
cooldown	int (ms)	500	Per-player cooldown in milliseconds
cooldown-message	string	(none)	Message shown while on cooldown. Supports {time} in seconds
permission	string	(none)	Permission node required to trigger the combo
cancel	boolean	false (true for DROP/CTRL_DROP)	Whether to cancel the underlying Minecraft event
worlds	list	(all worlds)	World names where the combo is active

Commands & Permissions

Command	Permission	Description
/keycaster	keycaster.admin	Show plugin version and help
/keycaster reload	keycaster.reload	Reload config.yml without restarting

Both permissions default to OP.

Limitations

These are hard limits imposed by how Minecraft's server-side protocol works.
They cannot be worked around without a client-side mod or a packet-level library
such as ProtocolLib or PacketEvents.

Left click / Attack
Left-click cannot be reliably detected on Paper 1.21.4+. The animation event that
normally covers this does not fire consistently in the current Paper build.
ATTACK and LEFT_CLICK are not supported.

Right click in air with an empty hand
When a player right-clicks in the air while holding nothing, the client does not
send an interaction packet to the server. RIGHT_CLICK will only fire when
the player is holding an item, or when right-clicking a block.

SPRINT vs double-tap W
The server receives the same sprint-start packet whether the player pressed Ctrl
or double-tapped W. SPRINT fires for both. It cannot be used to detect
only Ctrl. Use CTRL_DROP (Ctrl+Q) if you need a genuine Ctrl detection.

WASD is approximate
WASD is inferred from the player's movement vector relative to their facing
direction, not from actual key-press packets. This means:

• It fires when the player moves, not when the key is pressed
• It has a 150 ms debounce to avoid flooding
• Diagonal movement only fires the dominant axis
• It does not fire while the player stands still (e.g. pushing against a wall)

Scroll vs adjacent hotbar key
A slot change of exactly ±1 (or wrapping 0↔8) is indistinguishable from scrolling.
If a player presses hotbar key 2 while already on slot 1, the plugin will detect it
as SCROLL_DOWN instead of HOTBAR_2. Pressing any other non-adjacent
slot number is detected correctly as the hotbar key.

Same-slot hotbar key
Pressing the hotbar number key for the slot the player already has selected sends
no packet. HOTBAR_N will not fire in that case. This cannot be fixed
server-side.

Jump while swimming or in a vehicle
Jump is detected by a ground-to-air transition with upward velocity. It does not
fire while the player is swimming, flying, or in a vehicle.

Requirements

• Paper 1.21.4 or newer (Spigot is not supported)
• Java 21 or newer

[HR][/HR]

Installation

1. Drop KeyCaster-1.0.0.jar into your server's plugins/ folder
2. Start or restart the server
3. Edit plugins/KeyCaster/config.yml
4. Run /keycaster reload to apply changes without restarting