⌨️ Keybind

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

Client Mod (Fabric) • Server Plugin (Paper)

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

Mouse

📜 Commands & Permissions

🏗️ 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.