Firework FX API

The firework FX API, which resides in the package com.quartercode.quarterbukkit.api.fx.firework, allows you to quickly spawn firework effects without actually spawning a firework entity. Actually, an entity is spawned in the background, but it is hidden from everybody so that everything that remains is the desired firework effect.

Spawning pure fireworks

The most important class is the FireworkEffectSpawner, which contains four utility methods for spawning the described effect-only fireworks. The first two use standard Bukkit FireworkEffect you're probably already quite familiar with:

public static void spawnBukkit(Location location, FireworkEffect... bukkitEffects)
public static void spawnBukkit(Location location, Collection<FireworkEffect> bukkitEffects)

The other two use a new QuarterBukkit class called FireworkEffectDefinition:

public static void spawn(Location location, FireworkEffectDefinition... effects)
public static void spawn(Location location, Collection<FireworkEffectDefinition> effects)

The FireworkEffectDefinition class

That class represents a single effect that is part of the explosion of a firework. Essentially, it is a mutable version of the standard FireworkEffect class that already comes with Bukkit.

Properties

You can set and later modify colors, fade colors, shapes etc. There are getters, setters, addition and removal methods for all of those properties.

Type

The type defines the arrangement of the spark particles, which are created by the firework effect explosion, in the world. Currently, Minecraft provides 5 possible types in the FireworkEffect.Type enum:

When you create a new firework effect definition, you immediately have to set a type, which can, however, be accessed and changed later on. Of course, it's impossible to have a null effect type.

public FireworkEffectDefinition(FireworkEffect.Type type)
public FireworkEffect.Type getType()
public FireworkEffectDefinition setType(FireworkEffect.Type type)

Flicker

This property describes whether the particles spawned by this effect during the firework explosion shall flicker.

public boolean hasFlicker()
public FireworkEffectDefinition setFlicker(boolean flicker)

Trail

This property describes whether the particles spawned by this effect during the firework explosion leave behind a trail of other particles. Note that this option is only recommended in situations where there are only few other particles because the trail increases the particle amount by quite a bit.

public boolean hasTrail()
public FireworkEffectDefinition setTrail(boolean trail)

Colors

The colors define the ... well ... colors of the particles. You can't control which color every particle has, but you can define as many as you want and they will nicely mix together:

public List<Color> getColors()
public FireworkEffectDefinition setColors(Color... colors)
public FireworkEffectDefinition setColors(Collection<Color> colors)
public FireworkEffectDefinition addColors(Color... colors)
public FireworkEffectDefinition addColors(Collection<Color> colors)
public FireworkEffectDefinition removeColors(Color... colors)
public FireworkEffectDefinition removeColors(Collection<Color> colors)

Fade Colors

The particles will fade to another colors after some seconds (not configurable). Here, you can define those colors:

public List<Color> getFadeColors()
public FireworkEffectDefinition setFadeColors(Color... colors)
public FireworkEffectDefinition setFadeColors(Collection<Color> colors)
public FireworkEffectDefinition addFadeColors(Color... colors)
public FireworkEffectDefinition addFadeColors(Collection<Color> colors)
public FireworkEffectDefinition removeFadeColors(Color... colors)
public FireworkEffectDefinition removeFadeColors(Collection<Color> colors)

Chaining modifications

Because all modifiers on the firework effect definition return the object itself, you can chain calls in order to create compact one-liners:

new FireworkEffectDefinition(Type.BALL).setFlicker(true).addColors(Color.RED).addFadeColors(Color.BLUE);

Cloning

The FireworkEffectDefinition class actually provides a copy constructor you can use to clone the object if needs be:

public FireworkEffectDefinition(FireworkEffectDefinition from)

If you want to copy the information from one effect into another existing object instead, that's also possible:

public FireworkEffectDefinition from(FireworkEffectDefinition from)

Converting between FireworkEffectDefinition and Bukkit's FireworkEffect

Often, you just need a standard Bukkit FireworkEffect in the end although you want to manage your effects using the more versatile FireworkEffectDefinition class. For such cases, the definition class provides the following conversion method:

public FireworkEffect toBukkit()

Of course, the inverse way is also possible. This constructor creates a new definition instance out of the properties stored in a Bukkit FireworkEffect:

public FireworkEffectDefinition(FireworkEffect from)

If you want to copy the information from the Bukkit effect into an existing FireworkEffectDefinition object instead, that's also possible:

public FireworkEffectDefinition fromBukkit(FireworkEffect from)