NO LONGER MAINTAINED. ANY VERSION AFTER 1.19.4 WILL NOT BE SUPPORTED! USE PAPER'S PARTICLEBUILDER

ParticleLib

A spigot library supporting all particles from 1.8 to 1.19.3

Support • Features • Download • Usage

Support

Join the Discord if you have any questions. Don't open an issue to ask for support.

Features

Multiversion support from 1.8 - 1.19.3 ^{(All in one Jar)}
Colored particles
Particles with custom velocities
Particles with textures
Support for every particle in minecraft
An easy and fluent API to easily spawn particles with custom data

Download

The latest version can be downloaded on the releases page.

Maven

<dependencies>
    <dependency>
        <groupId>xyz.xenondevs</groupId>
        <artifactId>particle</artifactId>
        <version>1.8.4</version>
    </dependency>
</dependencies>

Gradle

dependencies {
    implementation 'xyz.xenondevs:particle:1.8.4'
}

Note: ParticleLib is on the central repository, so no extra repositories are required.

Usage

For more advanced usage explanations check out the Wiki.

Simple

To spawn particles, you can either use the ParticleEffet#display method, or you can use the ParticleBuilder.
For normal particles without any extra data, the display method is the best choice.

Example:

ParticleEffect.FLAME.display(location);

This code will spawn a flame particle at the specified location.

Some particles can have extra data. This data can contain a range of different properties.
For these special cases, I will only use the ParticleBuilder. Display methods with the specific parameters still exist, but shouldn't be used to avoid confusion.

Directional

Some particles accept a custom velocity. When given a Vector they will travel to the specified offset. The velocity is stored in the offsetX, offsetY and offsetZ properties of the particle.

To see if a particle is Directional check if it has the DIRECTIONAL PropertyType.

Note: The particles Enchantment_Table and Nautilus will be displayed at the offset location and fly to the original location.

Example:

new ParticleBuilder(ParticleEffect.FLAME, player.getLocation())
        .setOffsetY(1f)
        .setSpeed(0.1f)
        .display();

This code will spawn a flame particle that flies to the player's head.

Minecraft's particles can behave quite weirdly, so you may have to tweak the speed parameter when using directional particles.

Colored

A few particles like Redstone can have custom colors applied to them. This color can be set with ParticleColor implementations:

RegularColor
NoteColor

If your plugin runs on a pre 1.13 server, you can also set the RGB values in the offset properties.

To see if a particle is colorable check if it has the COLORABLE PropertyType.

Note:

Since 1.13 Redstone particles are storing their color values in another property. Therefore, the offset properties can be properly used on servers above 1.13.
Note particles don't accept a custom color. Instead, they support a note value from 0 to 24. Use NoteColor for this particle.

Regular Example:

new ParticleBuilder(ParticleEffect.REDSTONE, location)
        .setParticleData(new RegularColor(255,255,0))
        .display()

This code will spawn a yellow Redstone particle at the specified location.

setParticleData(new RegularColor(255, 255, 0)) can also be replaced with setColor(Color.YELLOW) in case you want to use java.awt.Color instead.

Note Example:

new ParticleBuilder(ParticleEffect.NOTE, location)
        .setParticleData(new NoteColor(1))
        .display()

This code will spawn a green Note particle at the specified location.

Textured

Several particles even accept textures as custom properties! These textures are modified with implementations of the ParticleTexture class:

BlockTexture
ItemTexture

Warning: These particles NEED the texture property, or the particle won't be displayed.

To see if a particle supports custom textures check if it has the REQUIRES_BLOCK or the REQUIRES_ITEM PropertyType.

Block texture example:

new ParticleBuilder(ParticleEffect.FALLING_DUST, location)
        .setParticleData(new BlockTexture(Material.STONE))
        .display()

This code will spawn a Falling Dust particle with a stone texture.

Item texture example:

ItemStack item = new ItemStack(Material.DIAMOND_AXE);
new ParticleBuilder(ParticleEffect.ITEM_CRACK, location)
        .setParticleData(new ItemTexture(item))
        .display();

This code will spawn an Item Crack particle with a diamond axe texture.

sfclog/ParticleLib