Paper/Spigot-API-Patches/0097-Expand-World.spawnParticle-API-and-add-Builder.patch

From 77befc8808bf1a216fdae6060f9a19d5f0b36df0 Mon Sep 17 00:00:00 2001
From: Aikar <aikar@aikar.co>
Date: Tue, 29 Aug 2017 23:58:48 -0400
Subject: [PATCH] Expand World.spawnParticle API and add Builder

Adds ability to control who receives it and who is the source/sender (vanish API)
the standard API is to send the packet to everyone in the world, which is ineffecient.

This adds a new Builder API which is much friendlier to use.

diff --git a/src/main/java/com/destroystokyo/paper/ParticleBuilder.java b/src/main/java/com/destroystokyo/paper/ParticleBuilder.java
new file mode 100644
index 000000000..06f1602f5
--- /dev/null
+++ b/src/main/java/com/destroystokyo/paper/ParticleBuilder.java
@@ -0,0 +1,478 @@
+package com.destroystokyo.paper;
+
+import com.google.common.collect.Lists;
+import org.bukkit.Color;
+import org.bukkit.Location;
+import org.bukkit.Particle;
+import org.bukkit.World;
+import org.bukkit.entity.Player;
+import org.bukkit.util.NumberConversions;
+
+import java.util.Collection;
+import java.util.List;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Helps prepare a particle to be sent to players.
+ *
+ * Usage of the builder is preferred over the super long {@link World#spawnParticle(Particle, Location, int, double, double, double, double, Object)} API
+ */
+public class ParticleBuilder {
+
+    private Particle particle;
+    private List<Player> receivers;
+    private Player source;
+    private Location location;
+    private int count = 1;
+    private double offsetX = 0, offsetY = 0, offsetZ = 0;
+    private double extra = 1;
+    private Object data;
+    private boolean force = true;
+
+    public ParticleBuilder(@NotNull Particle particle) {
+        this.particle = particle;
+    }
+
+    /**
+     * Sends the particle to all receiving players (or all). This method is safe to use
+     * Asynchronously
+     *
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder spawn() {
+        if (this.location == null) {
+            throw new IllegalStateException("Please specify location for this particle");
+        }
+        location.getWorld().spawnParticle(particle, receivers, source,
+            location.getX(), location.getY(), location.getZ(),
+            count, offsetX, offsetY, offsetZ, extra, data, force
+        );
+        return this;
+    }
+
+    /**
+     * @return The particle going to be sent
+     */
+    @NotNull
+    public Particle particle() {
+        return particle;
+    }
+
+    /**
+     * Changes what particle will be sent
+     *
+     * @param particle The particle
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder particle(@NotNull Particle particle) {
+        this.particle = particle;
+        return this;
+    }
+
+    /**
+     * @return List of players who will receive the particle, or null for all in world
+     */
+    @Nullable
+    public List<Player> receivers() {
+        return receivers;
+    }
+
+    /**
+     * Example use:
+     *
+     * builder.receivers(16); if (builder.hasReceivers()) { sendParticleAsync(builder); }
+     *
+     * @return If this particle is going to be sent to someone
+     */
+    public boolean hasReceivers() {
+        return (receivers == null && !location.getWorld().getPlayers().isEmpty()) || (
+            receivers != null && !receivers.isEmpty());
+    }
+
+    /**
+     * Sends this particle to all players in the world. This is rather silly and you should likely not
+     * be doing this.
+     *
+     * Just be a logical person and use receivers by radius or collection.
+     *
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder allPlayers() {
+        this.receivers = null;
+        return this;
+    }
+
+    /**
+     * @param receivers List of players to receive this particle, or null for all players in the
+     * world
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(@Nullable List<Player> receivers) {
+        // Had to keep this as we first made API List<> and not Collection, but removing this may break plugins compiled on older jars
+        // TODO: deprecate?
+        this.receivers = receivers != null ? Lists.newArrayList(receivers) : null;
+        return this;
+    }
+
+    /**
+     * @param receivers List of players to receive this particle, or null for all players in the
+     * world
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(@Nullable Collection<Player> receivers) {
+        this.receivers = receivers != null ? Lists.newArrayList(receivers) : null;
+        return this;
+    }
+
+    /**
+     * @param receivers List of players to be receive this particle, or null for all players in the
+     * world
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(@Nullable Player... receivers) {
+        this.receivers = receivers != null ? Lists.newArrayList(receivers) : null;
+        return this;
+    }
+
+    /**
+     * Selects all players within a cuboid selection around the particle location, within the
+     * specified bounding box. If you want a more spherical check, see {@link #receivers(int,
+     * boolean)}
+     *
+     * @param radius amount to add on all axis
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(int radius) {
+        return receivers(radius, radius);
+    }
+
+    /**
+     * Selects all players within the specified radius around the particle location. If byDistance is
+     * false, behavior uses cuboid selection the same as {@link #receivers(int, int)} If byDistance is
+     * true, radius is tested by distance in a spherical shape
+     *
+     * @param radius amount to add on each axis
+     * @param byDistance true to use a spherical radius, false to use a cuboid
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(int radius, boolean byDistance) {
+        if (!byDistance) {
+            return receivers(radius, radius, radius);
+        } else {
+            this.receivers = Lists.newArrayList();
+            for (Player nearbyPlayer : location.getWorld()
+                .getNearbyPlayers(location, radius, radius, radius)) {
+                Location loc = nearbyPlayer.getLocation();
+                double x = NumberConversions.square(location.getX() - loc.getX());
+                double y = NumberConversions.square(location.getY() - loc.getY());
+                double z = NumberConversions.square(location.getZ() - loc.getZ());
+                if (Math.sqrt(x + y + z) > radius) {
+                    continue;
+                }
+                this.receivers.add(nearbyPlayer);
+            }
+            return this;
+        }
+    }
+
+    /**
+     * Selects all players within a cuboid selection around the particle location, within the
+     * specified bounding box. Allows specifying a different Y size than X and Z If you want a more
+     * cylinder check, see {@link #receivers(int, int, boolean)} If you want a more spherical check,
+     * see {@link #receivers(int, boolean)}
+     *
+     * @param xzRadius amount to add on the x/z axis
+     * @param yRadius amount to add on the y axis
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(int xzRadius, int yRadius) {
+        return receivers(xzRadius, yRadius, xzRadius);
+    }
+
+    /**
+     * Selects all players within the specified radius around the particle location. If byDistance is
+     * false, behavior uses cuboid selection the same as {@link #receivers(int, int)} If byDistance is
+     * true, radius is tested by distance on the y plane and on the x/z plane, in a cylinder shape.
+     *
+     * @param xzRadius amount to add on the x/z axis
+     * @param yRadius amount to add on the y axis
+     * @param byDistance true to use a cylinder shape, false to use cuboid
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(int xzRadius, int yRadius, boolean byDistance) {
+        if (!byDistance) {
+            return receivers(xzRadius, yRadius, xzRadius);
+        } else {
+            this.receivers = Lists.newArrayList();
+            for (Player nearbyPlayer : location.getWorld()
+                .getNearbyPlayers(location, xzRadius, yRadius, xzRadius)) {
+                Location loc = nearbyPlayer.getLocation();
+                if (Math.abs(loc.getY() - this.location.getY()) > yRadius) {
+                    continue;
+                }
+                double x = NumberConversions.square(location.getX() - loc.getX());
+                double z = NumberConversions.square(location.getZ() - loc.getZ());
+                if (x + z > NumberConversions.square(xzRadius)) {
+                    continue;
+                }
+                this.receivers.add(nearbyPlayer);
+            }
+            return this;
+        }
+    }
+
+    /**
+     * Selects all players within a cuboid selection around the particle location, within the
+     * specified bounding box. If you want a more cylinder check, see {@link #receivers(int, int,
+     * boolean)} If you want a more spherical check, see {@link #receivers(int, boolean)}
+     *
+     * @param xRadius amount to add on the x axis
+     * @param yRadius amount to add on the y axis
+     * @param zRadius amount to add on the z axis
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder receivers(int xRadius, int yRadius, int zRadius) {
+        if (location == null) {
+            throw new IllegalStateException("Please set location first");
+        }
+        return receivers(location.getWorld().getNearbyPlayers(location, xRadius, yRadius, zRadius));
+    }
+
+    /**
+     * @return The player considered the source of this particle (for Visibility concerns), or null
+     */
+    @Nullable
+    public Player source() {
+        return source;
+    }
+
+    /**
+     * Sets the source of this particle for visibility concerns (Vanish API)
+     *
+     * @param source The player who is considered the source
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder source(@Nullable Player source) {
+        this.source = source;
+        return this;
+    }
+
+    /**
+     * @return Location of where the particle will spawn
+     */
+    @Nullable
+    public Location location() {
+        return location;
+    }
+
+    /**
+     * Sets the location of where to spawn the particle
+     *
+     * @param location The location of the particle
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder location(@NotNull Location location) {
+        this.location = location.clone();
+        return this;
+    }
+
+    /**
+     * Sets the location of where to spawn the particle
+     *
+     * @param world World to spawn particle in
+     * @param x X location
+     * @param y Y location
+     * @param z Z location
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder location(@NotNull World world, double x, double y, double z) {
+        this.location = new Location(world, x, y, z);
+        return this;
+    }
+
+    /**
+     * @return Number of particles to spawn
+     */
+    public int count() {
+        return count;
+    }
+
+    /**
+     * Sets the number of particles to spawn
+     *
+     * @param count Number of particles
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder count(int count) {
+        this.count = count;
+        return this;
+    }
+
+    /**
+     * Particle offset X. Varies by particle on how this is used
+     *
+     * @return Particle offset X.
+     */
+    public double offsetX() {
+        return offsetX;
+    }
+
+    /**
+     * Particle offset Y. Varies by particle on how this is used
+     *
+     * @return Particle offset Y.
+     */
+    public double offsetY() {
+        return offsetY;
+    }
+
+    /**
+     * Particle offset Z. Varies by particle on how this is used
+     *
+     * @return Particle offset Z.
+     */
+    public double offsetZ() {
+        return offsetZ;
+    }
+
+    /**
+     * Sets the particle offset. Varies by particle on how this is used
+     *
+     * @param offsetX Particle offset X
+     * @param offsetY Particle offset Y
+     * @param offsetZ Particle offset Z
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder offset(double offsetX, double offsetY, double offsetZ) {
+        this.offsetX = offsetX;
+        this.offsetY = offsetY;
+        this.offsetZ = offsetZ;
+        return this;
+    }
+
+    /**
+     * Gets the Particle extra data. Varies by particle on how this is used
+     *
+     * @return the extra particle data
+     */
+    public double extra() {
+        return extra;
+    }
+
+    /**
+     * Sets the particle extra data. Varies by particle on how this is used
+     *
+     * @param extra the extra particle data
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder extra(double extra) {
+        this.extra = extra;
+        return this;
+    }
+
+    /**
+     * Gets the particle custom data. Varies by particle on how this is used
+     *
+     * @param <T> The Particle data type
+     * @return the ParticleData for this particle
+     */
+    @Nullable
+    public <T> T data() {
+        //noinspection unchecked
+        return (T) data;
+    }
+
+    /**
+     * Sets the particle custom data. Varies by particle on how this is used
+     *
+     * @param data The new particle data
+     * @param <T> The Particle data type
+     * @return a reference to this object.
+     */
+    @NotNull
+    public <T> ParticleBuilder data(@Nullable T data) {
+        this.data = data;
+        return this;
+    }
+
+    /**
+     * Sets whether the particle is forcefully shown to the player. If forced, the particle will show
+     * faraway, as far as the player's view distance allows. If false, the particle will show
+     * according to the client's particle settings.
+     *
+     * @param force true to force, false for normal
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder force(boolean force) {
+        this.force = force;
+        return this;
+    }
+
+    /**
+     * Sets the particle Color. Only valid for REDSTONE.
+     *
+     * @param color the new particle color
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder color(@Nullable Color color) {
+        return color(color, 1);
+    }
+
+    /**
+     * Sets the particle Color and size. Only valid for REDSTONE.
+     *
+     * @param color the new particle color
+     * @param size the size of the particle
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder color(@Nullable Color color, float size) {
+        if (particle != Particle.REDSTONE && color != null) {
+            throw new IllegalStateException("Color may only be set on REDSTONE");
+        }
+
+        // We don't officially support reusing these objects, but here we go
+        if (color == null) {
+            if (data instanceof Particle.DustOptions) {
+                return data(null);
+            } else {
+                return this;
+            }
+        }
+
+        return data(new Particle.DustOptions(color, size));
+    }
+
+    /**
+     * Sets the particle Color.
+     * Only valid for REDSTONE.
+     * @param r red color component
+     * @param g green color component
+     * @param b blue color component
+     * @return a reference to this object.
+     */
+    @NotNull
+    public ParticleBuilder color(int r, int g, int b) {
+        return color(Color.fromRGB(r, g, b));
+    }
+}
diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
index 49467ac70..d2ceb07c7 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -96,6 +96,17 @@ public enum Particle {
         return dataType;
     }
 
+    // Paper start - Particle API expansion
+    /**
+     * Creates a {@link com.destroystokyo.paper.ParticleBuilder}
+     *
+     * @return a {@link com.destroystokyo.paper.ParticleBuilder} for the particle
+     */
+    @NotNull
+    public com.destroystokyo.paper.ParticleBuilder builder() {
+        return new com.destroystokyo.paper.ParticleBuilder(this);
+    }
+    // Paper end
     /**
      * Options which can be applied to redstone dust particles - a particle
      * color and size.
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index fbe7e76c0..085c7a42c 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -2433,7 +2433,57 @@ public interface World extends PluginMessageRecipient, Metadatable {
      *             the type of this depends on {@link Particle#getDataType()}
      * @param <T> Type
      */
-    public <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data);
+    public default <T> void spawnParticle(@NotNull Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data) { spawnParticle(particle, null, null, x, y, z, count, offsetX, offsetY, offsetZ, extra, data, true); }// Paper start - Expand Particle API
+    /**
+     * Spawns the particle (the number of times specified by count)
+     * at the target location. The position of each particle will be
+     * randomized positively and negatively by the offset parameters
+     * on each axis.
+     *
+     * @param particle the particle to spawn
+     * @param receivers List of players to receive the particles, or null for all in world
+     * @param source Source of the particles to be used in visibility checks, or null if no player source
+     * @param x the position on the x axis to spawn at
+     * @param y the position on the y axis to spawn at
+     * @param z the position on the z axis to spawn at
+     * @param count the number of particles
+     * @param offsetX the maximum random offset on the X axis
+     * @param offsetY the maximum random offset on the Y axis
+     * @param offsetZ the maximum random offset on the Z axis
+     * @param extra the extra data for this particle, depends on the
+     *              particle used (normally speed)
+     * @param data the data to use for the particle or null,
+     *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
+     */
+    public default <T> void spawnParticle(@NotNull Particle particle, @Nullable List<Player> receivers, @NotNull Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data) { spawnParticle(particle, receivers, source, x, y, z, count, offsetX, offsetY, offsetZ, extra, data, true); }
+    /**
+     * Spawns the particle (the number of times specified by count)
+     * at the target location. The position of each particle will be
+     * randomized positively and negatively by the offset parameters
+     * on each axis.
+     *
+     * @param particle the particle to spawn
+     * @param receivers List of players to receive the particles, or null for all in world
+     * @param source Source of the particles to be used in visibility checks, or null if no player source
+     * @param x the position on the x axis to spawn at
+     * @param y the position on the y axis to spawn at
+     * @param z the position on the z axis to spawn at
+     * @param count the number of particles
+     * @param offsetX the maximum random offset on the X axis
+     * @param offsetY the maximum random offset on the Y axis
+     * @param offsetZ the maximum random offset on the Z axis
+     * @param extra the extra data for this particle, depends on the
+     *              particle used (normally speed)
+     * @param data the data to use for the particle or null,
+     *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
+     * @param force allows the particle to be seen further away from the player
+     *              and shows to players using any vanilla client particle settings
+     */
+    public <T> void spawnParticle(@NotNull Particle particle, @Nullable List<Player> receivers, @Nullable Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data, boolean force);
+    // Paper end
+
 
     /**
      * Spawns the particle (the number of times specified by count)
-- 
2.25.1