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 (gold) entity effect particles:

someWorld.spawnParticle(Particle.ENTITY_EFFECT, 8, 1, 0.25, 1, Color.fromRGB(255, 215, 0));

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 TINTED_LEAVES particle is really simple to spawn, as it only requires a Color object to be passed as the data argument.

Example of spawning 10 orange leaves in a 4x4 area:

someWorld.spawnParticle(Particle.TINTED_LEAVES, someLocation, 10, 2, 0, 2, Color.fromRGB(191, 87, 0));

As the name implies, this type of particle converges to a single point (location), which in this case is the supplied location.

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

The SCULK_CHARGE particle takes a Float as it’s data. This is used as the particle’s “roll” or more formally, the angle the particle displays at in radians.

Example of spawning a sculk charge particle at 45°.

someWorld.spawnParticle(Particle.SCULK_CHARGE, 1, Float.valueOf(0.7853f));

The SHRIEK particle takes an Integer as it’s data. This is used to set the delay in ticks before the particle spawns.

It is completely up to your implementation when choosing to use data or a scheduler.

Example where a shriek particle will spawn after one second:

someWorld.spawnParticle(Particle.SHRIEK, 1, Integer.valueOf(20));

Vibration particles require you to pass a Vibration object as data, where you can choose between a location (Vibration.Destination.BlockDestination) or an entity target (Vibration.Destination.EntityDestination).

someWorld.spawnParticle(
  Particle.VIBRATION,
  someLocation,
  1,
  new Vibration(new Vibration.Destination.BlockDestination(otherLocation), 10));

Trail particles require you to pass a Particle.Trail object as data.

An example where 8 randomly offset trail particles move towards someLocation, which is in the center of the spawning bounding box in 10 ticks.

someWorld.spawnParticle(
  Particle.TRAIL,
  someLocation,
  8,
  2, 2, 2,
  new Particle.Trail(someLocation, Color.RED, 10)
);