KibbleCommands Overview
Command alias and automation plugin for Minecraft 1.21 through 26.2 servers and proxies (Paper, Purpur, Folia, Velocity, BungeeCord, Sponge).
commands.yml requires restarting the server on changes, lacks permission checks, has no cooldowns or warmup timers, and cannot run multiple commands per alias. KibbleCommands supports runtime reloading, permissions, cooldowns, warmups, Vault payments, and multi-command sequences while updating client tab-completion via player.updateCommands().
Features
Calls player.updateCommands() when aliases are registered, edited, or reloaded so players receive updated tab-completions without reconnecting.
Run a sequence of commands or select one at random from a configured list.
Delay execution with movement and damage cancel checks, and persist cooldown timestamps in SQLite or MySQL.
Deduct currency from the player's balance before running an alias.
Inspect, reload, and delete aliases in-game using /kc gui.
Runs on Spigot, Paper, and Folia servers as well as Velocity, BungeeCord, and Sponge proxies.
Module Architecture
KibbleCommands is split into platform modules around a shared core:
- kc-common: Configuration parser, SQLite and MySQL storage, cooldown tracking, and alias models.
- kc-bukkit: Bukkit CommandMap registration, Folia scheduling, Vault and PlaceholderAPI hooks, and movement/damage warmup listeners.
- kc-velocity, kc-bungeecord, kc-sponge: Proxy command registration and platform event bridges.
Installation
Setup instructions for Paper, Purpur, Spigot, Folia, Velocity, BungeeCord, and Sponge.
Prerequisites
| Requirement | Supported Versions | Notes |
|---|---|---|
| Java Runtime | Java 21 or newer | Required by Minecraft 1.20.5+ and modern server builds. |
| Minecraft Server | 1.21.x – 26.2.x | Paper, Purpur, Spigot, Bukkit, Folia. |
| Proxy Networks | Velocity 3.3+, BungeeCord, Waterfall | For network-level alias setups. |
| Soft Dependencies | Vault, LuckPerms, PlaceholderAPI, EssentialsX | Hooks enable automatically when present. |
Installation Steps
Paper / Purpur / Spigot / Folia
- Download
KibbleCommands.jar. - Place the JAR file into your server's
plugins/directory. - Optional: Install
Vaultand an economy provider for paid aliases. - Optional: Install
PlaceholderAPIfor placeholder parsing. - Start the server to generate
plugins/KibbleCommands/config.yml.
Velocity Proxy
- Place
KibbleCommands.jarinside the proxy'splugins/directory. - Restart the proxy. Configuration is generated in
plugins/kibblecommands/config.yml.
BungeeCord / Waterfall
- Place
KibbleCommands.jarinside the proxy'splugins/folder. - Restart BungeeCord.
Sponge
- Place
KibbleCommands.jarinside your Sponge server'smods/directory. - Start the server.
Quickstart
Basic alias creation and reload flow.
Step 1: Adding an alias in-game
With kibblecommands.admin or OP, register an alias from chat or console:
/kc add gmc minecraft:gamemode creative {player}
The command registers immediately and syncs to online players' autocomplete lists.
Step 2: Editing config.yml
Open plugins/KibbleCommands/config.yml to configure permissions, warmup timers, cooldowns, or console execution:
aliases:
gmc:
command: "minecraft:gamemode creative {player}"
description: "Switch yourself to Creative mode"
permission: "server.staff.creative"
player-only: true
pass-args: false
execute-as: "console"
spawn:
command: "teleport {player} 0 64 0"
description: "Teleport to spawn area"
player-only: true
warmup: 5 # 5-second warmup countdown
tab-complete:
- "now"
healme:
command: "essentials:heal {player}"
permission: "kibblecommands.alias.healme"
cooldown: 60 # 60 second cooldown
cost: 25.0 # Costs $25.00 via Vault
execute-as: "console"
Step 3: Reloading configuration
Run /kc reload to reload config.yml and re-sync tab completions.
/kc reload
Configuration Reference
Settings and options in config.yml.
Full Configuration Template
# =====================================================
# KibbleCommands Configuration
# by MinedKibbles21
# =====================================================
# Prefix shown before plugin messages in chat
message-prefix: "&8[&6KibbleCommands&8]&r "
# If true, players require kibblecommands.use to run any alias
require-use-permission: false
# If true, sends a notification when an alias is triggered
notify-on-alias-use: false
notify-message: "&7Alias &e{alias}&7 -> &e{target}"
# If true, custom 'send-message' text is sent to players
send-action-messages: true
# Aliases blocked from registration to prevent breaking essential server commands
blocked-aliases:
- plugins
- version
- reload
- stop
- op
- deop
# Database storage engine
database:
type: "sqlite" # 'sqlite' (local file) or 'mysql' (external server)
host: "localhost"
port: 3306
database: "minecraft"
username: "root"
password: ""
# Automated lifecycle triggers
events:
on-join:
commands:
- "effect give {player} speed 10 1"
on-first-join:
commands:
- "give {player} bread 10"
on-death:
commands: []
aliases: {}
Property Breakdown
| Property | Type | Default | Description |
|---|---|---|---|
message-prefix |
String | &8[&6KibbleCommands&8]&r |
Prefix attached to plugin feedback and error messages. Supports color codes (&6, &c). |
require-use-permission |
Boolean | false |
When true, players must have kibblecommands.use to run any alias. |
notify-on-alias-use |
Boolean | false |
Sends a notification to the player when an alias executes. |
notify-message |
String | &7Alias &e{alias}&7 -> &e{target} |
Message format used when notify-on-alias-use is enabled. |
send-action-messages |
Boolean | true |
Controls whether custom send-message text is sent to players. |
blocked-aliases |
List<String> | [plugins, reload, stop, ...] |
Command names protected from registration to prevent overriding core server commands. |
Database Storage
Cooldown persistence using SQLite or MySQL.
How Cooldown Storage Works
Cooldown timestamps are stored in a database to persist across server restarts and prevent players from resetting timers by disconnecting. Database queries run asynchronously.
SQLite
SQLite is enabled by default and stores data in plugins/KibbleCommands/cooldowns.db.
database:
type: "sqlite"
MySQL
For multi-server networks sharing cooldowns across proxies or sub-servers, configure MySQL:
database:
type: "mysql"
host: "127.0.0.1"
port: 3306
database: "network_core"
username: "minecraft_user"
password: "SuperSecurePassword123!"
Database Schema
The plugin creates the table automatically on first launch:
CREATE TABLE IF NOT EXISTS kc_cooldowns (
uuid VARCHAR(36) NOT NULL,
alias VARCHAR(64) NOT NULL,
expiry BIGINT NOT NULL,
PRIMARY KEY (uuid, alias)
);
Event Triggers
Running console commands on player join, first join, and death events.
Configuring Event Hooks
The events section in config.yml allows running console commands on specific player lifecycle events:
events:
# Triggered every time any player joins the server
on-join:
commands:
- "effect give {player} speed 10 1"
- "title {player} title {\"text\":\"Welcome Back!\",\"color\":\"gold\"}"
# Triggered ONLY when a brand new player joins for the first time
on-first-join:
commands:
- "give {player} bread 16"
- "give {player} stone_sword 1"
- "broadcast &6Welcome &e{player} &6to the server for the first time!"
# Triggered when a player dies
on-death:
commands:
- "tell {player} &cYou died! Return with /back"
Alias Mechanics
Alias structure, execution modes, sender contexts, and multi-command lists.
Alias Definition Schema
aliases:
<alias-name>:
# Single command target:
command: "target command string"
# OR Multiple command targets:
commands:
- "first target command"
- "second target command"
mode: "sequence" # 'sequence' (runs all) or 'random' (picks one)
description: "Short description shown in /kc info and /kc list"
permission: "custom.permission.node"
permission-message: "&cYou lack permission! Cooldown left: {cooldown_remaining}s"
execute-as: "sender" # 'sender' (player's perms) or 'console' (elevated)
player-only: false # Prevent console from running
console-only: false # Prevent players from running
pass-args: true # Forward extra typed arguments to target command
cooldown: 0 # Cooldown in seconds
warmup: 0 # Delay in seconds (cancelled on damage/movement)
cost: 0.0 # Vault currency charge
send-message: "&aMessage sent to player"
tab-complete: # Custom autocompletions
- "suboption1"
- "<player>" # Expands to online player names
Execution Context: sender vs console
| Mode | Privilege Level | Behavior |
|---|---|---|
execute-as: "sender" |
Player's permissions | Dispatches the command as the executing player. If the target command requires OP or a permission node, the player must have it. |
execute-as: "console" |
Console permissions | Dispatches the command from the server console. {player} is replaced with the executing player's name. |
Execution Modes: sequence vs random
sequence(default): Runs all commands incommandsin order.random: Picks one command at random fromcommandseach time the alias is run. Useful for reward commands or drop tables.
Tokens and Placeholders
Built-in variables, argument indexing, and PlaceholderAPI support.
Built-In Variables
| Token | Resolved Value | Example |
|---|---|---|
{player} or %player% |
Name of player running alias (or CONSOLE) |
Steve |
{sender} |
Name of the command sender | Steve or CONSOLE |
{uuid} |
UUID of player (blank for console) | 45a1e2f3-... |
{world} |
Name of the player's current world | world_nether |
{args} or %args% |
All trailing arguments joined as a single string | /alias apple pie → apple pie |
{arg:1} |
First argument passed after alias | /msg Steve hello → Steve |
{arg:2} |
Second argument passed after alias | /msg Steve hello → hello |
{cooldown_remaining} |
Remaining cooldown seconds | 24 |
{warmup_remaining} |
Remaining warmup countdown seconds | 3 |
PlaceholderAPI Integration
When PlaceholderAPI is installed, you can use any PAPI placeholder inside target commands, send-message, and permission-message:
aliases:
stats:
description: "View your player stats"
send-message: "&6=== &e{player}'s Stats &6===\n&7Rank: &a%luckperms_primary_group_name%\n&7Balance: &a$%vault_eco_balance%\n&7Ping: &e%player_ping%ms"
Warmups and Cooldowns
Execution delays, cancellation triggers, and cooldown bypasses.
Warmup Delays and Cancellation
Setting warmup: <seconds> delays execution. The warmup cancels if the player moves across block coordinates, takes damage, or disconnects.
aliases:
spawn:
command: "teleport {player} 0 64 0"
warmup: 5 # 5 second delay
Cooldown Bypass Permissions
Bypass nodes allow specific groups or players to skip cooldown timers:
kibblecommands.cooldown.bypass: Bypasses cooldowns on all aliases.kibblecommands.cooldown.bypass.<alias>: Bypasses cooldown on a specific alias.
Vault Economy
Charging currency balance per command execution.
Configuring Paid Aliases
With Vault and an economy plugin installed, add cost: <amount> to charge players when they run an alias:
aliases:
fixhand:
command: "repair hand"
description: "Repair your held item for $250"
cost: 250.0
cooldown: 300
player-only: true
Command Reference
Commands and arguments for /kc.
| Command | Usage | Description | Permission |
|---|---|---|---|
/kc help |
/kc help |
Prints command help in chat. | kibblecommands.admin |
/kc gui |
/kc gui |
Opens the admin chest GUI. | kibblecommands.gui |
/kc list |
/kc list |
Lists all registered aliases. | kibblecommands.admin |
/kc info <alias> |
/kc info <alias> |
Displays details for a specific alias. | kibblecommands.admin |
/kc add <alias> <cmd> |
/kc add gmc minecraft:gamemode creative {player} |
Registers a new alias and appends it to config.yml. |
kibblecommands.admin |
/kc edit <alias> <cmd> |
/kc edit spawn tp {player} 100 70 100 |
Updates the target command for an existing alias. | kibblecommands.admin |
/kc remove <alias> |
/kc remove gmc |
Unregisters and deletes an alias. | kibblecommands.admin |
/kc reload |
/kc reload |
Reloads config.yml, clears cooldown cache, and re-syncs player autocompletions. |
kibblecommands.reload |
/kc history <player> |
/kc history Notch |
Reads execution log entries from logs/use.log for a player. |
kibblecommands.admin |
Permissions
Permission nodes and default access levels.
| Permission Node | Default | Description |
|---|---|---|
kibblecommands.admin |
OP only | Access to all /kc administrative subcommands. |
kibblecommands.gui |
OP only | Access to open and use /kc gui. |
kibblecommands.reload |
OP only | Allows executing /kc reload. |
kibblecommands.use |
True | Required when require-use-permission is set to true. |
kibblecommands.cooldown.bypass |
OP only | Bypasses cooldown timers on all aliases. |
kibblecommands.cooldown.bypass.<alias> |
OP only | Bypasses cooldown on a specific alias. |
Admin GUI
In-game alias management menu via /kc gui.
Opening the GUI
Run /kc gui in-game. The menu uses three inventory views:
Listing View (54 slots)
- Slots 0–44: Active aliases rendered as nametags. Displays targets, execution context, cooldown, and cost. Clicking an item opens its details view.
- Slot 45 (Compass): Prints command help in chat.
- Slot 46 (Paper): Prints instructions for
/kc add. - Slot 48 (Nether Star): Reloads configuration and resets cooldown caches.
- Slot 49 (Clock): Refreshes the inventory listing.
- Slot 53 (Barrier): Closes the inventory.
Details View (27 slots)
Displays configured parameters for the selected alias and contains a button to open the deletion prompt.
Confirmation View (27 slots)
Provides green and red wool options to confirm or cancel alias deletion.
Alias Generator
Interactive tool to build and validate alias YAML configurations.
Generated YAML (config.yml)
GUI Simulator
Interactive preview of the in-game /kc gui interface.
Developer API
Maven dependency configuration, Java API methods, and source compilation.
Maven Dependency Setup
<dependency>
<groupId>com.minedkibbles21</groupId>
<artifactId>kibblecommands-bukkit</artifactId>
<version>2.1.0</version>
<scope>provided</scope>
</dependency>
Accessing the API in Java
import com.minedkibbles21.kibblecommands.KibbleCommands;
import com.minedkibbles21.kibblecommands.common.AliasConfig;
import com.minedkibbles21.kibblecommands.common.Cooldowns;
import org.bukkit.entity.Player;
public class MyPlugin {
public void checkAliasInfo(Player player, String aliasName) {
KibbleCommands kc = KibbleCommands.getPlugin(KibbleCommands.class);
// Fetch alias definition
AliasConfig cfg = kc.getDefinitions().get(aliasName.toLowerCase());
if (cfg != null) {
String target = cfg.getTarget();
double cost = cfg.getCost();
int cooldown = cfg.getCooldown();
player.sendMessage("Alias /" + aliasName + " targets: " + target);
}
// Query remaining player cooldown
Cooldowns cooldowns = kc.getCooldowns();
long remainingSeconds = cooldowns.getRemaining(player.getUniqueId(), aliasName);
if (remainingSeconds > 0) {
player.sendMessage("Cooldown active: " + remainingSeconds + "s remaining.");
}
}
}
Building from Source
- Clone the repository:
git clone https://github.com/minedkibbles21/KibbleCommands.git cd KibbleCommands/kc - Compile with Maven using Java 21:
mvn clean package - The compiled plugin JAR is written to
target/KibbleCommands-2.1.0.jar.
Configuration Examples
Common alias configurations for server setups.
1. Hub or spawn teleport with warmup
aliases:
hub:
command: "teleport {player} 0 100 0"
description: "Teleport to server hub"
player-only: true
warmup: 3
2. Paid feed shortcut with cooldown
aliases:
feed:
command: "feed {player}"
cost: 10.0
cooldown: 60
execute-as: "console"
send-message: "&aYour hunger has been restored for $10.00!"
3. Daily reward roller
aliases:
dailyroll:
description: "Spin for your daily mystery reward"
mode: "random"
cooldown: 86400 # 24 hours
execute-as: "console"
commands:
- "give {player} diamond 3"
- "give {player} emerald 5"
- "eco give {player} 500"
- "crate key give {player} mythical 1"
4. Staff warning command
aliases:
warn:
permission: "staff.warn"
execute-as: "console"
commands:
- "title {arg:1} title {\"text\":\"WARNING\",\"color\":\"red\",\"bold\":true}"
- "title {arg:1} subtitle {\"text\":\"{args}\",\"color\":\"yellow\"}"
- "tell {arg:1} &c[Staff Warning] &eYou were warned by &f{sender}&e: &c{args}"
5. Discord link message
aliases:
discord:
description: "Get official Discord link"
send-message: "&8&m----------------------------------------\n &9&lDiscord: &bhttps://discord.gg/your-server\n&8&m----------------------------------------"
Troubleshooting & FAQ
Common configuration and compatibility questions.
Frequently Asked Questions
Why does an alias output "command already managed by [Plugin]"?
KibbleCommands inspects the server's CommandMap during registration. If another plugin already registered that exact command name, KibbleCommands avoids overriding it. Use a different alias name or disable the conflicting plugin's command.
Why does registration fail with "name blocked by server config"?
The name is listed under blocked-aliases in config.yml (such as stop, reload, op, plugins). Remove the name from that list if you intend to allow it.
Why are cooldowns resetting across restarts?
Check your database settings. If using SQLite, confirm the server process has write access to plugins/KibbleCommands/. If using MySQL, verify connection credentials and database user privileges in config.yml.
Why is player balance not deducting?
Ensure Vault and a compatible economy plugin (e.g. EssentialsX) are installed and enabled. Look for the Vault hook message in your server startup log.
Why is autocomplete not updating for online players?
Run /kc reload. The plugin automatically calls player.updateCommands() to refresh client command packets.