⌨️ Keybind

Bind keys to server-side commands. Press a key, the server runs a command.

Client Mod (Fabric) • Server Plugin (Paper)

Component	Environment	Platform
KeybindMod	Client Side	Fabric (MC 1.21.x & 26.x)
KeybindPlugin	Server Side	Paper 1.18.2+

Note: Both the Server Plugin and the Client Mod must be installed for the mod to function. On servers without the plugin, no keybinds will be registered or available.

---

✨ Features

• 🔗 Server-Driven: Actions are defined entirely on the server and synced to the client on join.
• 📁 Per-Server Storage: Key assignments are saved per server IP in .minecraft/config/keybind-servers/ and never overwritten on rejoin.
• 🛠️ Dynamic Registration: New server actions appear in your Settings → Controls menu without restarting the game.
• 🏷️ Custom Display Names: Server owners set friendly names (e.g., "Teleport to Spawn" instead of spawn).
• ⏱️ Dual Cooldowns: Both a global cooldown (between any actions) and per-action cooldowns prevent spam.
• 🔐 Permission Support: Each action supports an optional extra permission node on top of keybind.use.
• 📡 Plugin Messaging: Uses keybind:main / keybind:sync plugin message channels. Falls back to /kbind <action> if the packet channel is unavailable.
• 🧹 Stale Action Cleanup: Obsolete actions from previous sessions are automatically removed from the Controls menu and saved config.
• 🌍 Universal Support: Compatible with Minecraft 1.21.x and 26.* using dynamic constructor discovery.

---

🚀 How It Works

1. Sync: 1 second after a player joins, the plugin sends all configured actions (name, display name, default key) over the keybind:sync channel.
2. Registration: The mod registers each action as a native Minecraft keybind under the Keybind category in Settings → Controls.
3. Trigger: When a key is pressed (and no screen is open), the mod sends the action name over the keybind:main channel.
4. Execution: The plugin validates the action name (alphanumeric + underscores only), checks permissions and cooldowns, then runs the command.

---

🛠️ Installation

Server Side

1. Place KeybindPlugin.jar into your plugins/ folder.
2. Restart the server — plugins/Keybind/config.yml is generated automatically.
3. Edit config.yml to define your actions, then run /kbind reload.

Client Side

1. Place KeybindMod.jar into your .minecraft/mods/ folder.
2. Requires Fabric Loader 0.18.4+ and Fabric API.
3. Launch the game and connect to any server running the plugin.

The mod works on any server. On servers without the plugin, no keybinds are registered.

---

⚙️ Configuration

plugins/Keybind/config.yml

# Global cooldown between any keybind actions (milliseconds)
global-cooldown: 500

actions:
  spawn:
    command: "spawn"              # Command to run (without /)
    display-name: "Spawn"        # Label shown in Controls menu
    default-key: "LEFT_BRACKET"  # Suggested key for first-time players
    permission: ""               # Optional extra permission node (leave empty for none)
    cooldown: 1000               # Per-action cooldown (ms); defaults to global-cooldown
    console: false               # true = run as console with {player} replaced by player name

  home:
    command: "home"
    display-name: "Home"
    default-key: "RIGHT_BRACKET"
    permission: ""
    cooldown: 1000
    console: false

Notes:

• Action names must be alphanumeric + underscores only (e.g. my_action).
• console: true runs the command as the console sender. Use {player} as a placeholder for the player's name (e.g. command: "tp {player} spawn").
• default-key is only applied the first time a player connects. Their saved binding is used on subsequent joins.

---

⌨️ Supported Keys

Keyboard

Category	Values
Letters	A–Z
Numbers	0–9
Function	F1–F25
Arrows	UP, DOWN, LEFT, RIGHT
Navigation	PAGE_UP, PAGE_DOWN, HOME, END, INSERT, DELETE
Special	SPACE, ENTER, TAB, BACKSPACE, ESCAPE, PAUSE
Lock keys	CAPS_LOCK, SCROLL_LOCK, NUM_LOCK
Other	PRINT_SCREEN, MENU
Modifiers	LEFT_SHIFT, LEFT_CONTROL (or LEFT_CTRL), LEFT_ALT, LEFT_SUPER, RIGHT_SHIFT, RIGHT_CONTROL (or RIGHT_CTRL), RIGHT_ALT, RIGHT_SUPER
Numpad	KP_0–KP_9, KP_ADD, KP_SUBTRACT, KP_MULTIPLY, KP_DIVIDE, KP_DECIMAL, KP_ENTER, KP_EQUAL
Symbols	LEFT_BRACKET, RIGHT_BRACKET, BACKSLASH, SEMICOLON, APOSTROPHE, COMMA, PERIOD, SLASH, GRAVE_ACCENT, MINUS, EQUAL — or the character directly: [, ], \, ;, ', ,, ., /, `, -, =
World keys	WORLD_1, WORLD_2 (locale-specific keys on some keyboards)

Mouse

Value	Aliases	Button
MOUSE_LEFT	MOUSE_1	Left click
MOUSE_RIGHT	MOUSE_2	Right click
MOUSE_MIDDLE	MOUSE_3	Middle click
MOUSE_4–MOUSE_8	—	Side/extra buttons

---

📜 Commands & Permissions

Command	Description	Permission
/kbind <action>	Manually trigger an action	keybind.use
/kbind list	List all configured action names	(any)
/kbind reload	Reload config and re-sync all online players	keybind.admin

Permission	Description	Default
keybind.use	Required to trigger any action	true (everyone)
keybind.admin	Access to /kbind reload	op
keybind.bypass.cooldown	Ignore all cooldowns	op

---

🏗️ Building from Source

./gradlew clean build

Project layout:

• keybind-mod-common/ shared loader-agnostic code, config/storage models, packet format, sync planning, and client session state
• keybind-mod-fabric/ Fabric-specific entrypoints, payload glue, mixins, and resources
• keybind-plugin/ Paper plugin

Output jars:

• keybind-plugin/build/libs/KeybindPlugin-1.0.0.jar
• keybind-mod-fabric/build/libs/KeybindMod-1.0.0.jar

Requires Java 17+ for the plugin, Java 21+ for the mod.

---

Security

• Action names are validated server-side against ^[a-zA-Z0-9_]+$ — arbitrary input is rejected.
• Packet length is capped at 256 bytes.
• All command execution happens on the main server thread.
• Players without keybind.use cannot trigger any action, even via direct /kbind command.