Particles

There are two methods to spawn particles:

• World.spawnParticle() which spawns the particle for all players and
• Player.spawnParticle() which spawns the particle only for the player.

Some particles do not require the additional extra and data fields. This guide explains how the particles that do use these arguments, behave based on their value.

This type of particle has an initial velocity when spawned. The velocity can be determined in two different ways, however both take into account the extra argument as speed.

In the following example 8 flame particles are spawned in a 1x1x1 cube shape randomly, with someLocation serving as it’s center. The last argument (extra) is set to 0, so the particles don’t move.

someWorld.spawnParticle(Particle.FLAME, someLocation, 8, 0.5, 0.5, 0.5, 0);

Setting the count parameter to anything positive will yield a random direction for the velocity. The offset arguments are used as random spawn offset from the location.

An example of spawning 6 crit particles at a location without offset that will move in a random direction at a slow speed:

someWorld.spawnParticle(Particle.CRIT, someLocation, 6, 0, 0, 0, 0.12);

To specify the velocity’s direction, set the count argument to 0 and use the offset arguments as the direction vector.

An example of a repeating task spawning campfire smoke that slowly goes “up” (positive Y axis):

Bukkit.getScheduler().runTaskTimer(plugin,
  () -> someWorld.spawnParticle(Particle.CAMPFIRE_COSY_SMOKE, someLocation, 0, 0, 1, 0, 0.1),
  0, 4);

We could also make the smoke go down if we wanted to:

Bukkit.getScheduler().runTaskTimer(plugin,
  () -> someWorld.spawnParticle(Particle.CAMPFIRE_COSY_SMOKE, someLocation, 0, 0, -1, 0, 0.1),
  0, 4);

The note particles have two different behaviors based on the count argument.

• If set to a positive number a random color (of the preset 24) will be chosen for each spawned particle.
• If set to 0, the offsetX argument will be used as an addition to a HSB (hue, saturation, brightness) color format’s hue value, which has a starting point at a green color.

Example:

someWorld.spawnParticle(Particle.NOTE, someLocation, 0, 0.4f, 0, 0);

The only Vanilla dust particle is the redstone particle. However, you can easily create a custom colored one by passing Particle.DustOptions as data.

An example of creating a vertical line of green dust particles

for (double i = 0; i <= 1.0; i += 0.1) {
  someWorld.spawnParticle(
    Particle.DUST,
    someLocation.clone().add(0, i, 0),
    1,
    new Particle.DustOptions(Color.GREEN, 1.0f));
}

Dust transition particles work similarly to dust particles, but they transition their color from one to another. This can be achieved by passing Particle.DustTransition as data.

An example where 3 dust transition particles spawn on the x axis within a 1 block length:

someWorld.spawnParticle(
  Particle.DUST_COLOR_TRANSITION,
  someLocation,
  3
  0.5, 0, 0,
  new Particle.DustTransition(Color.RED, Color.BLUE, 1.0f));

The enchantment particles have two different behaviors based on the count argument:

• If set to a positive number, offset arguments are used normally,
• If set to 0, the offset arguments will be used for a fixed relative spawn location from the supplied location/coordinates. The particle will then travel from this relative location to the supplied location in a curve.

An example where an enchantment particle will spawn at someLocation.clone().add(2,0,2) and travel to someLocation:

someWorld.spawnParticle(Particle.ENCHANT, someLocation, 0, 2, 0, 2);