Package com.destroystokyo.paper

# Class ParticleBuilder

java.lang.Object
com.destroystokyo.paper.ParticleBuilder

public class ParticleBuilder extends Object
Helps prepare a particle to be sent to players. Usage of the builder is preferred over the super long `World.spawnParticle(Particle, Location, int, double, double, double, double, Object)` API

## Constructor Summary

Constructors
Constructor
Description
`ParticleBuilder(@NotNull Particle particle)`

## Method Summary

Modifier and Type
Method
Description
`@NotNull ParticleBuilder`
`allPlayers()`
Sends this particle to all players in the world.
`@NotNull ParticleBuilder`
`color(int r, int g, int b)`
Sets the particle Color.
`@NotNull ParticleBuilder`
`color(@Nullable Color color)`
Sets the particle Color.
`@NotNull ParticleBuilder`
`color(@Nullable Color color, float size)`
Sets the particle Color and size.
`int`
`count()`
`@NotNull ParticleBuilder`
`count(int count)`
Sets the number of particles to spawn
`<T> T`
`data()`
Gets the particle custom data.
`<T> @NotNull ParticleBuilder`
`data(T data)`
Sets the particle custom data.
`double`
`extra()`
Gets the Particle extra data.
`@NotNull ParticleBuilder`
`extra(double extra)`
Sets the particle extra data.
`boolean`
`force()`
`@NotNull ParticleBuilder`
`force(boolean force)`
Sets whether the particle is forcefully shown to the player.
`boolean`
`hasReceivers()`
Example use: builder.receivers(16); if (builder.hasReceivers()) { sendParticleAsync(builder); }
`@Nullable Location`
`location()`
`@NotNull ParticleBuilder`
`location(@NotNull Location location)`
Sets the location of where to spawn the particle
`@NotNull ParticleBuilder`
`location(@NotNull World world, double x, double y, double z)`
Sets the location of where to spawn the particle
`@NotNull ParticleBuilder`
`offset(double offsetX, double offsetY, double offsetZ)`
Sets the particle offset.
`double`
`offsetX()`
Particle offset X.
`double`
`offsetY()`
Particle offset Y.
`double`
`offsetZ()`
Particle offset Z.
`@NotNull Particle`
`particle()`
`@NotNull ParticleBuilder`
`particle(@NotNull Particle particle)`
Changes what particle will be sent
`@Nullable List<Player>`
`receivers()`
`@NotNull ParticleBuilder`
`receivers(int radius)`
Selects all players within a cuboid selection around the particle location, within the specified bounding box.
`@NotNull ParticleBuilder`
`receivers(int radius, boolean byDistance)`
Selects all players within the specified radius around the particle location.
`@NotNull ParticleBuilder`
`receivers(int xzRadius, int yRadius)`
Selects all players within a cuboid selection around the particle location, within the specified bounding box.
`@NotNull ParticleBuilder`
`receivers(int xzRadius, int yRadius, boolean byDistance)`
Selects all players within the specified radius around the particle location.
`@NotNull ParticleBuilder`
`receivers(int xRadius, int yRadius, int zRadius)`
Selects all players within a cuboid selection around the particle location, within the specified bounding box.
`@NotNull ParticleBuilder`
`receivers(@Nullable Collection<Player> receivers)`
`@NotNull ParticleBuilder`
`receivers(@Nullable List<Player> receivers)`
`@NotNull ParticleBuilder`
`receivers(@Nullable Player... receivers)`
`@Nullable Player`
`source()`
`@NotNull ParticleBuilder`
`source(@Nullable Player source)`
Sets the source of this particle for visibility concerns (Vanish API)
`@NotNull ParticleBuilder`
`spawn()`
Sends the particle to all receiving players (or all).

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### ParticleBuilder

public ParticleBuilder(@NotNull @NotNull Particle particle)

## Method Details

### spawn

@NotNull public @NotNull ParticleBuilder spawn()
Sends the particle to all receiving players (or all). This method is safe to use Asynchronously

Returns:
  a reference to this object.

### particle

@NotNull public @NotNull Particle particle()

Returns:
  The particle going to be sent

### particle

@NotNull public @NotNull ParticleBuilder particle(@NotNull @NotNull Particle particle)
Changes what particle will be sent

Parameters:
  `particle` - The particle
Returns:
  a reference to this object.

### receivers

@Nullable public @Nullable List<Player> receivers()

Returns:
  List of players who will receive the particle, or null for all in world

### hasReceivers

public boolean hasReceivers()
Example use: builder.receivers(16); if (builder.hasReceivers()) { sendParticleAsync(builder); }

Returns:
  If this particle is going to be sent to someone

### allPlayers

@NotNull public @NotNull ParticleBuilder allPlayers()
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.

Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(@Nullable @Nullable List<Player> receivers)

Parameters:
  `receivers` - List of players to receive this particle, or null for all players in the world
Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(@Nullable @Nullable Collection<Player> receivers)

Parameters:
  `receivers` - List of players to receive this particle, or null for all players in the world
Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(@Nullable @Nullable Player... receivers)

Parameters:
  `receivers` - List of players to be receive this particle, or null for all players in the world
Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(int radius)
Selects all players within a cuboid selection around the particle location, within the specified bounding box. If you want a more spherical check, see `receivers(int, boolean)`

Parameters:
  `radius` - amount to add on all axis
Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(int radius, boolean byDistance)
Selects all players within the specified radius around the particle location. If byDistance is false, behavior uses cuboid selection the same as `receivers(int, int)` If byDistance is true, radius is tested by distance in a spherical shape

Parameters:
  `radius` - amount to add on each axis
  `byDistance` - true to use a spherical radius, false to use a cuboid
Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(int xzRadius, int yRadius)
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 `receivers(int, int, boolean)` If you want a more spherical check, see `receivers(int, boolean)`

Parameters:
  `xzRadius` - amount to add on the x/z axis
  `yRadius` - amount to add on the y axis
Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(int xzRadius, int yRadius, boolean byDistance)
Selects all players within the specified radius around the particle location. If byDistance is false, behavior uses cuboid selection the same as `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.

Parameters:
  `xzRadius` - amount to add on the x/z axis
  `yRadius` - amount to add on the y axis
  `byDistance` - true to use a cylinder shape, false to use cuboid
Returns:
  a reference to this object.

### receivers

@NotNull public @NotNull ParticleBuilder receivers(int xRadius, int yRadius, int zRadius)
Selects all players within a cuboid selection around the particle location, within the specified bounding box. If you want a more cylinder check, see `receivers(int, int, boolean)` If you want a more spherical check, see `receivers(int, boolean)`

Parameters:
  `xRadius` - amount to add on the x axis
  `yRadius` - amount to add on the y axis
  `zRadius` - amount to add on the z axis
Returns:
  a reference to this object.

### source

@Nullable public @Nullable Player source()

Returns:
  The player considered the source of this particle (for Visibility concerns), or null

### source

@NotNull public @NotNull ParticleBuilder source(@Nullable @Nullable Player source)
Sets the source of this particle for visibility concerns (Vanish API)

Parameters:
  `source` - The player who is considered the source
Returns:
  a reference to this object.

### location

@Nullable public @Nullable Location location()

Returns:
  Location of where the particle will spawn

### location

@NotNull public @NotNull ParticleBuilder location(@NotNull @NotNull Location location)
Sets the location of where to spawn the particle

Parameters:
  `location` - The location of the particle
Returns:
  a reference to this object.

### location

@NotNull public @NotNull ParticleBuilder location(@NotNull @NotNull World world, double x, double y, double z)
Sets the location of where to spawn the particle

Parameters:
  `world` - World to spawn particle in
  `x` - X location
  `y` - Y location
  `z` - Z location
Returns:
  a reference to this object.

### count

public int count()

Returns:
  Number of particles to spawn

### count

@NotNull public @NotNull ParticleBuilder count(int count)
Sets the number of particles to spawn

Parameters:
  `count` - Number of particles
Returns:
  a reference to this object.

### offsetX

public double offsetX()
Particle offset X. Varies by particle on how this is used

Returns:
  Particle offset X.

### offsetY

public double offsetY()
Particle offset Y. Varies by particle on how this is used

Returns:
  Particle offset Y.

### offsetZ

public double offsetZ()
Particle offset Z. Varies by particle on how this is used

Returns:
  Particle offset Z.

### offset

@NotNull public @NotNull ParticleBuilder offset(double offsetX, double offsetY, double offsetZ)
Sets the particle offset. Varies by particle on how this is used

Parameters:
  `offsetX` - Particle offset X
  `offsetY` - Particle offset Y
  `offsetZ` - Particle offset Z
Returns:
  a reference to this object.

### extra

public double extra()
Gets the Particle extra data. Varies by particle on how this is used

Returns:
  the extra particle data

### extra

@NotNull public @NotNull ParticleBuilder extra(double extra)
Sets the particle extra data. Varies by particle on how this is used

Parameters:
  `extra` - the extra particle data
Returns:
  a reference to this object.

### data

@Nullable public <T> T data()
Gets the particle custom data. Varies by particle on how this is used

Type Parameters:
  `T` - The Particle data type
Returns:
  the ParticleData for this particle

### data

@NotNull public <T> @NotNull ParticleBuilder data(@Nullable T data)
Sets the particle custom data. Varies by particle on how this is used

Type Parameters:
  `T` - The Particle data type
Parameters:
  `data` - The new particle data
Returns:
  a reference to this object.

### force

public boolean force()

Returns:
  whether the particle is forcefully shown to players.

### force

@NotNull public @NotNull ParticleBuilder force(boolean 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.

Parameters:
  `force` - true to force, false for normal
Returns:
  a reference to this object.

### color

@NotNull public @NotNull ParticleBuilder color(@Nullable @Nullable Color color)
Sets the particle Color. Only valid for REDSTONE.

Parameters:
  `color` - the new particle color
Returns:
  a reference to this object.

### color

@NotNull public @NotNull ParticleBuilder color(@Nullable @Nullable Color color, float size)
Sets the particle Color and size. Only valid for REDSTONE.

Parameters:
  `color` - the new particle color
  `size` - the size of the particle
Returns:
  a reference to this object.

### color

@NotNull public @NotNull ParticleBuilder color(int r, int g, int b)
Sets the particle Color. Only valid for REDSTONE.

Parameters:
  `r` - red color component
  `g` - green color component
  `b` - blue color component
Returns:
  a reference to this object.