At this point, you know how to create a plugin that will run some code when a command is executed. This is very useful in many situations. However, we would rather not be required to type in a command sometimes. We'd prefer it if the code could be automatically triggered to be executed. The trigger could be a specific event that occurs on the server, such as a block being broken, a creeper exploding, or a player sending a message in a chat. The Bukkit event system allows a developer to listen for an event and automatically run a block of code based on that event. By using the Bukkit event system, you can automate your server, which means less work for you to maintain the server in the future. In this chapter, we'll cover the following topics:
- Choosing an event
- Registering an event listener
- Listening for an event
- Canceling an event
- Communicating between events
- Modifying an event as it occurs
- Creating more plugins on your own
All the events that Bukkit provides can be found in the API documentation in the org.bukkit.event package. Each event is categorized into packages within org.bukkit.event, such as org.bukkit.event.block, org.bukkit.event.player, and org.bukkit.event.world. This makes it easy to find the event that you are looking for. A full list of the Bukkit events can be found at https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/class-use/Event.html. I encourage you to take a look at the list to see what type of event you can listen for. Each event has several methods, which give you more information and allow you to modify the event. For example, BlockBreakEvent provides methods to get the block that was broken and the player who broke it. Most events can also be canceled if you wish to not allow the events to occur. This is useful in many situations, such as not letting a new player place a TNT block, or preventing a mob from spawning.
As mentioned earlier, listening to events can aid in automating your server and reducing the number of commands being sent. In addition to that, they can simply be a lot of fun to work with. Let's look at a few examples of plugins that can be made using the Bukkit event system. We mentioned that you can listen to the player chat event and modify it as you please. You can use this to monitor messages and censor the offensive words that may be spoken. Placing TNT blocks was also mentioned. You can create a plugin that only lets players place TNT if they have the build.tnt permission node. There is also a WeatherChangeEvent class that can be canceled. That being said, there are many server administrators who don't like it when it rains on the server. Rain can be loud and annoying. Admins will issue the /toggledownfall command to stop the rain every time it starts. In this chapter, we will create a plugin that prevents rain from starting in the first place.
The first thing that we must do is find the appropriate event that we can listen for. To accomplish this, we will have a look at the Bukkit API documentation. Let's say that we are unfamiliar with the API. Therefore, we are unsure about which event we can use. We can look through the list of events until we find the correct one, but you may have better luck if you first find the right package. There are two categories that rain could fall under, namely world events or weather events. It is more likely that rain would be categorized under weather. So, we will look there first. There is no event that includes the word "rain" because rain is categorized with snow. Therefore, the event that we are looking for is the WeatherChangeEvent class. If you did not find a correct event to use, look in other packages.
Tip
If you are ever unable to find the event that you are looking for, then remember that you can ask for help on the Bukkit/Spigot forums. You can perhaps perform a search on the forums first to check whether anyone else was looking for the same information. It is possible that the event that you are attempting to listen for does not exist. Keep in mind that the Spigot project is not associated with the creators of Minecraft. Therefore, it is impossible to detect or modify some events.
Now that we have found the event, we wish to prevent this event from occurring. Viewing the WeatherChangeEvent class reference page, we will see several methods that are offered in this event. We will use the setCancelled method to cancel the event and the toWeatherState method to ensure that we are only preventing the rain from starting and not stopping.