Paper/patches/api/0100-Expand-World.spawnParticle-API-and-add-Builder.patch
Jake Potrebic 3fa4ea6668
Updated Upstream (Bukkit/CraftBukkit/Spigot)
Upstream has released updates that appear to apply and compile correctly.
This update has not been tested by PaperMC and as with ANY update, please do your own testing

Bukkit Changes:
6680169e [#660/Enum] Merge remote-tracking branch 'origin/pr/660' into experimental
8b97f215 Add missing AbstractTestingBase extension
9f21f42b [#660/Enum] Merge remote-tracking branch 'origin/pr/660' into experimental
fb59a4a0 Create experimental version
a7c1393b Merge branch 'master' into enums-to-registers
1af01165 Merge branch 'master' into enums-to-registers
4ee82e4e Implement feedback
af8ffd60 Merge branch 'master' into enums-to-registers
6a8ea63f Updated to 1.20
22ae9ebc Merge branch 'master' into enums-to-registers
b1d669be Some clean up
685d812e Merge branch 'master' into enums-to-registers
00d778c7 Convert MusicInstrument
bba2eb5f Convert GameEvent
ffbf67a1 Convert PotionType
eacaa45d Convert Particle
d08d21d1 Convert PatternType
c6b51f7c Convert Cat type
af6c2987 Make missing Frog variant abstract
a67a5f5c Add missing Annotation
6ab21c50 Change how converting from / to BlockType and ItemType work
e3e84e69 Add Objects.requireNonNull so that there are not marked as nullable
fceddab5 Add missing deprecation
e91906f5 Don't convert legacy in register instead, only in required method
2200b334 Use static constructors for ItemStack
b5f483b0 Deprecated Material
a995df2a Fix typo getItemTyp
9cedb664 import ItemType
27e282b2 getSteerItemType -> getSteerItem
d8d0e43b Better Piglin method names
3a2ab399 BLOCK_TYPE -> BLOCK, ITEM_TYPE -> ITEM
a0eb63ac Interface it is
4bb0b646 Split Material into BlockType and ItemType
b6bfcff5 Merge branch 'master' into enums-to-registers
1f86c847 Updated to Mockito 5.3.1
280ee1f7 Fix merge, updated to 1.19.4
9e0c7ad5 Merge branch 'master' into enums-to-registers
fdbed698 Updated to 1.19.3
85c3e2d3 Merge branch 'master' into enums-to-registers
b2c390af Fix merge
4e405647 Merge branch 'master' into enums-to-registers
d01b4c90 Fix copy/paste
ba2c8cb1 Update to 1.19
7e4f2db2 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
a1a974f0 Fix merge
7d3a91d3 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
499e22d9 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
a0cf419f Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
d5bd36a2 Fix / Implement merge changes
fe643952 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
cf1d2005 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
f18dce93 Make Statistic abstract
bbe3f791 Fix 1.18 merge Handle comment out test cases
0988647e Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
6e4f2c50 Populated BlockType and ItemType
7a58144d Convert Material enum, midpoint push, it compiles and runs
4771132c Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/bukkit into enums-to-registers
e6b179ff Convert Material enum, midpoint push to merge BlockState changes
f33b85a0 Change other enums / classes.
8b0d5418 Create seperat OldEnum class, which holds common enum methods.
45544426 Change Enums to classes to easier handle none standart minecraft values

CraftBukkit Changes:
8969b32d0 [#931/Enum] Merge remote-tracking branch 'origin/pr/931' into experimental
222257a67 Add missing AbstractTestingBase extension
0480af399 [#931/Enum] Merge remote-tracking branch 'origin/pr/931' into experimental
1afa1ddc2 Create experimental version
00780ea51 Ignore FactoryItemMaterialTest test
676969d01 SPIGOT-7389: Handle setting null items in ChiseledBookshelf Inventory
84f10cc36 Fix merge
9e114e13e Merge branch 'master' into enums-to-registers
941787e24 Add missing Commodore for 1.20 updated
6dac9a12d Updated tests
737426398 Only allow reference holder
aaaa5fa88 Merge branch 'master' into enums-to-registers
74957eb99 Merge branch 'master' into enums-to-registers
a1ca4e870 Merge branch 'master' into enums-to-registers
f293f4a61 Updated to 1.20
b434b3d15 Merge branch 'master' into enums-to-registers
e99dcbda7 Some clean up
fcead8aed Use correct primitive class
e955d9c50 Fix some Commodore errors
af5526ebb Allow Material to support older plugins
b83afd643 Add rewrite for Google enum set methods
067323765 Add missing method replacement in dynamic invocation
63e17e631 Merge branch 'master' into enums-to-registers
26dfcacf8 Bad copy and past
d50c9bd6a Convert MusicInstrument
c0c5312db Convert GameEvent
39daffe2c Convert PotionType
9b974f832 Convert Particle
f528fca63 Convert PatternType
525c65006 Convert Cat type
6832b8fbb More consistent to / from bukkit / minecraft methods
d31e38e16 Make missing Frog variant abstract
e4f0e7d8e This shouldn't be committed
6fee81baa Add Commodore for EnumSet
82a668683 Fix hasItemType / getItemType
f70162d66 Change how converting from / to BlockType and ItemType work
c3f7c7886 Don't convert legacy in register instead, only in required method
2039e05fa Use static constructors for ItemStack
fe221578b More Commodore
2b70bd171 More Commodore
70f4a89f5 Fix some Commodore
06544ed4b Fix typo getItemTyp
6269d2e42 getSteerItemType -> getSteerItem
a19ac46c0 Better Piglin method names
eef5f52c6 BLOCK_TYPE -> BLOCK, ITEM_TYPE -> ITEM
bbaff1348 Interface it is
c39e1316c Finish Commodore action for Material split
dd8552105 Work on Commodore
1d4ef8bf2 Split Material into BlockType and ItemType
6c5a98220 Merge branch 'master' into enums-to-registers
869658a96 Handle Material calls in lambda expression
523ac4ac0 Add reroute for Class#getEnumConstants
0a4463279 Use extra method for getting registry
602d9b404 Updated to Mockito 5.3.1
8ff87b77d Fix merge, updated to 1.19.4
9d739d313 Merge branch 'master' into enums-to-registers
eb6f702ff Reduce usage of BuiltInRegistries
b6f667cac Some more asm compatibility changes, add config option
87c931d38 Handle enum maps
a2c6699db Updated to 1.19.3
f7c27584f Merge branch 'master' into enums-to-registers
2f95b9951 Fix merge
184b05740 Merge branch 'master' into enums-to-registers
12bd8de26 Updated to 1.19
9c57831b7 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
4ed8eb402 Fix merge
a9faac8e4 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
0d2988603 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
3f8f9557d Fix merge, updated to 1.18.2
1560490c6 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
a0e4eb12c Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
8b59f682d Move getType method to CraftEntity class
b849c0147 Add missing patches
4644ba79f Fix / Implement merge changes
cf9ee732e Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
0c9125b67 Use Tag where possible
cc05153d9 Cache interactable call
ab5cc36de Use getHandle
83ebf4114 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
bc20aea0c Make Statistic abstract
3faa7e135 Add Tests for Material BlockType and ItemType
e10f74365 Fix 1.18 merge Handle comment out test cases
f72f70ec4 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
dbf4f5b7e Populated BlockType and ItemType
015afc1bc Convert Material enum, midpoint push, it compiles and runs
cc0112866 Merge branch 'master' of https://hub.spigotmc.org/stash/scm/~derfrzocker/craftbukkit into enums-to-registers
e26742c59 Convert Material enum, midpoint push to merge BlockState changes
796ad9295 Fix bug in legacy naming converting.
199c8278c Change other enums / classes.
fd513652a Seperated custom biome value handling. Fix compareTo call.
60c71ce07 Change Enums to classes to easier handle none standart minecraft values

Spigot Changes:
addcf45f [Enum] Rebuild patches
2023-06-20 09:50:05 -07:00

592 lines
21 KiB
Diff

From 0000000000000000000000000000000000000000 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 0000000000000000000000000000000000000000..f710167633a8ef1abc4aac2a1912514a959d414c
--- /dev/null
+++ b/src/main/java/com/destroystokyo/paper/ParticleBuilder.java
@@ -0,0 +1,485 @@
+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;
+ }
+
+ /**
+ * @return whether the particle is forcefully shown to players.
+ */
+ public boolean force() {
+ return force;
+ }
+
+ /**
+ * 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 (this.particle != Particle.DUST && 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 (this.data instanceof Particle.DustOptions) {
+ return data(null);
+ } else {
+ return this;
+ }
+ }
+
+ return this.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 0f97cf9fd3aebbcda1531f2cfbb9e2e17ba14acf..31c2706e0f038c180821e7c4e543f1177789ce3d 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -140,6 +140,17 @@ public abstract class Particle<D> extends OldEnum<Particle<D>> implements Keyed
@NotNull
public abstract Class<D> getDataType();
+ // 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 48e3e92820f59753df30e5d61f57fb71e2894aa6..61f5fd47381d21b268f58af2106fc8be5e2f1c73 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -2756,7 +2756,62 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
* @param data the data to use for the particle or null,
* the type of this depends on {@link Particle#getDataType()}
*/
- public <T> void spawnParticle(@NotNull Particle<T> particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data);
+ // Paper start - Expand Particle API
+ default <T> void spawnParticle(@NotNull Particle<T> particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data) {
+ this.spawnParticle(particle, null, null, 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
+ */
+ default <T> void spawnParticle(@NotNull Particle<T> 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) {
+ this.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
+ */
+ <T> void spawnParticle(@NotNull Particle<T> 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)