[Tut] The Simple Stuff: Block Listeners

​

Welcome to my new tutorial series, The Simple Stuff. Here I'll be posting tutorials for some of the most fundamental (yet crucial) aspects of creating plugins for Bukkit. If you understand these tutorials, please don't reply saying "Omg this is so easy" - because to a hell of a lot of people, it isn't.

What is listening (if you've read any other of my listener tutorials skip this)?
The Minecraft world is full of things happening all the time. Thousands of events are firing. Event is fairly obviously, an event (such as a block breaking or ice melting). Firing is just a term I'll be using instead of 'happening' or 'occurring'. A listener is a really nice feature CraftBukkit gives us, it lets as listen to everything happening in minecraft, and then run certain code when certain events fire.

Setting up a Block Listener
It's highly recommended that (especially for big plugins), you break down all the events you want to listen to into separate classes for each category of event. There are 9 categories of events, including block events, player events, entity events, and a few others. You can find all the event and event categories here (seriously, bookmark that page).

So we're going to create a new class for listening to all our block events. You'll need to implement the listener interface in order to access of all bukkit's awesome listener functionality! Also, you'll have to import the bukkit listener package (don't accidentally import the java listener package, its an impostor)!

​

Listening
Now we have a class ready, lets create a listener. Theres a huge list of things you can listen to! Each listener type as a specific name that you'll need. You can find all the events for blocks here. Let's say we want to listen to a block breaking event!

First we'll create the method that will run when a BlockBreakEvent occurs.



Remember, onBlockBreak is a name I chose for this method, it can be called whatever you want! The void indicates the method won't return any values.

Registering your Listener with your Plugin
We're nearly ready to start doing things whenever a block is broken! But first we have to register the listener class we just made in our plugin's onEnable() method. Just add this line of code.



Don't forget that you only have to add this line of code for each of your listener classes, NOT for each of your listener methods!

Getting data from events
Whenever a block is broken, as we know, the code inside our onBlockBreak() method will run. But theres a whole load of data that gets stored in the BlockBreakEvent we called 'event'. We can very easily access this data in order to manipulate/process it.

Here's a load of code, don't be daunted, all is explained in the paragraph below! Hopefully it should be pretty self-explanatory if you understand the concept of objects.



Before I explain the code, in the earlier picture I forget to mention that you need to add @EventHandler just above each listener method you create. Don't ask why, just do it, oh and it will need importing too (lots of stuff needs importing, rule of thumb is to make sure its the org.bukkit class your importing, although we do sometimes need to use java's classes).

First we create an object, of the type Block, called block. The data for the broken block is inside the BlockBreakEvent object we created called 'event'. So to access it we simply call the function getBlock() on 'event'.

We do the same thing with afterwards to get the player who broke the block. Only with object type Player instead of Block. The final object is Material of the block that was broken by calling getType() on the previously created Block object.

Finally we're going to send a message (by calling sendMessage() on the player object) to the player and tell them what block they broke. Simple.

Learning from this
Now you understand this (hopefully, if you don't tag me in a reply), you should be able to repeat for pretty much any event under the block category.

• Firstly go to this page and find an event you want to listen to.
• Then click the event and find the different functions you can call (getPlayer(), getBlock(), etc.)
• Then you can create objects and get whatever data the event holds.
• Start manipulating stuff!

Here's a list of just some of the different block related events you can listen to! Found on bukkit's javadocs here.


One last thing, you can really easily stop an event from occurring by listening for the event and then running this code.



What it's doing is setting a property in the object 'event' called cancelled to true. Meaning the event will be cancelled. That's a really simple (and fairly bad) way of stopping players from greifing!

Conclusion
So there we go! You've hopefully learnt how easy it is to use bukkit's javadoc (if somehow you still don't have it bookmarked, do it) in order to find events and find the data they hold so we can listen to them and pull data from them. If you don't understand anything, just leave a reply and I will try to help as soon as possible (or somebody else will)!

Follow @Scullyking
Like this post if it helped you in anyway

 

That should be "implement the Listener interface" - other than that it seems a useful tutorial

 

Ahh, fixed