The nice thing about the Bukkit API is that it has the basic features already built into its framework. As programmers, we need not go out of our way to implement these basic features into plugins. In this chapter, we will discuss one of these features, namely the in-game commands that can be executed by a player. These are similar to the commands that you are already familiar with, such as /reload, /gamemode, or /give. We will create a plugin that will enchant an item. By the end of this chapter, once the plugin is complete, you will be able to type /enchant to add your favorite enchantments to the item in your hand.
Commands are one of the easiest ways for players to communicate with a plugin. They also allow players to trigger the execution of a plugin's code. For these reasons, most plugins will have some sort of command. The Bukkit development team realized this and provided us with a simple way to register commands. Registering commands through Bukkit ensures that a plugin will know when a player types a command. It also prevents a plugin from having conflicts with another plugin's commands. The following are the three steps that we will cover to add a command to a plugin:
- Informing Bukkit that a plugin will be using a command
- Programming what a plugin will do when someone types a command
- Assigning newly written code to a specific command
Create a new Bukkit plugin as you did in Chapter 3, Creating Your First Bukkit Plugin, but name it Enchanter. Alternatively, you can create a copy of your existing project and modify the name, package, and so on in order to create a new plugin. This will eliminate the need to add the required libraries and configure the build script. A project can be copied by performing the following steps:
- Right-click on the project that you wish to copy and select Copy… from the menu.
- Set the project name. The project location should remain unchanged.
- Open
build.xml, as discussed in Chapter 4, Testing on the Spigot Server, and change the project's name to match what was set in step 2. - Update the package in your new project so that it is unique by right-clicking on the package and selecting Rename… in the Refactor menu item.
- Rename the main class, if necessary. You can also remove the methods or classes that you know will not be reused.
- Finally, modify the
plugin.ymlfile with the new plugin information, including name, main, version, and description.
Next, we will inform Bukkit that we will use a command by modifying the plugin.yml file of the plugin. As mentioned in Chapter 2, Learning the Bukkit API, Spigot reads the YAML file in order to find out necessary information about the plugin. This information includes all the commands that your plugin will handle. Each command can have a description, a proper usage message, and aliases, which is similar to how rl is an alias for reload. The command that we will use for the plugin will be enchant. It is typical to use lowercase letters for commands so that players do not have to worry about capitalization when typing the in-game command. The following code is a sample of how plugin.yml will appear after the enchant command is added:
name: Enchanter
version: 0.1
main: com.codisimus.enchanter.Enchanter
description: Used to quickly put enchantments on an item
commands:
enchant:
aliases: [e]
description: Adds enchantments to the item in your hand
usage: Hold the item you wish to enchant and type /enchantNote how the lines are indented. This indentation must be spaces and not tabs. NetBeans helps us automatically indent the necessary lines as you type them. In addition to this, NetBeans will automatically use spaces even if you use the Tab key. Indentation is very important in YAML files as this determines the hierarchy of keys. The enchant command is indented under commands to indicate that it is a command for the plugin. The aliases, description, and usage commands are indented under enchant to indicate that they belong to the enchant command.
The usage message will be displayed in case an error occurs or a player uses a command incorrectly. The description message can be viewed by issuing the help command for the plugin, that is, /help Enchanter.
For aliases, we have e as a value. This means that we can type /e if we feel that /enchant is too long to type. You may have more aliases, but they must be put in a YAML list format. Lists in a YAML file can be created in two different ways. The first format involves separating each item by a comma and a space and enclosing the entire list in square brackets, as shown in the following piece of code:
aliases: [e, addenchants, powerup]
The second format involves placing each item on a new line, which starts with a hyphen and a space, as shown in the following piece of code:
aliases: - e - addenchant - powerup
The preferred method is usually determined by the length of the list. The second format is easier to read when lists are long. However, be careful not to have extra or missing spaces before the hyphen, as it will cause problems when a program tries to read the list. In general, ensure that your lists line up. For more information about the YAML language, visit http://www.yaml.org/spec/1.2/spec.html.
Multiple commands can be easily added to a plugin. The following code is an example of plugin.yml with several commands:
name: Enchanter
version: 0.1
main: com.codisimus.enchanter.Enchanter
description: Used to quickly put enchantments on an item
commands:
enchant:
aliases: [e, addenchants]
description: Adds enchantments to the item in your hand
usage: Hold the item you wish to enchant and type /enchant
superenchant:
aliases:
- powerup
disenchant:
description: Removes enchantments from the item in your hand
usage: Hold the item you wish to disenchant and type /disenchant