Add your own event

Overview

On this page, we will be explaining how you can create custom events for AdditionsPlus that can eventually be used by the end-users after registration. You can call these events from your code to perform the configured actions. Please make sure that you have set up the dependency correctly. You can read how here.

What is an event?

In AdditionsPlus, you can call an event from your code that will execute the actions that are configured in the events.yml file. You can add additional options to your events for users to configure the event or send over other data, besides the actions. These options are optional, and the user has to add them manually, so make sure you use defaults.

All events consist of two parts: the plugin name and the event name, joined by a hyphen (-). The entire event identifier is stored in lowercase, regardless of the name you registered it as. It is advised that you do not enter too long plugin/event names. For example, use SWR instead of SkyWarsReloaded.
All events that are registered under the Bukkit plugin are registered without the plugin name in the identifier and have to be accessed by just the event name. This may only be used for Bukkit events.

Example Event:

firstjoin: # This is registered under "Bukkit".
  actions: # list of actions to execute on call.
  - '[msg]&aWelcome to the server, &e%player%&a!'

yourplugin-eventname: # This is registered under "yourplugin" with the name "eventname".
  option-one: 'hello' # extra option. # Extra option for your event.
  option-two: 4.5
  actions: # list of actions to execute on call.
  - '[title]&a&lEVENT\n&7Called a custom event'

Add a new event

For this example, you need the AdditionsAPI class as explained here.

For this example, we will be creating an event for a custom Mob plugin that is being fired when a custom mob has been killed. This code consists of two parts: the registration and the calling of the event.

Register the event

This example code is written for the main class of your plugin, executed when the plugin is being enabled.

@Override
public void onEnable() {
    AdditionsPlus additions = (AdditionsPlus) Bukkit.getPluginManager().getPlugin("Additions");
    AdditionsAPI api = additions.getAPI();

    // creating the event with id "custommobs-kill".
    AdditionsEvent event = api.createCustomEvent(additions, "CustomMobs", "kill", "Author", "Called when a custom mob has been killed");
    boolean registered = api.registerCustomEvent(event);

    if (registered) Bukkit.getLogger().info("Successfully registered the custommobs-kill event.");
    else Bukkit.getLogger().severe("Failed to register the custommobs-kill event.");
}

Calling the event

AdditionsPlus additions = (AdditionsPlus) Bukkit.getPluginManager().getPlugin("Additions");

// Getting the registered event (all lowercase!).
AdditionsEvent event = additions.getAPI().getEventById("custommobs-kill");
// Adding custom placeholders, without %%.
// Understand that placeholders will be cleared when calling #perform. If you're doing this in a loop, make sure to add them in every iteration.
event.addPlaceholder("mob", event.getMobName());
event.addPlaceholder("killer", event.getKiller().getName());
// Calling/performing the event.
event.perform(additions, event.getKiller());