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. The extra argument will server as the vector’s multiplier, scaling it.

So for example if we set offsets to 2.5, 1.2, 0.4 and extra to 5, the final velocity vector would be (12.5, 6, 2).

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 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));

While having a similar name and sharing the texture, there is big difference between the two. EFFECT can not be colored, while ENTITY_EFFECT can be.

An example of spawning a group of colored entity effect particles:

someWorld.spawnParticle(Particle.ENTITY_EFFECT, 8, 1, 0.25, 1);

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 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);

To spawn particles that require BlockData, simply put BlockData as it’s data argument.

Example:

someWorld.spawnParticle(Particle.BLOCK_CRUMBLE, someLocation, 4, BlockType.GLOWSTONE.createBlockData());

To spawn particles that require an ItemStack, simply put an ItemStack as it’s data argument.

Example:

someWorld.spawnParticle(Particle.ITEM, someLocation, 4, ItemType.DIAMOND_PICKAXE.createItemStack());