From fa5fe17b5525db90889a454fd8949895f3159afd Mon Sep 17 00:00:00 2001 From: Aikar 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 00000000..cf812721 --- /dev/null +++ b/src/main/java/com/destroystokyo/paper/ParticleBuilder.java @@ -0,0 +1,244 @@ +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 javax.annotation.Nullable; +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 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; + + 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(), + count, offsetX, offsetY, offsetZ, extra, data + ); + 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 receivers() { + return receivers; + } + + /** + * Sends this particle to all players in the world + */ + public ParticleBuilder allPlayers() { + this.receivers = null; + return this; + } + + /** + * @param receivers List of players to be receive this particle, or null + */ + public ParticleBuilder receivers(@Nullable List receivers) { + this.receivers = receivers != null ? Lists.newArrayList(receivers) : null; + return this; + } + + /** + * @param receivers List of players to be receive this particle, or null + */ + public ParticleBuilder receivers(Player... receivers) { + this.receivers = receivers != null && receivers.length > 0 ? Lists.newArrayList(receivers) : null; + return this; + } + + /** + * @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 data() { + //noinspection unchecked + return (T) data; + } + + /** + * Sets the particle custom data. Varies by particle on how this is used + */ + public ParticleBuilder data(T data) { + this.data = data; + return this; + } + + /** + * 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 index c7b0bd3e..6fa17d98 100644 --- a/src/main/java/org/bukkit/World.java +++ b/src/main/java/org/bukkit/World.java @@ -1791,7 +1791,31 @@ public interface World extends PluginMessageRecipient, Metadatable { * the type of this depends on {@link Particle#getDataType()} * @param Type */ - public void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data); + public default 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 + /** + * 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 Type + */ + public void spawnParticle(Particle particle, List receivers, Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data); + // Paper end // Spigot start public class Spigot -- 2.17.0