Bukkit: How would I call an event?

Question

I just started coding Bukkit and I have been trying to code a plugin that enable pvp for a certain player, and can disable it but only for themselves. It was working fine until I found I needed an event to make this work, yet I have not learned of the event I need. After looking at a few videos/things online I cannot find anything to help me. If you could tell me how I would do this, that would be great. Also if you could explain more about events that would also be appreciated :)

package me.impatheimpaler.test;

import java.util.ArrayList;
import java.util.List;
import org.bukkit.ChatColor;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class togglepvp extends JavaPlugin implements Listener{

    public void onEnable() {

    }

    public void onDisable() {

    }

    List<String> toggled = new ArrayList<String>();

    public boolean onCommand(CommandSender sender, Command cmd, String commandLabel, String[] args) {
        if (cmd.getName().equalsIgnoreCase("togglepvp")) {
            if (!(sender instanceof Player)) {
                 sender.sendMessage("Only a Player can run this command.");
                 return false;
            }
            Player player = (Player) sender;
            if (toggled.contains(player.getName())) {
                 player.sendMessage(ChatColor.RED + "Outgoing PvP - ON");
                 toggled.add(player.getName());
                 return true;
            }
            player.sendMessage(ChatColor.GREEN + "Outgoing PvP - OFF");
            toggled.remove(player.getName());
            return true;
        }
    }
}

Answer 1

To call an event you can use:

Bukkit.getServer().getPluginManager().callEvent(myEvent)

But, based on your question, I think that you mean that you would like to listen for an event, so you can preform certain actions when the event happens. To do this, first make the class that you would like to listen in implement Listener

public class MyHandlerClass implements Listener{
  //code
}

Next, you have to register events in your Main class, which is the one that extends JavaPlugin. To do this, find your onEnable() method, and call this.getServer().getPluginManager().registerEvents(Listener, this), where Listener is your listener class:

@Override
public void onEnable(){
  this.getServer().getPluginManager().registerEvents(new MyHandlerClass(), this);
  //other code
}

Next, to actually handle the events, make a function in your handler class (the one that implements Listener), with one argument that extends Event, and that has the @EventHandler annotation above it, for detecting an entity damaging another entity, you could use the event EntityDamageByEntityEvent:

@EventHandler
public void entityDamageByEntity(EntityDamageByEntityEvent event){
  //your code here
  //use event.getEntity() to get the entity damaged, and event.getDamager() to get the damager
}

Whenever an entity is damaged by another entity, entityDamageByEntity() will be called automatically, all you have to do is handle the event.

If you would like to cancel the event, you could use event.setCancelled(true)

Answer 2

Also if you could explain more about events that would also be appreciated :)

Well, an Event is, as its name already implicates, something during runtime of the code, that interupts the standard behaviour of your code. In general, this means, that the user does something.

Everytime, Bukkit notices a user doing something, that is covered by the event system, it fires an event:

The following is not the correct form how bukkit and minecraft does it, but I think, it should give you an image about it.

Bukkit creates a new Event (the thing, that is given in your event function, above post called the variable "event") and then it gets every registered listener for this event from its list. (e.g: If a user breaks a block, bukkit will get its own BlockBreakListener and every BlockBreakListener registered by different plugins.) Then the EventHandler will call every method, of those listeners, that is meant to be called, when event is fired.

So for example, it will first handle it's own BlockBreakMethod, then e.g. the one of WorldGuard (if installed) then the one of your plugin and last the one of Authme (if installed). You can not exactly tell in wich order the listeners get informed about the event, so You cannot be sure, wethere you "have the last word" or you are the first to handle the event.

This order is nearly randomly chosen (of course not, but you should imagine that), but you can exert a little bit of influence on the process by setting an event-priority. This is important, for example if you code a minigame, and want to decide, wether a player can break a block or not. Other plugins, that have the same choice, may decide another way as you, so if you have the HIGHER priority, your listener WILL BE EXECUTED AFTERWARDS, so your decision have a deeper impact on the result of the Event (wether it gets cancelled or not).

I hope, I could help you understanding the Events of Bukkit and events in general a little bit better. Do not care how they are generated, this is highly developed java code, so a beginner shouldn't care about it... First of all: Have fun coding :)