Particle API

The old particle API is deprecated since version 0.3.0, and was completely removed in version 0.4.0. Use the new Object System instead.

We created the first particle system API in the Bukkit history! It's using fireworks for displaying the particles and it's not as customizable as regulary engine tools, but it enables to spawn particles without any client modifications!

Particle System

The ParticleSystem class is the core of the API. There are many constructors for creating the system and filling it with values in one line:

public ParticleSystem();
public ParticleSystem(Location location);
public ParticleSystem(ParticleDescription... descriptions);
public ParticleSystem(List<ParticleDescription> descriptions);
public ParticleSystem(Location location, ParticleDescription... descriptions);
public ParticleSystem(Location location, List<ParticleDescription> descriptions);

We're going into the arguments later on.

There are also many methods for configuring your particle system. You can also change the properties in real-time while your animation is running!

Particle Description

public List<ParticleDescription> getDescriptions()
public ParticleSystem setDescriptions(ParticleDescription... descriptions)
public ParticleSystem setDescriptions(List<ParticleDescription> descriptions)
public ParticleSystem addDescription(ParticleDescription description)
public ParticleSystem removeDescription(ParticleDescription description)

You can mofify the particle description list with those methods.

There are also many constructors for the description as well:

public ParticleDescription()
public ParticleDescription(ParticleShape shape)
public ParticleDescription(Color... colors)
public ParticleDescription(List<Color> colors)
public ParticleDescription(ParticleShape shape, Color... colors)
public ParticleDescription(ParticleShape shape, List<Color> colors)

ParticleDescriptions describe your particles. You can set colors, fade colors, shapes etc. There are getters, setters, add- and remove-methods for all of those properties, so this part will only explain the different ones.

Shape

public ParticleShape getShape()
public ParticleDescription setShape(ParticleShape shape)

The shape defines the arrangement of the particles in the world. There are currently 5 possible shapes:

Colors

public List<Color> getColors()
public ParticleDescription setColors(Color... colors)
public ParticleDescription setColors(List<Color> colors)
public ParticleDescription addColor(Color color)
public ParticleDescription removeColor(Color color)

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 mix nicely together.

Fade Colors

public List<Color> getFadeColors()
public ParticleDescription setFadeColors(Color... colors)
public ParticleDescription setFadeColors(List<Color> colors)
public ParticleDescription addFadeColor(Color color)
public ParticleDescription removeFadeColor(Color color)

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

Start Location

public Location getLocation()
public ParticleSystem setLocation(Location location)

The start location defines where the animation will start. If you don't create an animation, your particles will always spawn around this location.

Runs

public int getRuns()
public ParticleSystem setRuns(int runs)

The run property defines the count of runs the particle system should emit particles. If you set it to -1 or lower, your animation will go on forever (until you cancel it).

Rate/Delay

public int getRate()
public ParticleSystem setRate(int rate)

The rate defines the delay between two runs in milliseconds. You can set it to any value you want (of course, 0 is not recommended for a large amount of runs).

Animation

public Vector getAnimation()
public ParticleSystem setAnimation(Vector animation)

The animation is a simple vector which defines the movement direction of the source location. The default value is 0, 0, 0, so your animation wont move.

Particle Spawner

public ParticleSpawner getSpawner()
public ParticleSystem setSpawner(ParticleSpawner spawner)

The particle spawner is kind of the renderer for the particles. The default one is the <code>DefaultParticleSpawner<code> which implements the interface ParticleSpawner. You can create implementing classes and implement the spawn(Plugin, List<ParticleDescription>, Location) method, but it's recommended to extend the default class so you don't have to write your own firework code.

Run Methods

There are several self-explanatory methods for run or stop the configured particle animation:

public boolean isRunning()
public ParticleSystem start(Plugin plugin)
public ParticleSystem stop()

The plugin is used for the schedule task and exceptions, so you can't use null.

Event Customization Methods

There are some methods which you can override in subclasses for doing some own stuff at those events:

protected void execute(Plugin plugin, Location location)
protected void end(Plugin plugin, Location location)

Example Usage

This is a simple oneliner for one particle emission at the location location:

new ParticleSystem(location, new ParticleDescription(ParticleShape.STAR, Color.FUCHSIA)).start(plugin);

This example shoots particle sources in every direction from the initial location location:

for (double vx = -1; vx <= 1; vx += 0.5) {
    for (double vy = -1; vy <= 1; vy += 0.5) {
        for (double vz = -1; vz <= 1; vz += 0.5) {
            new ParticleSystem(location, new ParticleDescription(ParticleShape.BALL_SMALL, Color.WHITE)).setRate(100).setRuns(10).setAnimation(new Vector(vx, vy, vz).divide(10)).start(plugin);
        }
    }
}