Particle FX API

The particle FX API, which resides in the package com.quartercode.quarterbukkit.api.fx.particle, allows you to quickly spawn the vanilla Minecraft particle effects like smoke or hearts we all know and love.

Defining particle effects

In the particle FX package, there exists a ParticleDefinition class which defines how a single spawned particle effect should look like. You create instances of this class to describe the particles and later pass them to the ParticleSpawner, which actually takes care of spawning them.

Properties

You can set different particle properties like the particle type, the particle amount etc. There are getters and setters for all of those properties.

Type

The type defines the look and behavior of the particles. Currently, Minecraft provides 35 possible types, which are all listed in the ParticleType enum. For a comprehensive list of all the particle effects and detailed information on each of them, take a look at the JavaDoc for ParticleType. They aren't listed here because the wiki would just get out of date very quickly.

When you create a new particle 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 ParticleDefinition(ParticleType type)
public ParticleType getType()
public ParticleDefinition setType(ParticleType type)

Amount

This property describes how many individual particles should be spawned when the particle definition is spawned. If the spread vector of the particle definition is the zero vector, the particles pretty much overlay each other. However, using the spread vector, you can create a spread of multiple individual particles over a specified field.

public int getAmount()
public ParticleDefinition setAmount(int amount)

Spread

This property describes how far away from the spawning location individual particles can appear. For example, if the x component of the vector is 2, the individual particles can spawn up to 2 blocks above or below the spawning location. Note that the amount property is quite useful in combination with the spread vector, since you can use high amounts to create a spread of multiple individual particles over a specified field.

public Vector getSpread()
public ParticleDefinition setSpread(Vector spread)

Parameter

The parameter property customizes the spawned particles in a way that's specific to the very particle type. Please refer to the JavaDoc description of the different types in ParticleType for more information. Note that some types do not support a parameter. The ParticleType.hasParameter() returns false for those types.

public float getParameter()
public ParticleDefinition setParameter(float parameter)

Chaining modifications

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

new ParticleDefinition(ParticleType.FIREWORKS_SPARK).setAmount(10).setSpread(new Vector(0, 2, 0));

Cloning

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

public ParticleDefinition(ParticleDefinition from)

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

public ParticleDefinition from(ParticleDefinition from)

Spawning particles

Defining particles is well and good, but of what use are they if nobody ca see them? Thereby, the most important class is easily ParticleSpawner, which contains a utility method for spawning the defined particle effect at a specified location.

public static void spawn(Location location, ParticleDefinition particle)

The spawner class handles all the dirty work in the background, so that you do only have to care about the creative aspect of designing beautifully looking particle arrangements.