1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-12-23 15:00:30 +01:00
PaperMC/patches/api/0098-Expand-World.spawnParticle-API-and-add-Builder.patch

685 lines
27 KiB
Diff
Raw Normal View History

2021-06-11 14:02:28 +02:00
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..6c405755f4507d6fbc6c3877c611a7191206f3ff
2021-06-11 14:02:28 +02:00
--- /dev/null
+++ b/src/main/java/com/destroystokyo/paper/ParticleBuilder.java
@@ -0,0 +1,582 @@
2021-06-11 14:02:28 +02:00
+package com.destroystokyo.paper;
+
+import com.google.common.base.Preconditions;
2021-06-11 14:02:28 +02:00
+import com.google.common.collect.Lists;
+import it.unimi.dsi.fastutil.objects.ObjectArrayList;
+import java.util.Collection;
+import java.util.List;
2021-06-11 14:02:28 +02:00
+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 org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
2021-06-11 14:02:28 +02:00
+
+/**
+ * Helps prepare a particle to be sent to players.
+ * <p>
2021-06-11 14:02:28 +02:00
+ * Usage of the builder is preferred over the super long {@link World#spawnParticle(Particle, Location, int, double, double, double, double, Object)} API
+ */
+@NullMarked
+public class ParticleBuilder implements Cloneable {
2021-06-11 14:02:28 +02:00
+
+ private Particle particle;
+ private @Nullable List<Player> receivers;
+ private @Nullable Player source;
+ private @Nullable Location location;
2021-06-11 14:02:28 +02:00
+ private int count = 1;
+ private double offsetX = 0, offsetY = 0, offsetZ = 0;
+ private double extra = 1;
+ private @Nullable Object data;
2021-06-11 14:02:28 +02:00
+ private boolean force = true;
+
+ public ParticleBuilder(final Particle particle) {
2021-06-11 14:02:28 +02:00
+ 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.
+ */
+ public ParticleBuilder spawn() {
+ if (this.location == null) {
+ throw new IllegalStateException("Please specify location for this particle");
+ }
+ this.location.getWorld().spawnParticle(
+ this.particle, this.receivers, this.source,
+ this.location.getX(), this.location.getY(), this.location.getZ(),
+ this.count, this.offsetX, this.offsetY, this.offsetZ, this.extra, this.data, this.force
2021-06-11 14:02:28 +02:00
+ );
+ return this;
+ }
+
+ /**
+ * @return The particle going to be sent
+ */
+ public Particle particle() {
+ return this.particle;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Changes what particle will be sent
+ *
+ * @param particle The particle
+ * @return a reference to this object.
+ */
+ public ParticleBuilder particle(final Particle particle) {
2021-06-11 14:02:28 +02:00
+ this.particle = particle;
+ return this;
+ }
+
+ /**
+ * @return List of players who will receive the particle, or null for all in world
+ */
+ public @Nullable List<Player> receivers() {
+ return this.receivers;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Example use:
+ * <p>
2021-06-11 14:02:28 +02:00
+ * builder.receivers(16); if (builder.hasReceivers()) { sendParticleAsync(builder); }
+ *
+ * @return If this particle is going to be sent to someone
+ */
+ public boolean hasReceivers() {
+ return (this.receivers == null && this.location != null && !this.location.getWorld().getPlayers().isEmpty()) || (
+ this.receivers != null && !this.receivers.isEmpty());
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Sends this particle to all players in the world. This is rather silly, and you should likely not
2021-06-11 14:02:28 +02:00
+ * be doing this.
+ * <p>
2021-06-11 14:02:28 +02:00
+ * Just be a logical person and use receivers by radius or collection.
+ *
+ * @return a reference to this object.
+ */
+ 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
2021-06-11 14:02:28 +02:00
+ * @return a reference to this object.
+ */
+ public ParticleBuilder receivers(final @Nullable List<Player> receivers) {
2021-06-11 14:02:28 +02: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?
+ 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
2021-06-11 14:02:28 +02:00
+ * @return a reference to this object.
+ */
+ public ParticleBuilder receivers(final @Nullable Collection<Player> receivers) {
2021-06-11 14:02:28 +02:00
+ 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
2021-06-11 14:02:28 +02:00
+ * @return a reference to this object.
+ */
+ public ParticleBuilder receivers(final Player @Nullable... receivers) {
2021-06-11 14:02:28 +02:00
+ 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.
+ */
+ public ParticleBuilder receivers(final int radius) {
+ return this.receivers(radius, radius);
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * 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
2021-06-11 14:02:28 +02:00
+ * @param byDistance true to use a spherical radius, false to use a cuboid
+ * @return a reference to this object.
+ */
+ public ParticleBuilder receivers(final int radius, final boolean byDistance) {
2021-06-11 14:02:28 +02:00
+ if (!byDistance) {
+ return this.receivers(radius, radius, radius);
2021-06-11 14:02:28 +02:00
+ } else {
+ if (this.location == null) {
+ throw new IllegalStateException("Please set location first");
+ }
2021-06-11 14:02:28 +02:00
+ this.receivers = Lists.newArrayList();
+ for (final Player nearbyPlayer : this.location.getWorld()
+ .getNearbyPlayers(this.location, radius, radius, radius)) {
+ final Location loc = nearbyPlayer.getLocation();
+ final double x = NumberConversions.square(this.location.getX() - loc.getX());
+ final double y = NumberConversions.square(this.location.getY() - loc.getY());
+ final double z = NumberConversions.square(this.location.getZ() - loc.getZ());
2021-06-11 14:02:28 +02:00
+ 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
2021-06-11 14:02:28 +02:00
+ * @return a reference to this object.
+ */
+ public ParticleBuilder receivers(final int xzRadius, final int yRadius) {
+ return this.receivers(xzRadius, yRadius, xzRadius);
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * 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
2021-06-11 14:02:28 +02:00
+ * @param byDistance true to use a cylinder shape, false to use cuboid
+ * @return a reference to this object.
+ * @throws IllegalStateException if a location hasn't been specified yet
2021-06-11 14:02:28 +02:00
+ */
+ public ParticleBuilder receivers(final int xzRadius, final int yRadius, final boolean byDistance) {
2021-06-11 14:02:28 +02:00
+ if (!byDistance) {
+ return this.receivers(xzRadius, yRadius, xzRadius);
2021-06-11 14:02:28 +02:00
+ } else {
+ if (this.location == null) {
+ throw new IllegalStateException("Please set location first");
+ }
2021-06-11 14:02:28 +02:00
+ this.receivers = Lists.newArrayList();
+ for (final Player nearbyPlayer : this.location.getWorld()
+ .getNearbyPlayers(this.location, xzRadius, yRadius, xzRadius)) {
+ final Location loc = nearbyPlayer.getLocation();
2021-06-11 14:02:28 +02:00
+ if (Math.abs(loc.getY() - this.location.getY()) > yRadius) {
+ continue;
+ }
+ final double x = NumberConversions.square(this.location.getX() - loc.getX());
+ final double z = NumberConversions.square(this.location.getZ() - loc.getZ());
2021-06-11 14:02:28 +02:00
+ 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.
+ */
+ public ParticleBuilder receivers(final int xRadius, final int yRadius, final int zRadius) {
+ if (this.location == null) {
2021-06-11 14:02:28 +02:00
+ throw new IllegalStateException("Please set location first");
+ }
+ return this.receivers(this.location.getWorld().getNearbyPlayers(this.location, xRadius, yRadius, zRadius));
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * @return The player considered the source of this particle (for Visibility concerns), or null
+ */
+ public @Nullable Player source() {
+ return this.source;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * 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.
+ */
+ public ParticleBuilder source(final @Nullable Player source) {
2021-06-11 14:02:28 +02:00
+ this.source = source;
+ return this;
+ }
+
+ /**
+ * @return Location of where the particle will spawn
+ */
+ public @Nullable Location location() {
+ return this.location;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Sets the location of where to spawn the particle
+ *
+ * @param location The location of the particle
+ * @return a reference to this object.
+ */
+ public ParticleBuilder location(final Location location) {
2021-06-11 14:02:28 +02:00
+ 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
2021-06-11 14:02:28 +02:00
+ * @return a reference to this object.
+ */
+ public ParticleBuilder location(final World world, final double x, final double y, final double z) {
2021-06-11 14:02:28 +02:00
+ this.location = new Location(world, x, y, z);
+ return this;
+ }
+
+ /**
+ * @return Number of particles to spawn
+ */
+ public int count() {
+ return this.count;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Sets the number of particles to spawn
+ *
+ * @param count Number of particles
+ * @return a reference to this object.
+ */
+ public ParticleBuilder count(final int count) {
2021-06-11 14:02:28 +02:00
+ this.count = count;
+ return this;
+ }
+
+ /**
+ * Particle offset X. Varies by particle on how this is used
+ *
+ * @return Particle offset X.
+ */
+ public double offsetX() {
+ return this.offsetX;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Particle offset Y. Varies by particle on how this is used
+ *
+ * @return Particle offset Y.
+ */
+ public double offsetY() {
+ return this.offsetY;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Particle offset Z. Varies by particle on how this is used
+ *
+ * @return Particle offset Z.
+ */
+ public double offsetZ() {
+ return this.offsetZ;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * 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.
+ */
+ public ParticleBuilder offset(final double offsetX, final double offsetY, final double offsetZ) {
2021-06-11 14:02:28 +02:00
+ 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 this.extra;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * 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.
+ */
+ public ParticleBuilder extra(final double extra) {
2021-06-11 14:02:28 +02:00
+ 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
+ */
+ public @Nullable <T> T data() {
2021-06-11 14:02:28 +02:00
+ //noinspection unchecked
+ return (T) this.data;
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * 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
2021-06-11 14:02:28 +02:00
+ * @return a reference to this object.
+ */
+ public <T> ParticleBuilder data(final @Nullable T data) {
2021-06-11 14:02:28 +02:00
+ this.data = data;
+ return this;
+ }
+
+ /**
+ * @return whether the particle is forcefully shown to players.
+ */
+ public boolean force() {
+ return this.force;
+ }
+
+ /**
2021-06-11 14:02:28 +02: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
+ * @return a reference to this object.
+ */
+ public ParticleBuilder force(final boolean force) {
2021-06-11 14:02:28 +02:00
+ this.force = force;
+ return this;
+ }
+
+ /**
+ * Sets the particle Color.
+ * Only valid for particles with a data type of {@link Color} or {@link Particle.DustOptions}.
2021-06-11 14:02:28 +02:00
+ *
+ * @param color the new particle color
+ * @return a reference to this object.
+ */
+ public ParticleBuilder color(final @Nullable Color color) {
+ if (this.particle.getDataType() == Color.class) {
+ return this.data(color);
+ }
+ return this.color(color, 1);
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Sets the particle Color and size.
+ * Only valid for particles with a data type of {@link Particle.DustOptions}.
2021-06-11 14:02:28 +02:00
+ *
+ * @param color the new particle color
+ * @param size the size of the particle
2021-06-11 14:02:28 +02:00
+ * @return a reference to this object.
+ */
+ public ParticleBuilder color(final @Nullable Color color, final float size) {
+ if (this.particle.getDataType() != Particle.DustOptions.class && color != null) {
+ throw new IllegalStateException("The combination of Color and size cannot be set on this particle type.");
2021-06-11 14:02:28 +02:00
+ }
+
+ // We don't officially support reusing these objects, but here we go
+ if (color == null) {
+ if (this.data instanceof Particle.DustOptions) {
+ return this.data(null);
2021-06-11 14:02:28 +02:00
+ } else {
+ return this;
+ }
+ }
+
+ return this.data(new Particle.DustOptions(color, size));
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Sets the particle Color.
+ * Only valid for particles with a data type of {@link Color} or {@link Particle.DustOptions}.
+ *
2021-06-11 14:02:28 +02:00
+ * @param r red color component
+ * @param g green color component
+ * @param b blue color component
+ * @return a reference to this object.
+ */
+ public ParticleBuilder color(final int r, final int g, final int b) {
+ return this.color(Color.fromRGB(r, g, b));
2021-06-11 14:02:28 +02:00
+ }
+
+ /**
+ * Sets the particle Color.
+ * Only valid for particles with a data type of {@link Color} or {@link Particle.DustOptions}.
+ * <p>
+ * This method detects if the provided color integer is in RGB or ARGB format.
+ * If the alpha channel is zero, it treats the color as RGB. Otherwise, it treats it as ARGB.
+ *
+ * @param color an integer representing the color components. If the highest byte (alpha channel) is zero,
+ * the color is treated as RGB. Otherwise, it is treated as ARGB.
+ * @return a reference to this object.
+ */
+ public ParticleBuilder color(final int color) {
+ final int alpha = (color >> 24) & 0xFF;
+ if (alpha == 0) {
+ return this.color(Color.fromRGB(color));
+ }
+ return this.color(Color.fromARGB(color));
+ }
+
+ /**
+ * Sets the particle Color.
+ * Only valid for particles with a data type of {@link Color} or {@link Particle.DustOptions}.
+ *
+ * @param a alpha color component
+ * @param r red color component
+ * @param g green color component
+ * @param b blue color component
+ * @return a reference to this object.
+ */
+ public ParticleBuilder color(final int a, final int r, final int g, final int b) {
+ return this.color(Color.fromARGB(a, r, g, b));
+ }
+
+ /**
+ * Sets the particle Color Transition.
+ * Only valid for {@link Particle#DUST_COLOR_TRANSITION}.
+ *
+ * @param fromColor the new particle from color
+ * @param toColor the new particle to color
+ * @return a reference to this object.
+ * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
+ */
+ public ParticleBuilder colorTransition(final Color fromColor, final Color toColor) {
+ return this.colorTransition(fromColor, toColor, 1);
+ }
+
+ /**
+ * Sets the particle Color Transition.
+ * Only valid for {@link Particle#DUST_COLOR_TRANSITION}.
+ *
+ * @param fromRed red color component for the "from" color
+ * @param fromGreen green color component for the "from" color
+ * @param fromBlue blue color component for the "from" color
+ * @param toRed red color component for the to color
+ * @param toGreen green color component for the to color
+ * @param toBlue blue color component for the to color
+ * @return a reference to this object.
+ * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
+ */
+ public ParticleBuilder colorTransition(
+ final int fromRed, final int fromGreen, final int fromBlue,
+ final int toRed, final int toGreen, final int toBlue
+ ) {
+ return this.colorTransition(Color.fromRGB(fromRed, fromGreen, fromBlue), Color.fromRGB(toRed, toGreen, toBlue));
+ }
+
+ /**
+ * Sets the particle Color Transition.
+ * Only valid for {@link Particle#DUST_COLOR_TRANSITION}.
+ *
+ * @param fromRgb an integer representing the red, green, and blue color components for the "from" color
+ * @param toRgb an integer representing the red, green, and blue color components for the "to" color
+ * @return a reference to this object.
+ * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
+ */
+ public ParticleBuilder colorTransition(final int fromRgb, final int toRgb) {
+ return this.colorTransition(Color.fromRGB(fromRgb), Color.fromRGB(toRgb));
+ }
+
+ /**
+ * Sets the particle Color Transition and size.
+ * Only valid for {@link Particle#DUST_COLOR_TRANSITION}.
+ *
+ * @param fromColor the new particle color for the "from" color.
+ * @param toColor the new particle color for the "to" color.
+ * @param size the size of the particle
+ * @return a reference to this object.
+ * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
+ */
+ public ParticleBuilder colorTransition(final Color fromColor, final Color toColor, final float size) {
+ Preconditions.checkArgument(fromColor != null, "Cannot define color transition with null fromColor.");
+ Preconditions.checkArgument(toColor != null, "Cannot define color transition with null toColor.");
+ Preconditions.checkArgument(this.particle() == Particle.DUST_COLOR_TRANSITION, "Can only define a color transition on particle DUST_COLOR_TRANSITION.");
+ return this.data(new Particle.DustTransition(fromColor, toColor, size));
+ }
+
+ @Override
+ public ParticleBuilder clone() {
+ try {
+ final ParticleBuilder builder = (ParticleBuilder) super.clone();
+ if (this.location != null) builder.location = this.location.clone();
+ if (this.receivers != null) builder.receivers = new ObjectArrayList<>(this.receivers);
+ return builder;
+ } catch (final CloneNotSupportedException e) {
+ throw new AssertionError();
+ }
+ }
2021-06-11 14:02:28 +02:00
+}
diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
2024-10-22 18:23:19 +02:00
index a1896780f312a91ab2330d2c850641d66143f23e..37e7862be843da4f48ac061fb1625854fd671b2a 100644
2021-06-11 14:02:28 +02:00
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
2024-10-22 18:23:19 +02:00
@@ -205,6 +205,18 @@ public enum Particle implements Keyed {
return key;
2021-06-11 14:02:28 +02:00
}
+ // 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
+
2021-06-11 14:02:28 +02:00
/**
* Options which can be applied to dust particles - a particle
2021-06-11 14:02:28 +02:00
* color and size.
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
Update upstream (Bukkit/CraftBukkit/Spigot) (#10875) 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: 376e37db SPIGOT-7677: Update which entities are marked as spawnable 06c4add3 SPIGOT-7737: Add separate TreeType.MEGA_PINE 19b7caaa SPIGOT-7731: Spawn eggs cannot have damage e585297e PR-1022: Add force option to Player#spawnParticle d26e0094 PR-1018: Add methods to get players seeing specific chunks 8df1ed18 PR-978: Add Material#isCompostable and Material#getCompostChance 4b9b59c7 SPIGOT-7676: Enforce locale parameter in toLowerCase and toUpperCase method calls and always use root locale 8d1e700a PR-1020: Cast instead of using #typed when getting BlockType and ItemType to better work with testing / mocks fa28607a PR-1016: Fix incorrect assumption of Fireball having constant speed 4c6c8586 PR-1015: Add a tool component to ItemMeta 6f6b2123 PR-1014: Add PotionEffectTypeCategory to distinguish between beneficial and harmful effects f511cfe1 PR-1013, SPIGOT-4288, SPIGOT-6202: Add material rerouting in preparation for the switch to ItemType and BlockType def44cbf SPIGOT-7669: Fix typo in ProjectileHitEvent#getHitBlockFace documentation 53fa4f72 PR-1011: Throw an exception if a RecipeChoice is ever supplied air CraftBukkit Changes: ee95e171a SPIGOT-7737: Add separate TreeType.MEGA_PINE 0dae4c62c Fix spawn egg equality check and copy constructor ab59e847c Fix spawn eggs with no entity creating invalid stacks and disconnect creative clients 3b6093b28 SPIGOT-7736: Creative spawn egg use loses components c6b4d5a87 SPIGOT-7731: Spawn eggs cannot have damage 340ccd57f SPIGOT-7735: Fix serialization of player heads with note block sound fd2f41834 SPIGOT-7734: Can't register a custom advancement using unsafe() 02456e2a5 PR-1413: Add force option to Player#spawnParticle 6a61f38b2 SPIGOT-7680: Per-world weather command 58c41cebb PR-1409: Add methods to get players seeing specific chunks 16c976797 PR-1412: Fix shipwreck loot tables not being set for BlockTransformers 7189ba636 PR-1360: Add Material#isCompostable and Material#getCompostChance 900384556 SPIGOT-7676: Enforce locale parameter in toLowerCase and toUpperCase method calls and always use root locale bdb40c5f1 Increase outdated build delay d6607c7dd SPIGOT-7675: Fix FoodComponent config deserialization b148ed332 PR-1406: Fix incorrect assumption of Fireball having constant speed 3ec31ca75 PR-1405: Add a tool component to ItemMeta 5d7d675b9 PR-1404: Add PotionEffectTypeCategory to distinguish between beneficial and harmful effects 960827981 PR-1403, SPIGOT-4288, SPIGOT-6202: Add material rerouting in preparation for the switch to ItemType and BlockType 94e44ec93 PR-1401: Add a config option to accept old keys in registry get calls a43701920 PR-1402: Fix ChunkSnapshot#isSectionEmpty() is always false 87d0a3368 SPIGOT-7668: Move NONE Registry updater to FieldRename to avoid some class loader issues 2ea1e7ac2 PR-1399: Fix regression preventing positive .setDamage value from causing knockback for 0 damage events ba2d49d21 Increase outdated build delay Spigot Changes: fcd94e21 Rebuild patches 342f4939 SPIGOT-7661: Add experimental unload-frozen-chunks option
2024-06-13 16:45:27 +02:00
index 9cf4823ddf1b8291e8c11c39c02c1fed58c18936..44a74f15bea60ecd8380520e8faaea41a6c261c5 100644
2021-06-11 14:02:28 +02:00
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
Update upstream (Bukkit/CraftBukkit/Spigot) (#10875) 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: 376e37db SPIGOT-7677: Update which entities are marked as spawnable 06c4add3 SPIGOT-7737: Add separate TreeType.MEGA_PINE 19b7caaa SPIGOT-7731: Spawn eggs cannot have damage e585297e PR-1022: Add force option to Player#spawnParticle d26e0094 PR-1018: Add methods to get players seeing specific chunks 8df1ed18 PR-978: Add Material#isCompostable and Material#getCompostChance 4b9b59c7 SPIGOT-7676: Enforce locale parameter in toLowerCase and toUpperCase method calls and always use root locale 8d1e700a PR-1020: Cast instead of using #typed when getting BlockType and ItemType to better work with testing / mocks fa28607a PR-1016: Fix incorrect assumption of Fireball having constant speed 4c6c8586 PR-1015: Add a tool component to ItemMeta 6f6b2123 PR-1014: Add PotionEffectTypeCategory to distinguish between beneficial and harmful effects f511cfe1 PR-1013, SPIGOT-4288, SPIGOT-6202: Add material rerouting in preparation for the switch to ItemType and BlockType def44cbf SPIGOT-7669: Fix typo in ProjectileHitEvent#getHitBlockFace documentation 53fa4f72 PR-1011: Throw an exception if a RecipeChoice is ever supplied air CraftBukkit Changes: ee95e171a SPIGOT-7737: Add separate TreeType.MEGA_PINE 0dae4c62c Fix spawn egg equality check and copy constructor ab59e847c Fix spawn eggs with no entity creating invalid stacks and disconnect creative clients 3b6093b28 SPIGOT-7736: Creative spawn egg use loses components c6b4d5a87 SPIGOT-7731: Spawn eggs cannot have damage 340ccd57f SPIGOT-7735: Fix serialization of player heads with note block sound fd2f41834 SPIGOT-7734: Can't register a custom advancement using unsafe() 02456e2a5 PR-1413: Add force option to Player#spawnParticle 6a61f38b2 SPIGOT-7680: Per-world weather command 58c41cebb PR-1409: Add methods to get players seeing specific chunks 16c976797 PR-1412: Fix shipwreck loot tables not being set for BlockTransformers 7189ba636 PR-1360: Add Material#isCompostable and Material#getCompostChance 900384556 SPIGOT-7676: Enforce locale parameter in toLowerCase and toUpperCase method calls and always use root locale bdb40c5f1 Increase outdated build delay d6607c7dd SPIGOT-7675: Fix FoodComponent config deserialization b148ed332 PR-1406: Fix incorrect assumption of Fireball having constant speed 3ec31ca75 PR-1405: Add a tool component to ItemMeta 5d7d675b9 PR-1404: Add PotionEffectTypeCategory to distinguish between beneficial and harmful effects 960827981 PR-1403, SPIGOT-4288, SPIGOT-6202: Add material rerouting in preparation for the switch to ItemType and BlockType 94e44ec93 PR-1401: Add a config option to accept old keys in registry get calls a43701920 PR-1402: Fix ChunkSnapshot#isSectionEmpty() is always false 87d0a3368 SPIGOT-7668: Move NONE Registry updater to FieldRename to avoid some class loader issues 2ea1e7ac2 PR-1399: Fix regression preventing positive .setDamage value from causing knockback for 0 damage events ba2d49d21 Increase outdated build delay Spigot Changes: fcd94e21 Rebuild patches 342f4939 SPIGOT-7661: Add experimental unload-frozen-chunks option
2024-06-13 16:45:27 +02:00
@@ -2948,7 +2948,57 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
2021-06-11 14:02:28 +02:00
* @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 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)