Commands.yml

commands.yml is a configuration file that houses custom defined aliases and command block overrides for your CraftBukkit server.

The command block override system provides a quick and easy way to force the server to use the commands provided by Mojang (as opposed to the ones built into Bukkit) for command blocks specifically, leaving all other commands untouched. While the aliases system, essentially, gives power user server admins the ability to define custom commands and force specific versions of a command to be used for the default commands.

Note: When editing this file, be careful to only use spaces and NOT tabs (as is the case with all .yml or YAML files).

Out of the box, Bukkit provides a useful fallback system for commands that has the following priorities:

1. Aliases - Aliases have the highest priority, overriding all commands.
2. Plugin Commands - If a matching alias is not found, a matching plugin command is used.
3. Bukkit Commands - If a matching plugin command is not found, the built in commands provided by Bukkit are used.
4. Mojang Commands - If a matching Bukkit command is not found, the built in commands provided by Mojang are used. This is the last fallback.

On top of this, we provide untouchable ultimate fallbacks for every command which can be used by users or the Aliases system to use specific versions of a command:

Type	Fallback	Example
Plugin Commands	pluginname:command	/scrapbukkit:time
Bukkit Commands	bukkit:command	/bukkit:time
Mojang Commands	minecraft:command	/minecraft:time

Of course, for each fallback we also provide permissions to allow you to control access to each command (except for Plugin Commands which depend on the plugin's handling of permissions):

Type	Permission	Example
Plugin Commands	Plugins provide their own system that you'll have to educate yourself on	N/A
Bukkit Commands	bukkit.command.* (List of Bukkit permissions)	bukkit.command.give
Mojang Commands	minecraft.command.* (List of Mojang permissions)	minecraft.command.give

Default commands.yml

command-block-overrides: []
aliases:
    icanhasbukkit:
    - "version $1-"

command-block-overrides

This section of the commands.yml controls what is known as the command block overrides feature. Since Bukkit has historically provided its own version of some Minecraft commands, we've added the ability to force the server to use the Mojang provided version for command blocks specifically. Commands used outside of command blocks will use the Bukkit (or plugin) version as usual.

Note: Since Bukkit has no control over the Mojang version of a command, we cannot guarantee that they will work as expected.

If the custom map you're running uses the /summon and /give commands, you probably want to enable command block overrides for them. To do this, you simply add them to the command-block-overrides list and your commands.yml would look something like this:

command-block-overrides:
    - "summon"
    - "give"

If, on the other hand, the custom map uses most of the Minecraft commands, you can also easily enable command block overrides for all valid commands by using a *, like so:

command-block-overrides:
    - "*"

aliases

This section of the commands.yml allows you to define custom aliases for commands on your server. At its core, an alias allows you to create custom commands that can perform multiple functions at once. This is a powerful tool that allows you to define easier to remember commands for your server staff.

Alongside letting you redefine commands, the Aliases System provides extra useful features that allow you to create some powerful custom commands for you server:

Modifier	Description	Example
$<argument number>	References a specific token	say $1 $2 $3
$<argument number>-	References a range of tokens starting from the argument number specified	say $1-
$$<argument number>	References a specific token that is required to be populated for the alias to function	say $$1
$$<argument number>-	References a range of tokens starting from the argument number specified. The starting token is required to be populated for the alias to function.	say $$1-
\	Escapes a special character	say \$100

Alias Examples

Scenario	Description	Command Usage	Example Configuration
Add an alternative way to run the /version command	In this example we're registering an alias called "icanhasbukkit" which will execute the version command when used.	/icanhasbukkit	aliases: icanhasbukkit: - "version"
Removing a command	In this example we're registering an alias called 'summon' that is mapped to nothing. By doing this, we are telling the server to unregister the command and, as a result, prevent it from existing/functioning. Note: If you are looking to prevent people from using a command, you should remove their permission to use the command instead of removing it with an alias.	N/A	aliases: summon: - []
Rename the /version command	In this example we're registering an alias called "icanhasversion" which will execute the version command when used and creating an alias called "version" that is mapped to nothing to remove it. Note: If you are looking to prevent people from using a command, you should remove their permission to use the command instead of removing it with an alias.	/icanhasversion	aliases: icanhasversion: - "bukkit:version" version: - []
Requiring a parameter	In this example we're creating an alias called 'givedirt' that requires providing an argument (in this case a player's name) before the alias will successfully run.	/givedirt <player>	aliases: givedirt: - "give $$1 minecraft:dirt"
Running multiple commands	In this example we're creating an alias called 'givedirtmsg' which will execute two commands that require an argument before the alias will successfully run.	/givedirtmsg <player>	aliases: givedirtmsg: - "give $$1 minecraft:dirt" - "say Gave dirt to $$1"
Using a command supplied by a plugin	In this example we're overriding the built in /time command to use the version supplied by the plugin ScrapBukkit instead.	/time <set|add> <value>	aliases: time: - "scrapbukkit:time $1-"
Using a command supplied by Mojang	In this example we're overriding the built in /time command to use the version supplied by Mojang instead.	/time <set|add> <value>	aliases: time: - "minecraft:time $1-"
Using a command supplied by Bukkit	In this example we're overriding the built in /time command to use the version supplied by Bukkit instead.	/time <set|add> <value>	aliases: time: - "bukkit:time $1-"
Accepting all parameters	In this example we're creating an alias called 'broadcast' that will execute the 'say' command and accept any arguments passed to it.	/broadcast <message>	aliases: broadcast: - "say $$1-"
Requiring the first parameter while keeping the second optional	In this example we're overriding the built in 'ban' command. This alias will require the first argument (which in this case is a player's name) while providing support for an optional ban reason. When the alias is used, the player will be banned and a /say message will be broadcasted, informing the people on the server that someone has been banned.	/ban <player> [optional reason]	aliases: ban: - "bukkit:ban $$1 $2-" - "say Banned $$1. Reason: $2-"
Using $ signs in a command	In this example we're creating an alias called 'dollar' that broadcasts the message "That will be $200, thanks!" to the server. Since the $ character is used to denote parameters, we need to escape the character with a \ (backslash) when creating an alias.	/dollar	aliases: dollar: - "say That will be \$200, thanks!"