Improves particles

Allows specifying separate particle trails for each player.
Removes random particles as a class option.
Adds a particle config builder for easier particle specification.

src/main/java/net/knarcraft/knarlib/particle/ParticleConfigBuilder.java

@@ -0,0 +1,148 @@
+package net.knarcraft.knarlib.particle;
+
+import org.bukkit.Particle;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A builder for creating particle configurations
+ *
+ * <p>The default behavior will spawn a single particle with no offset or extra data, and density 1.</p>
+ */
+@SuppressWarnings("unused")
+public class ParticleConfigBuilder {
+
+    private final Particle particleType;
+    private ParticleMode particleMode = ParticleMode.SINGLE;
+    private int particleAmount = 1;
+    private double particleDensity = 1;
+    private double heightOffset = 0;
+    private double offsetX = 0;
+    private double offsetY = 0;
+    private double offsetZ = 0;
+    private double extra = 0;
+
+    /**
+     * Instantiates a new particle config builder
+     *
+     * @param particleType <p>The type of particle to spawn</p>
+     */
+    public ParticleConfigBuilder(@NotNull Particle particleType) {
+        this.particleType = particleType;
+    }
+
+    /**
+     * Sets the mode to use when spawning the particles
+     *
+     * @param particleMode <p>The mode to use</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setMode(@NotNull ParticleMode particleMode) {
+        this.particleMode = particleMode;
+        return this;
+    }
+
+    /**
+     * Sets the amount of particles to spawn
+     *
+     * @param particleAmount <p>The number/amount of particles to spawn</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setAmount(int particleAmount) {
+        this.particleAmount = particleAmount;
+        return this;
+    }
+
+    /**
+     * Sets the density of the particles to spawn
+     *
+     * @param particleDensity <p>The new density</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setDensity(double particleDensity) {
+        this.particleDensity = particleDensity;
+        return this;
+    }
+
+    /**
+     * Sets the x,y,z offsets of the spawned particles
+     *
+     * <p>These values control the spread of the spawned particles</p>
+     *
+     * @param offsetX <p>The offset in the x-direction</p>
+     * @param offsetY <p>The offset in the y-direction</p>
+     * @param offsetZ <p>The offset in the z-direction</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setOffsets(double offsetX, double offsetY, double offsetZ) {
+        this.offsetX = offsetX;
+        this.offsetY = offsetY;
+        this.offsetZ = offsetZ;
+        return this;
+    }
+
+    /**
+     * Sets the x offset of the spawned particles
+     *
+     * @param offsetX <p>The offset in the x-direction</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setXOffset(double offsetX) {
+        this.offsetX = offsetX;
+        return this;
+    }
+
+    /**
+     * Sets the y offset of the spawned particles
+     *
+     * @param offsetY <p>The offset in the y-direction</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setYOffset(double offsetY) {
+        this.offsetY = offsetY;
+        return this;
+    }
+
+    /**
+     * Sets the z offset of the spawned particles
+     *
+     * @param offsetZ <p>The offset in the z-direction</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setZOffset(double offsetZ) {
+        this.offsetZ = offsetZ;
+        return this;
+    }
+
+    /**
+     * Sets the extra data for the spawned particles
+     *
+     * @param extra <p>The extra data to set</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setExtra(double extra) {
+        this.extra = extra;
+        return this;
+    }
+
+    /**
+     * Sets the height offset for the spawned particles
+     *
+     * @param heightOffset <p>The height offset to use</p>
+     * @return <p>This particle configuration builder</p>
+     */
+    public @NotNull ParticleConfigBuilder setHeightOffset(double heightOffset) {
+        this.heightOffset = heightOffset;
+        return this;
+    }
+
+    /**
+     * Builds the particle configuration
+     *
+     * @return <p>The built particle configuration</p>
+     */
+    public @NotNull ParticleConfig build() {
+        return new ParticleConfig(particleMode, particleType, particleAmount, particleDensity, heightOffset, offsetX,
+                offsetY, offsetZ, extra);
+    }
+
+}

src/main/java/net/knarcraft/knarlib/particle/ParticleTrailSpawner.java

@@ -7,6 +7,7 @@ import org.bukkit.Particle;
 import org.bukkit.World;
 import org.bukkit.entity.Player;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.HashMap;
 import java.util.HashSet;
@@ -26,20 +27,16 @@ public final class ParticleTrailSpawner implements Runnable {
     private final Map<UUID, Particle> playerParticles = new HashMap<>();
     private final Random random = new Random();
     private final Particle particle;
-    private final boolean randomTrailType;
     private final List<Particle> randomTrailTypes;
 
     /**
      * Instantiates a new particle trail spawner
      *
      * @param particle         <p>The type of particle used for the trail</p>
-     * @param randomTrailType  <p>Whether to use a random trail type each time a player is launched</p>
      * @param randomTrailTypes <p>The types of particles to use for random trails</p>
      */
-    public ParticleTrailSpawner(@NotNull Particle particle, boolean randomTrailType,
-                                @NotNull List<Particle> randomTrailTypes) {
+    public ParticleTrailSpawner(@NotNull Particle particle, @NotNull List<Particle> randomTrailTypes) {
         this.particle = particle;
-        this.randomTrailType = randomTrailType;
         this.randomTrailTypes = randomTrailTypes;
     }
 
@@ -54,6 +51,7 @@ public final class ParticleTrailSpawner implements Runnable {
                 continue;
             }
 
+            // Get the world and location to spawn the particle at
             Location playerLocation = player.getLocation();
             World playerWorld = playerLocation.getWorld();
             if (playerWorld == null) {
@@ -61,19 +59,13 @@ public final class ParticleTrailSpawner implements Runnable {
             }
 
             // Decide on which type of particle to spawn
-            Particle spawnParticle;
-            if (randomTrailType) {
-                spawnParticle = playerParticles.get(playerId);
-                if (spawnParticle == null) {
-                    spawnParticle = this.particle;
-                }
-            } else {
+            Particle spawnParticle = playerParticles.get(playerId);
+            if (spawnParticle == null) {
                 spawnParticle = this.particle;
             }
 
             // Spawn a trail particle
-            ParticleConfig particleConfig = new ParticleConfig(ParticleMode.SINGLE, spawnParticle,
-                    1, 1, 0, 0, 0, 0, 0);
+            ParticleConfig particleConfig = new ParticleConfigBuilder(spawnParticle).build();
             ParticleHelper.spawnParticle(playerWorld, playerLocation, particleConfig, 0);
         }
         playersWithTrails.removeAll(offlinePlayers);
@@ -91,21 +83,36 @@ public final class ParticleTrailSpawner implements Runnable {
     }
 
     /**
-     * Adds a trail behind the player with the given id
+     * Adds a random trail behind the player with the given id
      *
      * @param playerId <p>The id of the player to add the trail to</p>
      */
-    public void startTrail(@NotNull UUID playerId) {
+    public void startRandomTrail(@NotNull UUID playerId) {
         this.playerParticles.put(playerId, randomParticle());
         this.playersWithTrails.add(playerId);
     }
 
     /**
-     * Gets a random particle in the whitelist
+     * Adds a trail behind the player with the given id
      *
-     * @return <p>A random particle</p>
+     * @param playerId <p>The id of the player to add the trail to</p>
+     * @param particle <p>The particle to spawn, or null for the particle specified in the constructor</p>
+     */
+    public void startTrail(@NotNull UUID playerId, @Nullable Particle particle) {
+        this.playerParticles.put(playerId, particle);
+        this.playersWithTrails.add(playerId);
+    }
+
+    /**
+     * Gets a random particle from random the specified trail types
+     *
+     * @return <p>A random particle, or EGG_CRACK if no random trail types have been specified</p>
      */
     private @NotNull Particle randomParticle() {
+        if (this.randomTrailTypes.isEmpty()) {
+            return Particle.EGG_CRACK;
+        }
+
         Particle spawnParticle = null;
         while (spawnParticle == null || spawnParticle.getDataType() != Void.class) {
             spawnParticle = randomTrailTypes.get(random.nextInt(randomTrailTypes.size()));