Welcome to the BukkitWiki!

This Wiki is home to Bukkit's documentation and regulations surrounding the Bukkit Project and it's services. Want to help out? We would love to have you! Signup to get started!

Commands.yml

From BukkitWiki
Jump to: navigation, search

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.

Lightbulb.png 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.


Lightbulb.png 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.



Lightbulb.png 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.



Lightbulb.png 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!"