Creating Your First Particle Effect

The Particles API provides a powerful, stateful controller for managing complex, animated 3D particle effects. It utilizes a highly modular builder pattern, allowing you to easily snap together geometric shapes, mathematical animations, and different visual rendering methods.

Building a Basic Effect

To start off, you will need to create a Particles instance using Particles.builder(). At a minimum, you must define an origin, a shape, and a renderer.

public final class ParticleTest {
    
    public static void spawnBasicEffect(Player player) {
        Particles effect = Particles.builder()
            // The central anchor point
            .origin(player.getLocation())
            // A circle with a 2-block radius, made of 30 points
            .shape(Generators.circle(2.0, 30))
            // How to display it
            .render(new Renderers.Standard(Particle.HAPPY_VILLAGER, 1, 0.0, null))
            .build();

        // Starts the asynchronous calculation and rendering loop
        effect.start();
    }
}

[IMG?]

Dynamic Origins & Animations

You can make effects far more dynamic by passing a Supplier<Location> for the origin, which allows the effect to seamlessly follow a moving player or entity. We can also apply Transformers to animate the shape over time.

public final class ParticleTest {
    
    public static void spawnDynamicEffect(Player player) {
        Particles dynamicEffect = Particles.builder()
            // Origin dynamically updates to the player's current location every tick
            .origin(() -> player.getLocation().add(0, 1, 0))
            // Generate a 3D wireframe cube
            .shape(Generators.cube(2.0, 4))
            // Use the specialized DustRenderer to support custom RGB colors
            .render(new Renderers.DustRenderer(1.0f))
            .color(Color.AQUA)
            // Animate the cube by spinning it around the Y and X axes over 100 ticks
            .transform(Animations.spinY(360, 100, Easing.LINEAR))
            .transform(Animations.spinX(180, 100, Easing.LINEAR))
            // Render every 1 server tick
            .interval(1)
            // Automatically stop after 100 ticks (5 seconds)
            .duration(100)
            .build();

        dynamicEffect.start();
    }
}

[VIDEO?]

Builder Configuration Methods

The Particles.Builder contains a wide variety of methods to fine-tune exactly how your effect behaves, renders, and cleans itself up.

Method	Description
`origin(Location)`	Sets a static world location as the central anchor point for the effect.
`origin(Supplier<Location>)`	Sets a dynamic location supplier. Evaluated every tick, allowing the effect to track moving entities.
`shape(Generator)`	(Required) Sets the geometric shape logic (e.g., `Generators.circle()`).
`render(ParticleRenderer)`	(Required) Sets the implementation responsible for displaying the points in the world.
`transform(Transformer)`	Adds a custom spatial modifier to the pipeline (applied sequentially). Useful for complex mathematical animations.
`color(Color)`	Sets a static Bukkit `Color` for all particles. (Requires a renderer that supports color, like `DustRenderer`).
`color(ColorProvider)`	Sets a procedural color logic for dynamic, per-particle tinting and gradients.
`rotate(double x, double y, double z)`	Quickly adds a static rotation transformation (in radians) around the respective axes.
`scale(double s)`	Quickly adds a static scaling multiplier transformation to the coordinates.
`offset(double x, double y, double z)`	Quickly adds a static spatial offset transformation to the coordinates.
`interval(long ticks)`	Sets the delay in server ticks between each animation frame. Defaults to `1`.
`duration(long ticks)`	Sets the total lifetime of the effect in ticks. Set to `-1` for infinite duration. Defaults to `-1`.
`smooth(boolean)`	If true, calculates future frame motion vectors for smooth client-side interpolation (creates `MotionVector`s instead of `Pixel`s).
`viewers(List<Player>)`	Sets a static list of players who are allowed to see the effect.
`viewers(Supplier<List<Player>>)`	Sets a dynamic supplier for viewers, allowing players to phase in and out of seeing the effect based on conditions.
`stopIf(BooleanSupplier)`	A dynamic condition evaluated every tick. If it returns `true`, the effect is forcefully terminated.
`build()`	Validates the configuration and produces the final `Particles` instance. Throws an error if origin, shape, or render are missing.

05 June 2026