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
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.
You can set and later modify colors, fade colors, shapes etc. There are getters, setters, addition and removal methods for all of those properties.
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
| ||A small standard ball.|
| ||A large standard ball.|
| ||A 3D star.|
| ||A quite random "bursting" shape.|
| ||A creeper face.|
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)
This property describes whether the particles spawned by this effect during the firework explosion shall flicker.
public boolean hasFlicker() public FireworkEffectDefinition setFlicker(boolean flicker)
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)
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)
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)
Because all modifiers on the firework effect definition return the object itself, you can chain calls in order to create compact one-liners:
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
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)