API

http://i.imgur.com/3pWoMrW.pnghttp://i.imgur.com/tOxLyvc.pnghttp://i.imgur.com/QC4q9O1.pnghttp://i.imgur.com/12FofvF.pnghttp://i.imgur.com/F1jIKMf.png

v1.2 developers: Things changed a lot recently. The packaging of EquestrianDash is very different. Please update your projects accordingly or they won't work with this new version!

Setup

To start, you only need to add EquestrianDash as a library/to your build path, and set your plugin to depend on EquestrianDash in your plugin YML, like so:

name: CoolPowerups
version: 1.5
author: Me
main: com.MyStuff.CoolPowerups.Core.Main
depend: [EquestrianDash]

The Powerup API

Here you will learn how to make your own powerups.

To start, you'll need a method that hooks into EquestrianDash's PowerupRegistry. To do this, access it from EquestrianDash's main class (I might change the class name at a later date and deprecate this one).

    private PowerupsRegistry getPowerupsRegistry()
    {
        return com.colonelhedgehog.equestriandash.core.EquestrianDash.getPowerupsRegistry();
    }

Then in your onEnable() method, you'll want to put this:

        PowerupsRegistry registry = getPowerupRegistry();

What the powerup registry does is, simply put, toss your powerups into the rotation.

Before you start registering powerups, you'll want to actually make some. Make a new class. Call it whatever you like. For example, "TestPowerup." Make it so TestPowerup implements "com.colonelhedgehog.equestriandash.api.powerup.Powerup" (that's the qualified import, you can import it normally if you'd like).

Once you do that, you'll need to implement all of the methods that a powerup gives you. With these, you are given a variety of functions that will be called at specific times. They're kind of like events, except they're all formatted nicely in one place.

Example? Here is what the speed powerup's class will look like, at its barest:

/**
 * Created by ColonelHedgehog on 11/9/14.
 * You have freedom to modify given sources. Please credit me as original author.
 * Keep in mind that this is not for sale.
 */
public class SpeedPowerup implements Powerup
{
    @Override
    public ItemStack getItem()
    {
        // This is the powerup's icon. When a player hits an item box, it, along with other powerups, shows up in your hotbar. Don't bother adding any lore. Notice how many of my fields are being accessed via Config.

        ItemStack icon = new ItemStack(Material.getMaterial(Main.plugin.getConfig().getString("Powerups.Speed.Material"))); // The powerup's icon.
        ItemMeta iconMeta = icon.getItemMeta(); // Getting its meta.
        iconMeta.setDisplayName(ChatColor.translateAlternateColorCodes('&', Main.plugin.getConfig().getString("Powerups.Speed.Title"))); // Setting its display name to a predefined string in the config.
        icon.setItemMeta(iconMeta); // Now we set all the meta.
        return icon;
    }

    private String getMessage()
    {
        // This isn't technically part of the interface. It just makes things easier, really. :P
        return Main.Prefix + "§aYou used a " + this.getItem().getItemMeta().getDisplayName() + "§a!";
    }

    @Override
    public void doOnRightClick(Racer racer, Action action)
    {
        // This will be performed in the event that you right-click with the item.
        racer.getPlayer().sendMessage(getMessage());
        Horse h = racer.getHorse();
        h.addPotionEffect(new PotionEffect(PotionEffectType.SPEED, 100, 10));

        racer.getPlayer().getInventory().clear();
    }

    // For reference's sake:

    @Override
    public void doOnLeftClick(Racer racer, Action action)
    {
        // This will be performed in the event that you left-click with the item.
    }

    @Override
    public void doOnDrop(Racer racer, Item dropped)
    {
        // This will be performed in the event that you drop the item.
    }

    @Override
    public void doOnRightClickRacer(Racer racer, Racer clicked)
    {
        // This will be performed in the event that you right-click someone with the item.
    }

    @Override
    public void doOnLeftClickRacer(Racer racer, Racer clicked)
    {
        // This will be performed in the event that you left-click (hit) someone with the item.
    }

    @Override
    public void doOnPickup(Racer racer, Racer dropper, Item item)
    {
        // This will be performed in the event that you pick up the item.
    }

    // For not reference's sake:


    // This next part was part of the old API. But I removed it because it was useless.
    /*@Override
    public String getMessage()
    {
        // This is executed when a message needs to be sent to the racer.
        return Main.Prefix + "§aYou used a §fSpeed Powerup§a!"; // Consistancy is cool, yo.
    }*/

    @Override
    public double getChance(int rank)
    {
        return (rank / Main.plugin.getConfig().getDouble("Powerups.Speed.Chance")); 
        // Chance that when we hit an item-box, this will be an option. For this to be effective, you're going to need to use some algebra, as I have done above.
    }

    @Override
    public List<ActionType> cancelledEvents()
    {
        List<ActionType> actions = new ArrayList<>();
        actions.add(ActionType.ALL);
        // In this case, ALL types of actions will be cancelled. You can add the different kinds of events you need to be cancelled to the list. This way the action won't be carried through (for example, canceling the left-click action makes it so your left-click event fires (as described in doOnLeftClickRacer), but doesn't end up with the opposite party getting hurt. 
        return actions;
    }
}