Developer API: Making an Ability Trigger - BoBoBalloon/InnovativeItemsDOCS Wiki

Intro

For this example, I will demonstrate below an ability trigger that fires every time a player picks up the custom item.

Make a new Ability Trigger

First make a new class that extends the AbilityTrigger class. Keep in mind that this class has two generic types.

public class PickupItemTrigger extends AbilityTrigger<Event, RuntimeContext> {
    public PickupItemTrigger() {
        super();
    }

    @NotNull
    public Player fromEvent(@NotNull Event event) {

    }

    @NotNull
    public RuntimeContext trigger(@NotNull Event event, @NotNull CustomItem item, @NotNull Ability ability) {

    }
}

The ability trigger class header looks like so: AbilityTrigger<T extends Event, S extends RuntimeContext>

Because of that we can change our class header a look a little something like this:

public class PickupItemTrigger extends AbilityTrigger<EntityPickupItemEvent, RuntimeContext> {
    public PickupItemTrigger() {
        super();
    }

    @NotNull
    public Player fromEvent(@NotNull EntityPickupItemEvent event) {

    }

    @NotNull
    public RuntimeContext trigger(@NotNull EntityPickupItemEvent event, @NotNull CustomItem item, @NotNull Ability ability) {

    }
}

Make a new Ability Trigger: Constructor

The constructor signature of an ability trigger looks a little something like this:

public AbilityTrigger(@NotNull String identifier, @Nullable String regex, @NotNull Class<T> eventClass, @NotNull Class<S> contextClass, @NotNull InventoryIterator<T> iterator, @Nullable Predicate<T> predicate, @NotNull FunctionTargeter... targeters)

Let's break each parameter down:

Lets update our constructor to pass these into the superclass's constructor:

public PickupItemTrigger() {
    super("item-pickup", null, EntityPickupItemEvent.class, RuntimeContext.class, InventoryIterator.fromFunctionSingleton((event, inventory) -> event.getItem().getItemstack()), event -> event.getEntity() instanceof Player);
}

We could skip the targeters parameter because if you leave a vararg empty it becomes an empty array and the api will add the player targeter for you.

Make a new Ability Trigger: fromEvent() Method

The fromEvent() method is a simple method that should be used to return a player from type T. Keep in mind that this will only be called if the predicate in the constructor is null or returned true.

Lets update our fromEvent() method to match this:

@NotNull
public Player fromEvent(@NotNull EntityPickupItemEvent event) {
   return (Player) event.getEntity(); //we can cast this safely because the predicate in the constructor already did an instanceof check
}

Make a new Ability Trigger: trigger() Method

The trigger method will be called every time a custom item with an ability with your ability trigger is found in the collection your InventoryIterator found. It will pass you the instance of the event, with the instance of the custom item, an the instance of the ability. With that you are required to return an instance of the type S that will be used for ability execution.

Do NOT execute the provided ability inside of the trigger method, it will be handled for you.

Since this trigger is pretty elementary, the trigger method will be pretty straightforward.

@NotNull
public RuntimeContext trigger(@NotNull EntityPickupItemEvent event, @NotNull CustomItem item, @NotNull Ability ability) {
    return new RuntimeContext(this.fromEvent(event), ability);
}

Make a new Ability Trigger: All Together

We have already cover all the basic elements of an ability trigger, the final product is below:

public class PickupItemTrigger extends AbilityTrigger<EntityPickupItemEvent, RuntimeContext> {
    public PickupItemTrigger() {
        super("item-pickup", null, EntityPickupItemEvent.class, RuntimeContext.class, InventoryIterator.fromFunctionSingleton((event, inventory) -> event.getItem().getItemstack()), event -> event.getEntity() instanceof Player);
    }

    @NotNull
    public Player fromEvent(@NotNull EntityPickupItemEvent event) {
        return (Player) event.getEntity(); //we can cast this safely because the predicate in the constructor already did an instanceof check
    }

    @NotNull
    public RuntimeContext trigger(@NotNull EntityPickupItemEvent event, @NotNull CustomItem item, @NotNull Ability ability) {
        return new RuntimeContext(this.fromEvent(event), ability);
    }
}

Registering the Ability Trigger

Just like with functions, ability triggers must be registered via the FunctionManager that can be obtained using the InnovativeItemsAPI utility class. Please remember that like functions, ability triggers must be registered on the onLoad() method, it will not work if you register on the onEnable() method of your main class. Also, don't worry about registering the bukkit event listener, that is handled in the backend for you.

@Override
public void onLoad() {
    FunctionManager functionManager = InnovativeItemsAPI.getFunctionManager();

    functionManager.registerTriggers(new PickupItemTrigger());
}