Add a force option to the ParticleBuilder API (#1322)

Particle packets contain a boolean which marks the particle to either force or show normal to the receiver.
Spigot has been sending all particles with the force boolean which overrides client particle settings.

Related changes in this commit;
- Add a force option to the ParticleBuilder API, which defaults to true to keep spigot consistent with existing api.
- Add a new spawnParticle method to support this mode as a parameter. Of course kept existing api methods the same so as to not break them.

Let me know if changes are needed.

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

@@ -1,19 +1,20 @@
-From cd6e9ca316853d3c693c8e07db6595184b79742f Mon Sep 17 00:00:00 2001
+From ff3c644d6400800a4beba62ff9529f9f74a9282c 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.
+Adds an option to control the force mode of the particle.
 
 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 00000000..2bccc409
+index 00000000..f7aa162f
 --- /dev/null
 +++ b/src/main/java/com/destroystokyo/paper/ParticleBuilder.java
-@@ -0,0 +1,365 @@
+@@ -0,0 +1,378 @@
 +package com.destroystokyo.paper;
 +
 +import com.google.common.collect.Lists;
@@ -42,6 +43,7 @@ index 00000000..2bccc409
 +    private double offsetX = 0, offsetY = 0, offsetZ = 0;
 +    private double extra = 1;
 +    private Object data;
++    private boolean force = true;
 +
 +    public ParticleBuilder(Particle particle) {
 +        this.particle = particle;
@@ -57,7 +59,7 @@ index 00000000..2bccc409
 +        }
 +        location.getWorld().spawnParticle(particle, receivers, source,
 +            location.getX(), location.getY(), location.getZ(),
-+            count, offsetX, offsetY, offsetZ, extra, data
++            count, offsetX, offsetY, offsetZ, extra, data, force
 +        );
 +        return this;
 +    }
@@ -350,6 +352,18 @@ index 00000000..2bccc409
 +    }
 +
 +    /**
++     * 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;
++    }
++
++    /**
 +     * Sets the particle Color.
 +     * Only valid for REDSTONE, SPELL_MOB and SPELL_MOB_AMBIENT.
 +     */
@@ -398,15 +412,15 @@ index 9794c13e..cc9c2c5e 100644
 +    // Paper end
  }
 diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
-index 3b81f81e..e7973c73 100644
+index 3b81f81e..114e81dd 100644
 --- a/src/main/java/org/bukkit/World.java
 +++ b/src/main/java/org/bukkit/World.java
-@@ -1775,7 +1775,31 @@ public interface World extends PluginMessageRecipient, Metadatable {
+@@ -1775,7 +1775,57 @@ public interface World extends PluginMessageRecipient, Metadatable {
       *             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);
-+    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); }// Paper start - Expand Particle API
++    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
 +    /**
 +     * Spawns the particle (the number of times specified by count)
 +     * at the target location. The position of each particle will be
@@ -429,11 +443,37 @@ index 3b81f81e..e7973c73 100644
 +     *             the type of this depends on {@link Particle#getDataType()}
 +     * @param <T> Type
 +     */
-+    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);
++    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);
 +    // Paper end
++
  
      // Spigot start
      public class Spigot
 -- 
-2.17.1
+2.16.1.windows.1
 

Spigot-Server-Patches/0297-Expand-World.spawnParticle-API-and-add-Builder.patch

@@ -1,15 +1,16 @@
-From d1902f093f9e9e05aa983daa6f46cf1c06269faa Mon Sep 17 00:00:00 2001
+From ee7c23774b46b929e07932d07d5a70fd7c26c446 Mon Sep 17 00:00:00 2001
 From: Aikar <aikar@aikar.co>
 Date: Tue, 15 Aug 2017 22:29:12 -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.
+Adds an option to control the force mode of the particle.
 
 This adds a new Builder API which is much friendlier to use.
 
 diff --git a/src/main/java/net/minecraft/server/WorldServer.java b/src/main/java/net/minecraft/server/WorldServer.java
-index c06158e02..49019d54d 100644
+index c06158e0..49019d54 100644
 --- a/src/main/java/net/minecraft/server/WorldServer.java
 +++ b/src/main/java/net/minecraft/server/WorldServer.java
 @@ -1399,12 +1399,17 @@ public class WorldServer extends World implements IAsyncTaskHandler {
@@ -33,17 +34,17 @@ index c06158e02..49019d54d 100644
              BlockPosition blockposition = entityplayer.getChunkCoordinates();
              double d7 = blockposition.distanceSquared(d0, d1, d2);
 diff --git a/src/main/java/org/bukkit/craftbukkit/CraftWorld.java b/src/main/java/org/bukkit/craftbukkit/CraftWorld.java
-index 568a50ec4..36dd8ad60 100644
+index 568a50ec..ca8bda1c 100644
 --- a/src/main/java/org/bukkit/craftbukkit/CraftWorld.java
 +++ b/src/main/java/org/bukkit/craftbukkit/CraftWorld.java
-@@ -1568,13 +1568,16 @@ public class CraftWorld implements World {
+@@ -1568,15 +1568,18 @@ public class CraftWorld implements World {
          spawnParticle(particle, location.getX(), location.getY(), location.getZ(), count, offsetX, offsetY, offsetZ, extra, data);
      }
  
 +    // Paper start - Particle API Expansion
      @Override
 -    public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data) {
-+    public <T> void spawnParticle(Particle particle, List<Player> receivers, Player sender, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data) {
++    public <T> void spawnParticle(Particle particle, List<Player> receivers, Player sender, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force) {
 +        // Paper end
          if (data != null && !particle.getDataType().isInstance(data)) {
              throw new IllegalArgumentException("data should be " + particle.getDataType() + " got " + data.getClass());
@@ -53,8 +54,11 @@ index 568a50ec4..36dd8ad60 100644
 +                receivers == null ? getHandle().players : receivers.stream().map(player -> ((CraftPlayer) player).getHandle()).collect(java.util.stream.Collectors.toList()), // Paper -  Particle API Expansion
 +                sender != null ? ((CraftPlayer) sender).getHandle() : null, // Sender // Paper - Particle API Expansion
                  CraftParticle.toNMS(particle), // Particle
-                 true, // Extended range
+-                true, // Extended range
++                force , // Extended range // Paper - Particle API Expansion
                  x, y, z, // Position
+                 count,  // Count
+                 offsetX, offsetY, offsetZ, // Random offset
 -- 
-2.18.0
+2.16.1.windows.1