ParticleLib

A spigot library supporting all particles from 1.8 to 1.17.1



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.17.1 ^{(All in one Jar)}
• Colored particles
• Moving particles with 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.6.4</version>
    </dependency>
</dependencies>

Gradle

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

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

Usage

For more advanced usage explanations check out the Wiki or the Javadoc.

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.