Class ParticleBuilder

java.lang.Object
com.destroystokyo.paper.ParticleBuilder
All Implemented Interfaces:
Cloneable
@NullMarked public class ParticleBuilder extends Object implements Cloneable
Helps prepare a particle to be sent to players.

Usage of the builder is preferred over the super long World.spawnParticle(Particle, List, Player, double, double, double, int, double, double, double, double, double, double, Object, boolean, Particle.RandomizationType) API.

  • Constructor Details

    • ParticleBuilder

      public ParticleBuilder(Particle particle)

  • Method Details

    • spawn

      public 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

      public Particle particle()
      Returns:
      The particle going to be sent

    • particle

      public ParticleBuilder particle(Particle particle)
      Changes what particle will be sent
      Parameters:
      particle - The particle
      Returns:
      a reference to this object.

    • receivers

      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

      public 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

      public ParticleBuilder receivers(@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

      public ParticleBuilder receivers(@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

      public ParticleBuilder receivers(Player @Nullable ... 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

      public 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

      public 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

      public 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

      public 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.
      Throws:
      IllegalStateException - if a location hasn't been specified yet

    • receivers

      public 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

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

    • source

      public ParticleBuilder source(@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

      public @Nullable Location location()
      Returns:
      Location of where the particle will spawn

    • location

      public ParticleBuilder location(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

      public ParticleBuilder location(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

      public 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

      public 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

      @Deprecated(since="26.3", forRemoval=true) public double extra()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use one of the speed methods instead
      Gets the Particle extra data (speedX). Varies by particle on how this is used
      Returns:
      the extra particle data

    • extra

      @Deprecated(since="26.3", forRemoval=true) public ParticleBuilder extra(double extra)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use speed(double) instead
      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.

    • speedX

      public double speedX()
      Particle speed X. Varies by particle on how this is used
      Returns:
      the particle speed X

    • speedY

      public double speedY()
      Particle speed Y. Varies by particle on how this is used
      Returns:
      the particle speed Y

    • speedZ

      public double speedZ()
      Particle speed Z. Varies by particle on how this is used
      Returns:
      the particle speed Z

    • speed

      public ParticleBuilder speed(double speed)
      Sets the particle speed. Varies by particle on how this is used
      Parameters:
      speed - Particle speed
      Returns:
      a reference to this object.

    • speed

      public ParticleBuilder speed(double speedX, double speedY, double speedZ)
      Sets the particle speed. Varies by particle on how this is used
      Parameters:
      speedX - Particle speed X
      speedY - Particle speed Y
      speedZ - Particle speed Z
      Returns:
      a reference to this object.

    • data

      public <T> @Nullable 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

      public <T> 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

      public 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.

    • randomizationType

      public Particle.RandomizationType randomizationType()
      Gets the randomization type for the particle. This determines how the particle's position and velocity are randomized.
      Returns:
      the randomization type for the particle

    • randomizationType

      public ParticleBuilder randomizationType(Particle.RandomizationType randomizationType)
      Sets the randomization type for the particle. This determines how the particle's position and velocity are randomized.
      Parameters:
      randomizationType - the new randomization type for the particle
      Returns:
      a reference to this object.

    • color

      public ParticleBuilder color(@Nullable Color color)
      Sets the particle Color. Only valid for particles with a data type of Color, Particle.DustOptions or Particle.Spell.
      Parameters:
      color - the new particle color
      Returns:
      a reference to this object.

    • color

      public ParticleBuilder color(@Nullable Color color, float value)
      Sets the particle Color and size or power. Only valid for particles with a data type of Particle.DustOptions or Particle.Spell.
      Parameters:
      color - the new particle color
      value - the size or power of the particle
      Returns:
      a reference to this object.

    • color

      public ParticleBuilder color(int r, int g, int b)
      Sets the particle Color. Only valid for particles with a data type of Color, Particle.DustOptions or Particle.Spell.
      Parameters:
      r - red color component
      g - green color component
      b - blue color component
      Returns:
      a reference to this object.

    • color

      public ParticleBuilder color(int color)
      Sets the particle Color. Only valid for particles with a data type of Color, Particle.DustOptions or Particle.Spell.

      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.

      Parameters:
      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.
      Returns:
      a reference to this object.

    • color

      public ParticleBuilder color(int a, int r, int g, int b)
      Sets the particle Color. Only valid for particles with a data type of Color, Particle.DustOptions or Particle.Spell.
      Parameters:
      a - alpha color component
      r - red color component
      g - green color component
      b - blue color component
      Returns:
      a reference to this object.

    • colorTransition

      public ParticleBuilder colorTransition(Color fromColor, Color toColor)
      Sets the particle Color Transition. Only valid for Particle.DUST_COLOR_TRANSITION.
      Parameters:
      fromColor - the new particle from color
      toColor - the new particle to color
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if the particle builder's particle() isn't Particle.DUST_COLOR_TRANSITION.

    • colorTransition

      public ParticleBuilder colorTransition(int fromRed, int fromGreen, int fromBlue, int toRed, int toGreen, int toBlue)
      Sets the particle Color Transition. Only valid for Particle.DUST_COLOR_TRANSITION.
      Parameters:
      fromRed - red color component for the "from" color
      fromGreen - green color component for the "from" color
      fromBlue - blue color component for the "from" color
      toRed - red color component for the to color
      toGreen - green color component for the to color
      toBlue - blue color component for the to color
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if the particle builder's particle() isn't Particle.DUST_COLOR_TRANSITION.

    • colorTransition

      public ParticleBuilder colorTransition(int fromRgb, int toRgb)
      Sets the particle Color Transition. Only valid for Particle.DUST_COLOR_TRANSITION.
      Parameters:
      fromRgb - an integer representing the red, green, and blue color components for the "from" color
      toRgb - an integer representing the red, green, and blue color components for the "to" color
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if the particle builder's particle() isn't Particle.DUST_COLOR_TRANSITION.

    • colorTransition

      public ParticleBuilder colorTransition(Color fromColor, Color toColor, float size)
      Sets the particle Color Transition and size. Only valid for Particle.DUST_COLOR_TRANSITION.
      Parameters:
      fromColor - the new particle color for the "from" color.
      toColor - the new particle color for the "to" color.
      size - the size of the particle
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if the particle builder's particle() isn't Particle.DUST_COLOR_TRANSITION.

    • clone

      public ParticleBuilder clone()
      Overrides:
      clone in class Object