2018-08-14 05:42:31 +00:00
From ff3c644d6400800a4beba62ff9529f9f74a9282c Mon Sep 17 00:00:00 2001
2018-05-01 00:32:15 +00:00
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.
2018-08-14 05:42:31 +00:00
Adds an option to control the force mode of the particle.
2018-05-01 00:32:15 +00:00
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
2018-08-14 05:42:31 +00:00
index 00000000..f7aa162f
2018-05-01 00:32:15 +00:00
--- /dev/null
+++ b/src/main/java/com/destroystokyo/paper/ParticleBuilder.java
2018-08-14 05:42:31 +00:00
@@ -0,0 +1,378 @@
2018-05-01 00:32:15 +00:00
+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;
2018-06-07 00:59:04 +00:00
+import org.bukkit.util.NumberConversions;
2018-05-01 00:32:15 +00:00
+
+import javax.annotation.Nullable;
2018-06-07 00:59:04 +00:00
+import java.util.Collection;
2018-05-01 00:32:15 +00:00
+import java.util.List;
+
+/**
+ * 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;
2018-08-14 05:42:31 +00:00
+ private boolean force = true;
2018-05-01 00:32:15 +00:00
+
+ public ParticleBuilder(Particle particle) {
+ this.particle = particle;
+ }
+
+ /**
+ * Sends the particle to all receiving players (or all).
+ * This method is safe to use Asynchronously
+ */
+ 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(),
2018-08-14 05:42:31 +00:00
+ count, offsetX, offsetY, offsetZ, extra, data, force
2018-05-01 00:32:15 +00:00
+ );
+ return this;
+ }
+
+ /**
+ * @return The particle going to be sent
+ */
+ public Particle particle() {
+ return particle;
+ }
+
+ /**
+ * Changes what particle will be sent
+ * @param particle The particle
+ */
+ public ParticleBuilder particle(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;
+ }
+
+ /**
2018-06-07 01:27:50 +00:00
+ * Example use:
+ *
+ * builder.receivers(16);
+ * if (builder.hasReceivers()) {
+ * sendParticleAsync(builder);
+ * }
+ * @return If this particle is going to be sent to someone
+ */
+ public boolean hasReceivers() {
2018-06-07 01:45:30 +00:00
+ return (receivers == null && !location.getWorld().getPlayers().isEmpty()) || (receivers != null && !receivers.isEmpty());
2018-06-07 01:27:50 +00:00
+ }
+
+ /**
2018-06-07 01:45:30 +00:00
+ * 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.
2018-05-01 00:32:15 +00:00
+ */
+ public ParticleBuilder allPlayers() {
+ this.receivers = null;
+ return this;
+ }
+
+ /**
2018-06-07 01:27:50 +00:00
+ * @param receivers List of players to receive this particle, or null for all players in the world
2018-05-01 00:32:15 +00:00
+ */
+ public ParticleBuilder receivers(@Nullable List<Player> receivers) {
2018-06-07 00:59:04 +00:00
+ // 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?
2018-06-07 01:27:50 +00:00
+ this.receivers = receivers != null ? Lists.newArrayList(receivers) : null;
+ return this;
2018-06-07 00:59:04 +00:00
+ }
+
+ /**
2018-06-07 01:27:50 +00:00
+ * @param receivers List of players to receive this particle, or null for all players in the world
2018-06-07 00:59:04 +00:00
+ */
+ public ParticleBuilder receivers(@Nullable Collection<Player> receivers) {
2018-05-01 00:32:15 +00:00
+ this.receivers = receivers != null ? Lists.newArrayList(receivers) : null;
+ return this;
+ }
+
+ /**
2018-06-07 01:27:50 +00:00
+ * @param receivers List of players to be receive this particle, or null for all players in the world
2018-05-01 00:32:15 +00:00
+ */
+ public ParticleBuilder receivers(Player... receivers) {
2018-06-07 01:27:50 +00:00
+ this.receivers = receivers != null ? Lists.newArrayList(receivers) : null;
2018-05-01 00:32:15 +00:00
+ return this;
+ }
+
+ /**
2018-06-07 00:59:04 +00:00
+ * 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
+ */
+ 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
+ */
+ 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
+ */
+ 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
+ */
+ 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
+ */
+ 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));
+ }
+
+ /**
2018-05-01 00:32:15 +00:00
+ * @return The player considered the source of this particle (for Visibility concerns), or null
+ */
+ 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
+ */
+ public ParticleBuilder source(Player source) {
+ this.source = source;
+ return this;
+ }
+
+ /**
+ * @return Location of where the particle will spawn
+ */
+ public Location location() {
+ return location;
+ }
+
+ /**
+ * Sets the location of where to spawn the particle
+ * @param location The location of the particle
+ */
+ public ParticleBuilder location(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
+ */
+ public ParticleBuilder location(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
+ */
+ public ParticleBuilder count(int count) {
+ this.count = count;
+ return this;
+ }
+
+ /**
+ * Particle offset X. Varies by particle on how this is used
+ */
+ public double offsetX() {
+ return offsetX;
+ }
+ /**
+ * Particle offset Y. Varies by particle on how this is used
+ */
+ public double offsetY() {
+ return offsetY;
+ }
+ /**
+ * Particle offset Z. Varies by particle on how this is used
+ */
+ public double offsetZ() {
+ return offsetZ;
+ }
+
+ /**
+ * Sets the particle offset. Varies by particle on how this is used
+ */
+ 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
+ */
+ public double extra() {
+ return extra;
+ }
+
+ /**
+ * Sets the particle extra data. Varies by particle on how this is used
+ */
+ public ParticleBuilder extra(double extra) {
+ this.extra = extra;
+ return this;
+ }
+
+ /**
+ * Gets the particle custom data. Varies by particle on how this is used
+ */
+ public <T> T data() {
+ //noinspection unchecked
+ return (T) data;
+ }
+
+ /**
+ * Sets the particle custom data. Varies by particle on how this is used
+ */
+ public <T> ParticleBuilder data(T data) {
+ this.data = data;
+ return this;
+ }
+
+ /**
2018-08-14 05:42:31 +00:00
+ * 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
+ */
+ public ParticleBuilder force(boolean force) {
+ this.force = force;
+ return this;
+ }
+
+ /**
2018-05-01 00:32:15 +00:00
+ * Sets the particle Color.
+ * Only valid for REDSTONE, SPELL_MOB and SPELL_MOB_AMBIENT.
+ */
+ public ParticleBuilder color(Color color) {
+ return color(color.getRed(), color.getGreen(), color.getBlue());
+ }
+
+ /**
+ * Sets the particle Color.
+ * Only valid for REDSTONE, SPELL_MOB and SPELL_MOB_AMBIENT.
+ */
+ public ParticleBuilder color(int r, int g, int b) {
+ if (particle != Particle.REDSTONE && particle != Particle.SPELL_MOB && particle != Particle.SPELL_MOB_AMBIENT) {
+ throw new IllegalStateException("Color may only be set on REDSTONE, SPELL_MOB, or SPELL_MOB_AMBIENT");
+ }
+ offsetX = convertColorValue(r);
+ offsetY = convertColorValue(g);
+ offsetZ = convertColorValue(b);
+ return this;
+ }
+
+ private static double convertColorValue(double value) {
+ if (value <= 0.0D) {
+ value = -1.0D;
+ }
+
+ return value / 255.0D;
+ }
+}
diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
index 9794c13e..cc9c2c5e 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -71,4 +71,13 @@ public enum Particle {
public Class<?> getDataType() {
return dataType;
}
+
+ // Paper start - Particle API expansion
+ /**
+ * Creates a {@link com.destroystokyo.paper.ParticleBuilder}
+ */
+ public com.destroystokyo.paper.ParticleBuilder builder() {
+ return new com.destroystokyo.paper.ParticleBuilder(this);
+ }
+ // Paper end
}
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
2018-08-14 05:42:31 +00:00
index 3b81f81e..114e81dd 100644
2018-05-01 00:32:15 +00:00
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
2018-08-14 05:42:31 +00:00
@@ -1775,7 +1775,57 @@ public interface World extends PluginMessageRecipient, Metadatable {
2018-05-01 00:32:15 +00:00
* the type of this depends on {@link Particle#getDataType()}
* @param <T> Type
*/
- public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
2018-08-14 05:42:31 +00:00
+ public default <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data) { spawnParticle(particle, null, null, x, y, z, count, offsetX, offsetY, offsetZ, extra, data, true); }// Paper start - Expand Particle API
2018-05-01 00:32:15 +00:00
+ /**
+ * 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
+ */
2018-08-14 05:42:31 +00:00
+ public default <T> void spawnParticle(Particle particle, List<Player> receivers, Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, 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(Particle particle, List<Player> receivers, Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force);
2018-05-01 00:32:15 +00:00
+ // Paper end
2018-08-14 05:42:31 +00:00
+
2018-05-01 00:32:15 +00:00
// Spigot start
public class Spigot
--
2018-08-14 05:42:31 +00:00
2.16.1.windows.1
2018-05-01 00:32:15 +00:00
