Create Custom Firework

To create a new Firework, you need to write your own class in your separate plugin.

Basic structure:

• The plugin has one instance of the Firework class per key, which will be registered.
• That Firework creates an ItemStack, which contains a NBT tag containing the Firework key.
• States like Location specific tasks will be saved and handled in separate objects.

Creating a new Firework is as simple as extending the AbstractFireWork class.
There are two default abstract classes with predefined behaviour.

• BlockFireWork - A firework that can be placed into the world.
• ItemFireWork - A firework using a projectile like eggs, arrows, snowballs, etc.

If you would like to make a firework with custom behaviour, you should extend the AbstractFireWork directly.

Basic Firework setup

Each firework requires a unique NamespacedKey to identify it. It is recommended to use your plugin for the NamespacedKey.

new NamespacedKey(yourPlugin, "your_custom_firework");

When done creating it, you need to register the firework, so the plugin can use it.

FireWorksRegistry registry = FancyFirework.getPlugin().getRegistry();

registry.register(yourCustomFirework);

Fireworks with predefined behaviour

BlockFireWork

This firework can be placed into the world. When placing it, it spawns an ArmorStand on the clicked block. The ItemStack of the Firework is placed on the Head of the ArmorStand.

There are a few methods that are called dependent on the action.

    /**
     * Called when a player places the firework.
     *
     * @param block The placed block.
     * @param stand The spawned ArmorStand of the firework.
     * @param player The player that placed the firework.
     */
    public abstract void onPlace(Block block, ArmorStand stand, Player player);

    /**
     * Called when the firework is lit by a player using flint and steel.
     *
     * @param stand The ArmorStand of the firework, that was lit.
     * @param player The player that lit the firework.
     */
    public abstract void onLit(ArmorStand stand, @Nullable Player player);

    /**
     * Called when a task of this firework executes a tick.
     *
     * @param task The task that executed the tick.
     * @param active If the delay has passed and the task is actively running.
     */
    public abstract void onTick(Task task, boolean active);

The methods are only called once (except for the onTick)!
To have a behaviour like the battery fireworks, you need to start a task that actually spawns the effects and fireworks.

Task

The task represents the state of an individually placed firework. It handles the runtime of the firework and can be used to spawn effects, etc.

The task requires the properties:
player - The player that executed the task. e.g. who lit the firework.
armorStand - The ArmorStand that this task belongs to.
duration - The total duration of the task. In ticks.
delay - The initial delay of the task. In ticks.
period - The period of the task. In ticks.
taskTORun - The task that runs every period.

You can of course extend the Task class too, to save custom settings and or Runnables, etc.

Each tick, the task will call the BlockFireWork#onTick, even before the initial delay has passed!
To check if the delay has passed, use the active argument from the onTick or the Task#isActive method.

ItemFireWork