Package com.binaris.wizardry.api.client

Class ParticleBuilder

java.lang.Object
com.binaris.wizardry.api.client.ParticleBuilder
public final class ParticleBuilder extends Object

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    ParticleBuilder.ParticleData
    Data class for particle properties to be sent over the network and spawned client-side.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ParticleBuilder()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    ParticleBuilder
    allowServer(boolean allow)
    Sets whether server-side spawning is allowed for the particle being built.
    ParticleBuilder
    collide(boolean collide)
    Sets the collisions of the particle being built.
    ParticleBuilder
    color(float r, float g, float b)
    Sets the color of the particle being built.
    ParticleBuilder
    color(int hex)
    Sets the color of the particle being built.
    ParticleBuilder
    color(int r, int g, int b)
    Sets the color of the particle being built.
    static ParticleBuilder
    create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> particle)
    Start building a particle.
    static ParticleBuilder
    create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> type, net.minecraft.util.RandomSource random, double x, double y, double z, double radius)
    Creates a particle at a random position within a radius of the given position.
    static ParticleBuilder
    create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> type, net.minecraft.util.RandomSource random, double x, double y, double z, double radius, boolean move)
    Starts building a particle of the given type and positions it randomly within the given radius of the given position, with velocity proportional to distance from the given position if move is true.
    static ParticleBuilder
    create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> type, net.minecraft.world.entity.Entity entity)
    Starts building a particle of the given type and positions it randomly within the given entity's bounding box.
    ParticleBuilder
    entity(net.minecraft.world.entity.Entity entity)
    Sets the entity of the particle being built.
    ParticleBuilder
    face(float yaw, float pitch)
    Sets the rotation of the particle being built.
    ParticleBuilder
    face(net.minecraft.core.Direction direction)
    Sets the rotation of the particle being built.
    ParticleBuilder
    fade(float r, float g, float b)
    Sets the fade color of the particle being built.
    ParticleBuilder
    fade(int hex)
    Sets the fade color of the particle being built.
    ParticleBuilder
    fade(int r, int g, int b)
    Sets the fade color of the particle being built.
    ParticleBuilder
    gravity(boolean value)
    Set the gravity property of the particle.
    ParticleBuilder
    length(double length)
    Sets the target and target velocity of the particle being built.
    ParticleBuilder
    pos(double x, double y, double z)
    Sets the position of the particle.
    ParticleBuilder
    pos(net.minecraft.core.BlockPos pos)
    Sets the position of the particle.
    ParticleBuilder
    pos(net.minecraft.world.phys.Vec3 vec3d)
    Sets the position of the particle.
    ParticleBuilder
    scale(float scale)
    set the scale of the particle
    ParticleBuilder
    seed(long seed)
    Sets the seed of the particle being built.
    ParticleBuilder
    shaded(boolean value)
    Set the shaded property of the particle.
    void
    spawn(net.minecraft.world.level.Level world)
    Spawn the particle in the world.
    static void
    spawnHealParticles(net.minecraft.world.level.Level world, net.minecraft.world.entity.LivingEntity entity)
     
    static void
    spawnShockParticles(net.minecraft.world.level.Level world, double x, double y, double z)
     
    ParticleBuilder
    spin(double radius, double speed)
    Sets the spin parameters of the particle being built.
    ParticleBuilder
    target(double x, double y, double z)
    Sets the target of the particle being built.
    ParticleBuilder
    target(net.minecraft.world.entity.Entity target)
    Sets the target of the particle being built.
    ParticleBuilder
    target(net.minecraft.world.phys.Vec3 pos)
    Sets the target of the particle being built.
    ParticleBuilder
    time(int lifetime)
    Set the max age of the particle.
    ParticleBuilder
    tvel(double vx, double vy, double vz)
    Sets the target point velocity of the particle being built.
    ParticleBuilder
    tvel(net.minecraft.world.phys.Vec3 vel)
    Sets the target point velocity of the particle being built.
    ParticleBuilder
    velocity(double velocityX, double velocityY, double velocityZ)
    Sets the velocity of the particle.
    ParticleBuilder
    velocity(net.minecraft.world.phys.Vec3 vel)
    Sets the velocity of the particle being built.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ParticleBuilder

      public ParticleBuilder()

  • Method Details

    • create

      public static ParticleBuilder create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> particle)
      Start building a particle. This is just for more readable code with a static function.
      Parameters:
      particle - The particle type
      Returns:
      The ParticleBuilder instance
      Throws:
      IllegalStateException - If already building
      See Also:
      • particle(DeferredObject)

    • create

      public static ParticleBuilder create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> type, net.minecraft.world.entity.Entity entity)
      Starts building a particle of the given type and positions it randomly within the given entity's bounding box. Equivalent to calling ParticleBuilder.create(type).pos(...); users should chain any additional builder methods onto this one and finish with .spawn(world) as normal. Used extensively with summoned creatures; makes code much neater and more concise.

      N.B. this does not cause the particle to move with the given entity.
      Parameters:
      type - The type of particle to build
      entity - The entity to position the particle at
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is already building.

    • create

      public static ParticleBuilder create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> type, net.minecraft.util.RandomSource random, double x, double y, double z, double radius)
      Creates a particle at a random position within a radius of the given position. Just in case if you need to spawn random particles in a radius. For creating a normal particle, use create(DeferredObject)
      Parameters:
      type - The particle type
      random - The random object
      x - The x position
      y - The y position
      z - The z position
      radius - The radius

    • create

      public static ParticleBuilder create(DeferredObject<net.minecraft.core.particles.SimpleParticleType> type, net.minecraft.util.RandomSource random, double x, double y, double z, double radius, boolean move)
      Starts building a particle of the given type and positions it randomly within the given radius of the given position, with velocity proportional to distance from the given position if move is true. Good for making explosion-type effects. Equivalent to calling ParticleBuilder.create(type).pos(...).vel(...); users should chain any additional builder methods onto this one and finish with .spawn(world) as normal.
      Parameters:
      type - The type of particle to build
      random - An RNG instance
      x - The x coordinate of the centre of the region in which to position the particle
      y - The y coordinate of the centre of the region in which to position the particle
      z - The z coordinate of the centre of the region in which to position the particle
      radius - The radius of the region in which to position the particle
      move - Whether the particle should move outwards from the centre (note that if this is false, the particle's default velocity will apply)
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is already building.

    • spawnShockParticles

      public static void spawnShockParticles(net.minecraft.world.level.Level world, double x, double y, double z)

    • spawnHealParticles

      public static void spawnHealParticles(net.minecraft.world.level.Level world, net.minecraft.world.entity.LivingEntity entity)

    • pos

      public ParticleBuilder pos(double x, double y, double z)
      Sets the position of the particle.
      Parameters:
      x - The x position
      y - The y position
      z - The z position
      Throws:
      IllegalStateException - If not building yet

    • pos

      public ParticleBuilder pos(net.minecraft.core.BlockPos pos)
      Sets the position of the particle.
      Parameters:
      pos - The position
      Throws:
      IllegalStateException - If not building yet

    • pos

      public ParticleBuilder pos(net.minecraft.world.phys.Vec3 vec3d)
      Sets the position of the particle.
      Parameters:
      vec3d - The position
      Throws:
      IllegalStateException - If not building yet

    • time

      public ParticleBuilder time(int lifetime)
      Set the max age of the particle.
      Parameters:
      lifetime - The lifetime
      Throws:
      IllegalStateException - If not building yet

    • velocity

      public ParticleBuilder velocity(double velocityX, double velocityY, double velocityZ)
      Sets the velocity of the particle.
      Parameters:
      velocityX - The x velocity
      velocityY - The y velocity
      velocityZ - The z velocity
      Throws:
      IllegalStateException - If not building yet

    • velocity

      public ParticleBuilder velocity(net.minecraft.world.phys.Vec3 vel)
      Sets the velocity of the particle being built. This is a vector-based alternative to velocity(double, double, double) ( double, double, double)}, allowing for even more concise code when a vector is available.

      Affects: All particle types
      Parameters:
      vel - A vector representing the velocity of the particle to be built.
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • scale

      public ParticleBuilder scale(float scale)
      set the scale of the particle
      Parameters:
      scale - The scale
      Throws:
      IllegalStateException - If not building yet

    • color

      public ParticleBuilder color(float r, float g, float b)
      Sets the color of the particle being built. If unspecified, this defaults to the particle's default color, specified within its constructor. If all colour components are 0 or 1, at least one must have the float suffix (f or F) or the integer overload will be used instead, causing the particle to appear black!

      Affects: All particle types except ICE, MAGIC_BUBBLE and MAGIC_FIRE
      Parameters:
      r - The red color component to set; will be clamped to between zero and one
      g - The green color component to set; will be clamped to between zero and one
      b - The blue color component to set; will be clamped to between zero and one
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • color

      public ParticleBuilder color(int r, int g, int b)
      Sets the color of the particle being built. This is an 8-bit (0-255) integer version of color(float, float, float).

      Affects: All particle types except ICE, MAGIC_BUBBLE and MAGIC_FIRE
      Parameters:
      r - The red color component to set; will be clamped to between 0 and 255
      g - The green color component to set; will be clamped to between 0 and 255
      b - The blue color component to set; will be clamped to between 0 and 255
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • color

      public ParticleBuilder color(int hex)
      Sets the color of the particle being built. This is a 6-digit hex color version of color(float, float, float).

      Affects: All particle types except ICE, MAGIC_BUBBLE and MAGIC_FIRE
      Parameters:
      hex - The colour to be set, as a packed 6-digit hex integer (e.g. 0xff0000).
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • fade

      public ParticleBuilder fade(float r, float g, float b)
      Sets the fade color of the particle being built. If unspecified, this defaults to whatever the particle's base colour is. If all colour components are 0 or 1, at least one must have the float suffix (f or F) or the integer overload will be used instead, causing the particle to appear black!

      Affects: All particle types except ICE, MAGIC_BUBBLE and MAGIC_FIRE
      Parameters:
      r - The red color component to set; will be clamped to between zero and one
      g - The green color component to set; will be clamped to between zero and one
      b - The blue color component to set; will be clamped to between zero and one
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • fade

      public ParticleBuilder fade(int r, int g, int b)
      Sets the fade color of the particle being built. This is an 8-bit (0-255) integer version of fade(float, float, float).

      Affects: All particle types except ICE, MAGIC_BUBBLE and MAGIC_FIRE
      Parameters:
      r - The red colour component to set; will be clamped to between 0 and 255
      g - The green colour component to set; will be clamped to between 0 and 255
      b - The blue colour component to set; will be clamped to between 0 and 255
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • fade

      public ParticleBuilder fade(int hex)
      Sets the fade color of the particle being built. This is a 6-digit hex color version of fade(float, float, float).

      Affects: All particle types except ICE, MAGIC_BUBBLE and MAGIC_FIRE
      Parameters:
      hex - The colour to be set, as a packed 6-digit hex integer (e.g., 0xff0000).
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • seed

      public ParticleBuilder seed(long seed)
      Sets the seed of the particle being built. If unspecified, this defaults to the particle's default seed, specified within its constructor (this is normally chosen at random).

      Pro tip: to get a particle to stay the same while a continuous spell is in use (but change between casts), use .seed(world.getTotalWorldTime() - ticksInUse).

      Affects: All particle types
      Parameters:
      seed - The seed to set
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • spin

      public ParticleBuilder spin(double radius, double speed)
      Sets the spin parameters of the particle being built. If unspecified, these both default to 0.

      Affects: All particle types
      Parameters:
      radius - The rotation radius to set
      speed - The rotation speed to set, in revolutions per tick
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • collide

      public ParticleBuilder collide(boolean collide)
      Sets the collisions of the particle being built. If unspecified, this defaults to false.

      Affects: All particle types
      Parameters:
      collide - True to enable block collisions for the particle, false to disable
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • entity

      public ParticleBuilder entity(net.minecraft.world.entity.Entity entity)
      Sets the entity of the particle being built. This will cause the particle to move with the given entity, and will make the position specified using pos(double, double, double) relative to that entity's position.

      Affects: All particle types
      Parameters:
      entity - The entity to set (passing in null will do nothing but will not cause any problems, so for the sake of conciseness it is not necessary to perform a null check on the passed-in argument)
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • face

      public ParticleBuilder face(float yaw, float pitch)
      Sets the rotation of the particle being built. If unspecified, the particle will use the default behavior and rotate to face the viewer.

      Affects: All particle types
      Parameters:
      yaw - The yaw angle to set in degrees, where 0 is south.
      pitch - The pitch angle to set in degrees, where 0 is horizontal.
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • face

      public ParticleBuilder face(net.minecraft.core.Direction direction)
      Sets the rotation of the particle being built. This is an EnumFacing-based alternative to face(float, float) which sets the yaw and pitch to the appropriate angles for the given facing. For example, if the given facing is NORTH, the particle will render parallel to the north face of blocks. If unspecified, the particle will use the default behavior and rotate to face the viewer.

      Affects: All particle types
      Parameters:
      direction - The EnumFacing direction to set.
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • allowServer

      public ParticleBuilder allowServer(boolean allow)
      Sets whether server-side spawning is allowed for the particle being built. By default this is false.

      There's no need to allow this for spell casting (normally) as spells handle particle spawning and synchronization themselves, check Spell.requiresPacket() for more details.

      Parameters:
      allow - True to allow server-side spawning, false to prevent it
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • shaded

      public ParticleBuilder shaded(boolean value)
      Set the shaded property of the particle.
      Parameters:
      value - The value
      Throws:
      IllegalStateException - If not building yet

    • gravity

      public ParticleBuilder gravity(boolean value)
      Set the gravity property of the particle.
      Parameters:
      value - The value
      Throws:
      IllegalStateException - If not building yet

    • target

      public ParticleBuilder target(double x, double y, double z)
      Sets the target of the particle being built. This will cause the particle to stretch to touch the given position.

      Affects: Targeted particles, namely BEAM, LIGHTNING and
      Parameters:
      x - The target x-coordinate to set
      y - The target y-coordinate to set
      z - The target z-coordinate to set
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • target

      public ParticleBuilder target(net.minecraft.world.phys.Vec3 pos)
      Sets the target of the particle being built. This is a vector-based alternative to target(double, double, double), allowing for even more concise code when a vector is available.

      Affects: Targeted particles, namely BEAM, LIGHTNING and
      Parameters:
      pos - A vector representing the target position of the particle to be built.
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • tvel

      public ParticleBuilder tvel(double vx, double vy, double vz)
      Sets the target point velocity of the particle being built. This will cause the position it stretches to touch to move at the given velocity. Has no effect unless target(double, double, double) or one of its overloads is also set.

      Affects: Targeted particles, namely BEAM, LIGHTNING and
      Parameters:
      vx - The target point x velocity to set
      vy - The target point y velocity to set
      vz - The target point z velocity to set
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • tvel

      public ParticleBuilder tvel(net.minecraft.world.phys.Vec3 vel)
      Sets the target point velocity of the particle being built. This is a vector-based alternative to tvel(double, double, double), allowing for even more concise code when a vector is available.

      Affects: Targeted particles, namely BEAM, LIGHTNING and
      Parameters:
      vel - A vector representing the target point velocity of the particle to be built.
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • length

      public ParticleBuilder length(double length)
      Sets the target and target velocity of the particle being built. This method takes an origin entity and a position and estimates the position of the target point based on the given entity's rotational velocities and its distance from the given position.

      Affects: Targeted particles, namely BEAM, LIGHTNING and
      Parameters:
      length - The length of the particle being built.
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • target

      public ParticleBuilder target(net.minecraft.world.entity.Entity target)
      Sets the target of the particle being built. This will cause the particle to stretch to touch the given entity.

      Affects: Targeted particles, namely BEAM, LIGHTNING and
      Parameters:
      target - The entity to set
      Returns:
      The particle builder instance, allowing other methods to be chained onto this one
      Throws:
      IllegalStateException - if the particle builder is not yet building.

    • spawn

      public void spawn(net.minecraft.world.level.Level world)
      Spawn the particle in the world.

      Use ParticleWizardry.PROVIDERS to get the particle factory, set the properties and then add the particle to the particle manager.

      Warn if the particle is being spawned at (0, 0, 0) and the entity is null or ParticleBuilder is being used in server side, as this is likely to be a mistake.

      Parameters:
      world - The world
      Throws:
      IllegalStateException - If not building yet