KibbleCommands Overview

Command alias and automation plugin for Minecraft 1.21 through 26.2 servers and proxies (Paper, Purpur, Folia, Velocity, BungeeCord, Sponge).

Paper 1.21 - 26.2 Folia Velocity 3.3+ BungeeCord / Waterfall SpongeAPI 10+
Differences from vanilla commands.yml
Vanilla 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

Autocomplete synchronization

Calls player.updateCommands() when aliases are registered, edited, or reloaded so players receive updated tab-completions without reconnecting.

Multi-command execution

Run a sequence of commands or select one at random from a configured list.

Warmups and cooldowns

Delay execution with movement and damage cancel checks, and persist cooldown timestamps in SQLite or MySQL.

Vault economy support

Deduct currency from the player's balance before running an alias.

Admin GUI menu

Inspect, reload, and delete aliases in-game using /kc gui.

Proxy support

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

  1. Download KibbleCommands.jar.
  2. Place the JAR file into your server's plugins/ directory.
  3. Optional: Install Vault and an economy provider for paid aliases.
  4. Optional: Install PlaceholderAPI for placeholder parsing.
  5. Start the server to generate plugins/KibbleCommands/config.yml.
Folia support
KibbleCommands runs cooldown checks and database operations asynchronously off the region threads.

Velocity Proxy

  1. Place KibbleCommands.jar inside the proxy's plugins/ directory.
  2. Restart the proxy. Configuration is generated in plugins/kibblecommands/config.yml.

BungeeCord / Waterfall

  1. Place KibbleCommands.jar inside the proxy's plugins/ folder.
  2. Restart BungeeCord.

Sponge

  1. Place KibbleCommands.jar inside your Sponge server's mods/ directory.
  2. 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:

Minecraft Chat / 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:

plugins/KibbleCommands/config.yml
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.

In-Game / Console
/kc reload

Configuration Reference

Settings and options in config.yml.

Full Configuration Template

config.yml
# =====================================================
#           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.

config.yml (SQLite)
database:
  type: "sqlite"

MySQL

For multi-server networks sharing cooldowns across proxies or sub-servers, configure MySQL:

config.yml (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:

SQL Schema
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:

config.yml
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

Schema Format
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 in commands in order.
  • random: Picks one command at random from commands each 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 pieapple pie
{arg:1} First argument passed after alias /msg Steve helloSteve
{arg:2} Second argument passed after alias /msg Steve hellohello
{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:

PlaceholderAPI Example in config.yml
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.

Spawn Teleport with Warmup
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:

config.yml
aliases:
  fixhand:
    command: "repair hand"
    description: "Repair your held item for $250"
    cost: 250.0
    cooldown: 300
    player-only: true
Balance check
Player balance is checked before running target commands. If the player cannot afford the cost, execution stops and an error message is sent.

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.

Command players type (e.g. /healme)

Generated YAML (config.yml)

YAML Output

GUI Simulator

Interactive preview of the in-game /kc gui interface.

KibbleCommands > Active Aliases 54 Slots
Click any alias nametag to inspect details or test deletion safeguards.

Developer API

Maven dependency configuration, Java API methods, and source compilation.

Maven Dependency Setup

pom.xml
<dependency>
    <groupId>com.minedkibbles21</groupId>
    <artifactId>kibblecommands-bukkit</artifactId>
    <version>2.1.0</version>
    <scope>provided</scope>
</dependency>

Accessing the API in Java

Java API Hook
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

  1. Clone the repository:
    git clone https://github.com/minedkibbles21/KibbleCommands.git
    cd KibbleCommands/kc
  2. Compile with Maven using Java 21:
    mvn clean package
  3. 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

config.yml
aliases:
  hub:
    command: "teleport {player} 0 100 0"
    description: "Teleport to server hub"
    player-only: true
    warmup: 3

2. Paid feed shortcut with cooldown

config.yml
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

config.yml
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

config.yml
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

config.yml
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.

ESC