How To Register An Event Spigot
This folio is part of the official Bukkit Documentation
This page has been accepted and included in the official Bukkit Documentation. You can discuss discrepancies, bug, or errors in the article on its Talk page.
Welcome to Bukkit's Effect API reference page.
Contents
- 1 Introduction
- 2 The Basics
- 2.1 Setting upwards the Method
- 2.two @EventHandler
- 2.3 Calculation the listener
- 2.4 EventHandler Parameters
- 2.4.one Result Priorities
- 2.4.one.one Case with a BlockPlaceEvent
- 2.4.one Result Priorities
- 3 Registering Events
- 3.1 Case Listener
- 3.2 Registering Events in Plugin
- 3.two.1 Registering Events with Plugin equally Listener
- 3.iii Registering Events in your Listener
- 4 Un-registering events or listeners
- 4.1 Un-register specific event
- 4.2 Un-annals all events
- 5 Creating Custom Events
- 5.ane Custom Outcome Example
- 5.1.1 Calling your Custom Event
- 5.one.2 Listening to a Custom Event
- v.one.iii Making your CustomEvent Cancellable
- 5.ane Custom Outcome Example
- 6 Videos
Introduction
Events are how the CraftBukkit server tells your plugin that something has happened in the world. Bukkit defines many events, in multiple categories; e.g. player deportment (player logged in, thespian clicked a block, player died, role player respawned...), cake events (block placed, block broken, cake'due south neighbour changed...), entity events (a mob targeted y'all, a creeper exploded...), world-wide events (a world loaded or unloaded, a clamper loaded or unloaded), and many more. Due to unknown reasons there is no longer any links to official Javadocs every bit they have all been taken off line.
The Basics
To go on this section simple, nosotros're going to simply work with PlayerLoginEvent. Lets start with setting up the method
Setting upward the Method
In order for your plugin to handle an event call, you lot need to create a method for information technology:
@EventHandler public void onLogin ( PlayerLoginEvent event ) { // Your code hither... } Before this method tin exist invoked by Bukkit when the "PlayerLoginEvent" is fired, we need to annotate information technology. We practise this with EventHandlers.
@EventHandler
The "@EventHandler" course is an Annotation, which goes just above your method. It looks like this:
@EventHandler // EventPriority.NORMAL by default This marks your method every bit an EventHandler with the EventPriority as NORMAL.
The EventHandler can take an EventPriority to specify the priority of the method, like so:
@EventHandler ( priority = EventPriority . HIGHEST ) // Makes your method Highest priority @EventHandler ( priority = EventPriority . Depression ) // Makes your method Depression priority Here'due south what it would look like in your class:
@EventHandler public void onLogin ( PlayerLoginEvent result ) { // Your lawmaking here... } Adding the listener
In gild for Bukkit to be able to register your EventHandler's, the class which contains your outcome handling methods must implement the Listener (org.bukkit.event.Listener) interface, e.thousand.:
public last class MyPlayerListener implements Listener { @EventHandler public void onLogin ( PlayerLoginEvent issue ) { // Your code hither... } } The proper noun of the method (onLogin in the to a higher place example) does not matter; you may call the method anything you like inside your listener.
You may be wondering.. "How does Bukkit know which result to listen to?" It knows that by the issue parameter you specify in the method's signature - in the above example: PlayerLoginEvent.
-
Note: You must specify a unmarried specific effect or Bukkit will not be able to register it
Your main plugin grade (i.e. the class which extends JavaPlugin) can also exist an event listener, and this might make sense if your plugin is very pocket-sized. E.g.:
public class MyPlugin extends JavaPlugin implements Listener { @Override public void onEnable () { getServer (). getPluginManager (). registerEvents ( this , this ); } @EventHandler public void onLogin ( PlayerLoginEvent event ) { getLogger (). log ( Level . INFO , "Histrion " + event . getPlayer (). getName () + " is logging in!" ); } } EventHandler Parameters
The @EventHandler annotation tin can have parameters to farther define how the event handler behaves. At the moment yous can specify:
| Proper noun | Type | Default | Clarification | Values |
|---|---|---|---|---|
| priority | EventPriority | EventPriority.NORMAL | Sets the priority of your method |
|
| ignoreCancelled | boolean | false | If gear up to true, your method will not get the upshot if the event has been cancelled |
|
Outcome Priorities
There are 6 priorities in Bukkit:
- EventPriority.MONITOR
- EventPriority.HIGHEST
- EventPriority.Loftier
- EventPriority.NORMAL
- EventPriority.LOW
- EventPriority.Lowest
Every plugin gets a say in what happens, and every plugin must get a chance to know the outcome of an event. Then, nosotros laissez passer events to plugins even later they've been cancelled. A plugin can actually uncancel an consequence afterward another plugin cancelled it. This is where priorities become really important. When changing values of an event the changes of one with the higher priority will override whatever changes done before by a listener with a lower priority and so that in the end the ane with the highest priority can have the final say in the actually outcome. To achieve this priority guild listeners are called from the ones with the lowest to the ones with the highest priority. Whatsoever listener with the MONITOR priority is called final.
If you want to change the consequence of an event, choose very advisedly from Everyman to HIGHEST. Suggested generalized protection plugins on lowest, more specific plugins on normal, and override plugins on high.
If you want to human activity when an event happens, simply not change the outcome, use MONITOR. Information technology'due south really really important that y'all use MONITOR, or an event might get cancelled afterwards you've acted on information technology, and it's even more of import that you don't modify the event of the result on MONITOR or it'll break other plugins.
Example with a BlockPlaceEvent
The lowest priority listener is called to become its say in whether it should exist cancelled or not. And so the low priority listener is called to see if it wants to override the lowest, etc. Somewhen it hits monitor, and at this point nothing should alter the event of the consequence. Monitor should exist used to see the upshot of an upshot, without changing any aspect of it. If we accept three plugins enabled; one is a bones area protection plugin, one is a fancy plugin using signs, and another is a logging plugin. The protection plugin listens on EventPriority.LOWEST. Information technology says they can't place blocks in this area, and cancels the event. The fancy sign plugin listens on EventPriority.NORMAL. It says they tin can place signs hither, and uncancels the event. The log plugin listens on EventPriority.MONITOR. It sees that the event was really immune, and logs it.
Registering Events
To register your methods, the grade containing the EventHandler(s) must implement the Listener interface.
import org.bukkit.outcome.Listener ; public final class LoginListener implements Listener { }
You only demand to provide a plugin and a listener to annals them in the PluginManager.
getServer (). getPluginManager (). registerEvents ( Listener , Plugin );
Instance Listener
This listener contains two EventHandlers. One listening on HIGH, and one on NORMAL.
import org.bukkit.consequence.Listener ; import org.bukkit.event.EventHandler ; import org.bukkit.issue.EventPriority ; import org.bukkit.issue.actor.PlayerLoginEvent ; public final class LoginListener implements Listener { @EventHandler public void normalLogin ( PlayerLoginEvent event ) { // Some lawmaking here } @EventHandler ( priority = EventPriority . HIGH ) public void highLogin ( PlayerLoginEvent outcome ) { // Some lawmaking here } }
Registering Events in Plugin
The registerEvents method requires a listener and a plugin. Luckily, we already have our LoginListener. At present for the LoginPlugin!
import org.bukkit.plugin.coffee.JavaPlugin ; public final class LoginPlugin extends JavaPlugin { public void onEnable () { getServer (). getPluginManager (). registerEvents ( new LoginListener (), this ); } }
Registering Events with Plugin every bit Listener
Y'all could fifty-fifty have the events in the principal grade, for example:
import org.bukkit.plugin.java.JavaPlugin ; import org.bukkit.event.Listener ; import org.bukkit.event.EventHandler ; import org.bukkit.event.role player.PlayerLoginEvent ; public final class LoginPlugin extends JavaPlugin implements Listener { public void onEnable () { getServer (). getPluginManager (). registerEvents ( this , this ); } @EventHandler public void normalLogin ( PlayerLoginEvent outcome ) { // Some code hither } }
Registering Events in your Listener
There are many ways to register your events. Here's an example where y'all register them in your listener class.
import org.bukkit.event.Listener ; import org.bukkit.consequence.EventHandler ; import org.bukkit.event.EventPriority ; import org.bukkit.event.player.PlayerLoginEvent ; public final class LoginListener implements Listener { public LoginListener ( LoginPlugin plugin ) { plugin . getServer (). getPluginManager (). registerEvents ( this , plugin ); } @EventHandler public void normalLogin ( PlayerLoginEvent event ) { // Some lawmaking here } @EventHandler ( priority = EventPriority . Loftier ) public void highLogin ( PlayerLoginEvent event ) { // Some code here } }
The LoginPlugin would look like this:
import org.bukkit.plugin.coffee.JavaPlugin ; public final course LoginPlugin extends JavaPlugin { public void onEnable () { new LoginListener ( this ); } }
Un-registering events or listeners
You tin can un-annals private events, entire listener classes or all events registered by your plugin or even by other plugins!
United nations-annals specific outcome
Each event class has the getHandlerList() static method, call that and and so you tin apply .unregister() method. Instance:
PlayerInteractEvent . getHandlerList (). unregister ( plugin ); // this volition unregister all PlayerInteractEvent instances from the plugin // you can also specify a listener course instead of plugin.
Now you lot know why you'll need the getHandlerList() in your custom events.
Un-register all events
Using the HandlerList class and its unregisterAll() static method you lot can easily unregister events from listener classes or plugins. Example:
HandlerList . unregisterAll ( plugin ); // this will unregister all events from the specified plugin // yous tin also specify a listener course instead of plugin.
Creating Custom Events
Creating custom events is very unproblematic, you can use the same system that Bukkit uses without ruining performance.
There are two (2) things to keep in mind when you create a Custom Outcome. They are "extend Consequence" and "static handlers." With static handlers, you must input the post-obit code into your custom effect:
private static final HandlerList handlers = new HandlerList (); public HandlerList getHandlers () { return handlers ; } public static HandlerList getHandlerList () { return handlers ; }
This block of code makes the EventHandlers contained inside your ain issue, keeping any unrelated events completely separated.
Custom Event Case
The following example shows how easy information technology is to create your own "CustomEvent."
import org.bukkit.outcome.Event ; import org.bukkit.event.HandlerList ; public terminal form CustomEvent extends Effect { individual static final HandlerList handlers = new HandlerList (); private String message ; public CustomEvent ( String example ) { message = example ; } public Cord getMessage () { render bulletin ; } public HandlerList getHandlers () { return handlers ; } public static HandlerList getHandlerList () { return handlers ; } }
Calling your Custom Result
Yous are in control of creating and calling your events, where you call it is completely up to y'all. Here'southward an instance
// Create the issue here CustomEvent outcome = new CustomEvent ( "Sample Bulletin" ); // Telephone call the event Bukkit . getServer (). getPluginManager (). callEvent ( event ); // Now you do the event Bukkit . getServer (). broadcastMessage ( consequence . getMessage ());
Remember: You are in control of your events. If yous don't telephone call it, and human action upon it, information technology doesn't happen!
Listening to a Custom Event
How exercise you listen to a custom outcome you lot say? Simple, the aforementioned way as listening to a normal event!
import org.bukkit.event.Listener ; import org.bukkit.event.EventHandler ; public final class CustomListener implements Listener { @EventHandler public void normalLogin ( CustomEvent effect ) { // Some code here } }
Making your CustomEvent Cancellable
If you ever want to make your effect cancellable, remember one thing: "implements Cancellable." Just like y'all would import Listener. Information technology's really that simple, let me show you an instance!
import org.bukkit.upshot.Outcome ; import org.bukkit.effect.HandlerList ; import org.bukkit.event.Cancellable ; public last class CustomEvent extends Event implements Cancellable { private static final HandlerList handlers = new HandlerList (); private String bulletin ; private boolean cancelled ; public CustomEvent ( String instance ) { message = example ; } public String getMessage () { return message ; } public boolean isCancelled () { return cancelled ; } public void setCancelled ( boolean cancel ) { cancelled = cancel ; } public HandlerList getHandlers () { return handlers ; } public static HandlerList getHandlerList () { return handlers ; } }
After, you lot would cheque if a plugin had cancelled the event in your code, before processing normally
// Create the result here CustomEvent event = new CustomEvent ( "Sample Message" ); // Call the event Bukkit . getServer (). getPluginManager (). callEvent ( event ); // Bank check if the event is non cancelled if (! event . isCancelled ()) { // Now you lot practise the event Bukkit . getServer (). broadcastMessage ( event . getMessage ()); }
Videos
| Linguistic communication | English • беларуская • Deutsch • español • suomi • français • italiano • 한국어 • Nederlands • norsk • polski • português • русский • lietuvių • čeština |
|---|
Source: https://bukkit.fandom.com/wiki/Event_API_Reference
Posted by: elliottfarge1958.blogspot.com
0 Response to "How To Register An Event Spigot"
Post a Comment