Class Location

Method Details

• setWorld

  public void setWorld(@Nullable @Nullable World world)

  Sets the world that this location resides in

  Parameters:

  world - New world that this location resides in

• isWorldLoaded

  public boolean isWorldLoaded()

  Checks if world in this location is present and loaded.

  Returns:

  true if is loaded, otherwise false

• getWorld

  @UndefinedNullability public World getWorld()

  Gets the world that this location resides in

  Returns:

  World that contains this location, or null if it is not set

  Throws:

  IllegalArgumentException - when world is unloaded

  See Also:

  • isWorldLoaded()

• getChunk

  @NotNull public @NotNull Chunk getChunk()

  Gets the chunk at the represented location

  Returns:

  Chunk at the represented location

• getBlock

  @NotNull public @NotNull Block getBlock()

  Gets the block at the represented location

  Returns:

  Block at the represented location

• setX

  public void setX(double x)

  Sets the x-coordinate of this location

  Parameters:

  x - X-coordinate

• getX

  public double getX()

  Gets the x-coordinate of this location

  Returns:

  x-coordinate

• getBlockX

  public int getBlockX()

  Gets the floored value of the X component, indicating the block that this location is contained with.

  Returns:

  block X

• setY

  public void setY(double y)

  Sets the y-coordinate of this location

  Parameters:

  y - y-coordinate

• getY

  public double getY()

  Gets the y-coordinate of this location

  Returns:

  y-coordinate

• getBlockY

  public int getBlockY()

  Gets the floored value of the Y component, indicating the block that this location is contained with.

  Returns:

  block y

• setZ

  public void setZ(double z)

  Sets the z-coordinate of this location

  Parameters:

  z - z-coordinate

• getZ

  public double getZ()

  Gets the z-coordinate of this location

  Returns:

  z-coordinate

• getBlockZ

  public int getBlockZ()

  Gets the floored value of the Z component, indicating the block that this location is contained with.

  Returns:

  block z

• setYaw

  public void setYaw(float yaw)

  Sets the yaw of this location, measured in degrees.

  • A yaw of 0 or 360 represents the positive z direction.
  • A yaw of 180 represents the negative z direction.
  • A yaw of 90 represents the negative x direction.
  • A yaw of 270 represents the positive x direction.

  Increasing yaw values are the equivalent of turning to your right-facing, increasing the scale of the next respective axis, and decreasing the scale of the previous axis.

  Parameters:

  yaw - new rotation's yaw

• getYaw

  public float getYaw()

  Gets the yaw of this location, measured in degrees.

  • A yaw of 0 or 360 represents the positive z direction.
  • A yaw of 180 represents the negative z direction.
  • A yaw of 90 represents the negative x direction.
  • A yaw of 270 represents the positive x direction.

  Increasing yaw values are the equivalent of turning to your right-facing, increasing the scale of the next respective axis, and decreasing the scale of the previous axis.

  Returns:

  the rotation's yaw

• setPitch

  public void setPitch(float pitch)

  Sets the pitch of this location, measured in degrees.

  • A pitch of 0 represents level forward facing.
  • A pitch of 90 represents downward facing, or negative y direction.
  • A pitch of -90 represents upward facing, or positive y direction.

  Increasing pitch values the equivalent of looking down.

  Parameters:

  pitch - new incline's pitch

• getPitch

  public float getPitch()

  Gets the pitch of this location, measured in degrees.

  • A pitch of 0 represents level forward facing.
  • A pitch of 90 represents downward facing, or negative y direction.
  • A pitch of -90 represents upward facing, or positive y direction.

  Increasing pitch values the equivalent of looking down.

  Returns:

  the incline's pitch

• getDirection

  @NotNull public @NotNull Vector getDirection()

  Gets a unit-vector pointing in the direction that this Location is facing.

  Returns:

  a vector pointing the direction of this location's pitch and yaw

• setDirection

  @NotNull public @NotNull Location setDirection(@NotNull @NotNull Vector vector)

  Sets the yaw and pitch to point in the direction of the vector.

  Parameters:

  vector - the direction vector

  Returns:

  the same location

• add

  @NotNull public @NotNull Location add(@NotNull @NotNull Location vec)

  Adds the location by another.

  Parameters:

  vec - The other location

  Returns:

  the same location

  Throws:

  IllegalArgumentException - for differing worlds

  See Also:

  • Vector

• add

  @NotNull public @NotNull Location add(@NotNull @NotNull Vector vec)

  Adds the location by a vector.

  Parameters:

  vec - Vector to use

  Returns:

  the same location

  See Also:

  • Vector

• add

  @NotNull public @NotNull Location add(double x, double y, double z)

  Adds the location by another. Not world-aware.

  Parameters:

  x - X coordinate

  y - Y coordinate

  z - Z coordinate

  Returns:

  the same location

  See Also:

  • Vector

• subtract

  @NotNull public @NotNull Location subtract(@NotNull @NotNull Location vec)

  Subtracts the location by another.

  Parameters:

  vec - The other location

  Returns:

  the same location

  Throws:

  IllegalArgumentException - for differing worlds

  See Also:

  • Vector

• subtract

  @NotNull public @NotNull Location subtract(@NotNull @NotNull Vector vec)

  Subtracts the location by a vector.

  Parameters:

  vec - The vector to use

  Returns:

  the same location

  See Also:

  • Vector

• subtract

  @NotNull public @NotNull Location subtract(double x, double y, double z)

  Subtracts the location by another. Not world-aware and orientation independent.

  Parameters:

  x - X coordinate

  y - Y coordinate

  z - Z coordinate

  Returns:

  the same location

  See Also:

  • Vector

• length

  public double length()

  Gets the magnitude of the location, defined as sqrt(x^2+y^2+z^2). The value of this method is not cached and uses a costly square-root function, so do not repeatedly call this method to get the location's magnitude. NaN will be returned if the inner result of the sqrt() function overflows, which will be caused if the length is too long. Not world-aware and orientation independent.

  Returns:

  the magnitude

  See Also:

  • Vector

• lengthSquared

  public double lengthSquared()

  Gets the magnitude of the location squared. Not world-aware and orientation independent.

  Returns:

  the magnitude

  See Also:

  • Vector

• distance

  public double distance(@NotNull @NotNull Location o)

  Get the distance between this location and another. The value of this method is not cached and uses a costly square-root function, so do not repeatedly call this method to get the location's magnitude. NaN will be returned if the inner result of the sqrt() function overflows, which will be caused if the distance is too long.

  Parameters:

  o - The other location

  Returns:

  the distance

  Throws:

  IllegalArgumentException - for differing worlds

  See Also:

  • Vector

• distanceSquared

  public double distanceSquared(@NotNull @NotNull Location o)

  Get the squared distance between this location and another.

  Parameters:

  o - The other location

  Returns:

  the distance

  Throws:

  IllegalArgumentException - for differing worlds

  See Also:

  • Vector

• multiply

  @NotNull public @NotNull Location multiply(double m)

  Performs scalar multiplication, multiplying all components with a scalar. Not world-aware.

  Parameters:

  m - The factor

  Returns:

  the same location

  See Also:

  • Vector

• zero

  @NotNull public @NotNull Location zero()

  Zero this location's components. Not world-aware.

  Returns:

  the same location

  See Also:

  • Vector

• isChunkLoaded

  public boolean isChunkLoaded()

• isGenerated

  public boolean isGenerated()

  Checks if a Chunk has been generated at this location.

  Returns:

  true if a chunk has been generated at this location

• set

  @NotNull public @NotNull Location set(double x, double y, double z)

  Sets the position of this Location and returns itself

  This mutates this object, clone first.

  Parameters:

  x - X coordinate

  y - Y coordinate

  z - Z coordinate

  Returns:

  self (not cloned)

• add

  @NotNull public @NotNull Location add(@NotNull @NotNull Location base, double x, double y, double z)

  Takes the x/y/z from base and adds the specified x/y/z to it and returns self

  This mutates this object, clone first.

  Parameters:

  base - The base coordinate to modify

  x - X coordinate to add to base

  y - Y coordinate to add to base

  z - Z coordinate to add to base

  Returns:

  self (not cloned)

• subtract

  @NotNull public @NotNull Location subtract(@NotNull @NotNull Location base, double x, double y, double z)

  Takes the x/y/z from base and subtracts the specified x/y/z to it and returns self

  This mutates this object, clone first.

  Parameters:

  base - The base coordinate to modify

  x - X coordinate to subtract from base

  y - Y coordinate to subtract from base

  z - Z coordinate to subtract from base

  Returns:

  self (not cloned)

• toBlockLocation

  @NotNull public @NotNull Location toBlockLocation()

  Returns:

  A new location where X/Y/Z are on the Block location (integer value of X/Y/Z)

• toBlockKey

  @Deprecated public long toBlockKey()

  Deprecated.

  only encodes y block ranges from -512 to 511 and represents an already changed implementation detail

  Returns:

  The block key for this location's block location.

  See Also:

  • Block.getBlockKey(int, int, int)

• toCenterLocation

  @NotNull public @NotNull Location toCenterLocation()

  Returns:

  A new location where X/Y/Z are the center of the block

• toHighestLocation

  @NotNull public @NotNull Location toHighestLocation()

  Returns a copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ())

  Returns:

  A copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ())

  Throws:

  NullPointerException - if {getWorld()} is null

• toHighestLocation

  @NotNull @Deprecated(forRemoval=true) @ScheduledForRemoval(inVersion="1.21") public @NotNull Location toHighestLocation(@NotNull HeightmapType heightmap)

  Deprecated, for removal: This API element is subject to removal in a future version.

  Use toHighestLocation(HeightMap)

  Returns a copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ(), heightmap)

  Parameters:

  heightmap - The heightmap to use for finding the highest y location.

  Returns:

  A copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ(), heightmap)

  Throws:

  NullPointerException - if {getWorld()} is null

  UnsupportedOperationException - if World.getHighestBlockYAt(int, int, com.destroystokyo.paper.HeightmapType) does not support the specified heightmap

• toHighestLocation

  @NotNull public @NotNull Location toHighestLocation(@NotNull @NotNull HeightMap heightMap)

  Returns a copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ(), heightMap)

  Parameters:

  heightMap - The heightmap to use for finding the highest y location.

  Returns:

  A copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ(), heightMap)

• createExplosion

  public boolean createExplosion(float power)

  Creates explosion at this location with given power

  Will break blocks and ignite blocks on fire.

  Parameters:

  power - The power of explosion, where 4F is TNT

  Returns:

  false if explosion was canceled, otherwise true

• createExplosion

  public boolean createExplosion(float power, boolean setFire)

  Creates explosion at this location with given power and optionally setting blocks on fire.

  Will break blocks.

  Parameters:

  power - The power of explosion, where 4F is TNT

  setFire - Whether to set blocks on fire

  Returns:

  false if explosion was canceled, otherwise true

• createExplosion

  public boolean createExplosion(float power, boolean setFire, boolean breakBlocks)

  Creates explosion at this location with given power and optionally setting blocks on fire.

  Parameters:

  power - The power of explosion, where 4F is TNT

  setFire - Whether to set blocks on fire

  breakBlocks - Whether to have blocks be destroyed

  Returns:

  false if explosion was canceled, otherwise true

• createExplosion

  public boolean createExplosion(@Nullable @Nullable Entity source, float power)

  Creates explosion at this location with given power, with the specified entity as the source.

  Will break blocks and ignite blocks on fire.

  Parameters:

  source - The source entity of the explosion

  power - The power of explosion, where 4F is TNT

  Returns:

  false if explosion was canceled, otherwise true

• createExplosion

  public boolean createExplosion(@Nullable @Nullable Entity source, float power, boolean setFire)

  Creates explosion at this location with given power and optionally setting blocks on fire, with the specified entity as the source.

  Will break blocks.

  Parameters:

  source - The source entity of the explosion

  power - The power of explosion, where 4F is TNT

  setFire - Whether to set blocks on fire

  Returns:

  false if explosion was canceled, otherwise true

• createExplosion

  public boolean createExplosion(@Nullable @Nullable Entity source, float power, boolean setFire, boolean breakBlocks)

  Creates explosion at this location with given power and optionally setting blocks on fire, with the specified entity as the source.

  Parameters:

  source - The source entity of the explosion

  power - The power of explosion, where 4F is TNT

  setFire - Whether to set blocks on fire

  breakBlocks - Whether to have blocks be destroyed

  Returns:

  false if explosion was canceled, otherwise true

• getNearbyEntities

  @NotNull public @NotNull Collection<Entity> getNearbyEntities(double x, double y, double z)

  Returns a list of entities within a bounding box centered around a Location.

  Some implementations may impose artificial restrictions on the size of the search bounding box.

  Parameters:

  x - 1/2 the size of the box along the x-axis

  y - 1/2 the size of the box along the y-axis

  z - 1/2 the size of the box along the z-axis

  Returns:

  the collection of entities near location. This will always be a non-null collection.

• getNearbyLivingEntities

  @NotNull public @NotNull Collection<LivingEntity> getNearbyLivingEntities(double radius)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  radius - X Radius

  Returns:

  the collection of entities near location. This will always be a non-null collection.

• getNearbyLivingEntities

  @NotNull public @NotNull Collection<LivingEntity> getNearbyLivingEntities(double xzRadius, double yRadius)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xzRadius - X/Z Radius

  yRadius - Y Radius

  Returns:

  the collection of living entities near location. This will always be a non-null collection.

• getNearbyLivingEntities

  @NotNull public @NotNull Collection<LivingEntity> getNearbyLivingEntities(double xRadius, double yRadius, double zRadius)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xRadius - X Radius

  yRadius - Y Radius

  zRadius - Z radius

  Returns:

  the collection of living entities near location. This will always be a non-null collection.

• getNearbyLivingEntities

  @NotNull public @NotNull Collection<LivingEntity> getNearbyLivingEntities(double radius, @Nullable @Nullable Predicate<? super LivingEntity> predicate)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  radius - Radius

  predicate - a predicate used to filter results

  Returns:

  the collection of living entities near location. This will always be a non-null collection.

• getNearbyLivingEntities

  @NotNull public @NotNull Collection<LivingEntity> getNearbyLivingEntities(double xzRadius, double yRadius, @Nullable @Nullable Predicate<? super LivingEntity> predicate)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xzRadius - X/Z Radius

  yRadius - Y Radius

  predicate - a predicate used to filter results

  Returns:

  the collection of living entities near location. This will always be a non-null collection.

• getNearbyLivingEntities

  @NotNull public @NotNull Collection<LivingEntity> getNearbyLivingEntities(double xRadius, double yRadius, double zRadius, @Nullable @Nullable Predicate<? super LivingEntity> predicate)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xRadius - X Radius

  yRadius - Y Radius

  zRadius - Z radius

  predicate - a predicate used to filter results

  Returns:

  the collection of living entities near location. This will always be a non-null collection.

• getNearbyPlayers

  @NotNull public @NotNull Collection<Player> getNearbyPlayers(double radius)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  radius - X/Y/Z Radius

  Returns:

  the collection of players near location. This will always be a non-null collection.

• getNearbyPlayers

  @NotNull public @NotNull Collection<Player> getNearbyPlayers(double xzRadius, double yRadius)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xzRadius - X/Z Radius

  yRadius - Y Radius

  Returns:

  the collection of players near location. This will always be a non-null collection.

• getNearbyPlayers

  @NotNull public @NotNull Collection<Player> getNearbyPlayers(double xRadius, double yRadius, double zRadius)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xRadius - X Radius

  yRadius - Y Radius

  zRadius - Z Radius

  Returns:

  the collection of players near location. This will always be a non-null collection.

• getNearbyPlayers

  @NotNull public @NotNull Collection<Player> getNearbyPlayers(double radius, @Nullable @Nullable Predicate<? super Player> predicate)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  radius - X/Y/Z Radius

  predicate - a predicate used to filter results

  Returns:

  the collection of players near location. This will always be a non-null collection.

• getNearbyPlayers

  @NotNull public @NotNull Collection<Player> getNearbyPlayers(double xzRadius, double yRadius, @Nullable @Nullable Predicate<? super Player> predicate)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xzRadius - X/Z Radius

  yRadius - Y Radius

  predicate - a predicate used to filter results

  Returns:

  the collection of players near location. This will always be a non-null collection.

• getNearbyPlayers

  @NotNull public @NotNull Collection<Player> getNearbyPlayers(double xRadius, double yRadius, double zRadius, @Nullable @Nullable Predicate<? super Player> predicate)

  Gets nearby players within the specified radius (bounding box)

  Parameters:

  xRadius - X Radius

  yRadius - Y Radius

  zRadius - Z Radius

  predicate - a predicate used to filter results

  Returns:

  the collection of players near location. This will always be a non-null collection.

• getNearbyEntitiesByType

  @NotNull public <T extends Entity> @NotNull Collection<T> getNearbyEntitiesByType(@Nullable @Nullable Class<? extends T> clazz, double radius)

  Gets all nearby entities of the specified type, within the specified radius (bounding box)

  Type Parameters:

  T - the entity type

  Parameters:

  clazz - Type to filter by

  radius - X/Y/Z radius to search within

  Returns:

  the collection of entities of type clazz near location. This will always be a non-null collection.

• getNearbyEntitiesByType

  @NotNull public <T extends Entity> @NotNull Collection<T> getNearbyEntitiesByType(@Nullable @Nullable Class<? extends T> clazz, double xzRadius, double yRadius)

  Gets all nearby entities of the specified type, within the specified radius, with x and x radius matching (bounding box)

  Type Parameters:

  T - the entity type

  Parameters:

  clazz - Type to filter by

  xzRadius - X/Z radius to search within

  yRadius - Y radius to search within

  Returns:

  the collection of entities near location. This will always be a non-null collection.

• getNearbyEntitiesByType

  @NotNull public <T extends Entity> @NotNull Collection<T> getNearbyEntitiesByType(@Nullable @Nullable Class<? extends T> clazz, double xRadius, double yRadius, double zRadius)

  Gets all nearby entities of the specified type, within the specified radius (bounding box)

  Type Parameters:

  T - the entity type

  Parameters:

  clazz - Type to filter by

  xRadius - X Radius

  yRadius - Y Radius

  zRadius - Z Radius

  Returns:

  the collection of entities near location. This will always be a non-null collection.

• getNearbyEntitiesByType

  @NotNull public <T extends Entity> @NotNull Collection<T> getNearbyEntitiesByType(@Nullable @Nullable Class<? extends T> clazz, double radius, @Nullable @Nullable Predicate<? super T> predicate)

  Gets all nearby entities of the specified type, within the specified radius (bounding box)

  Type Parameters:

  T - the entity type

  Parameters:

  clazz - Type to filter by

  radius - X/Y/Z radius to search within

  predicate - a predicate used to filter results

  Returns:

  the collection of entities near location. This will always be a non-null collection.

• getNearbyEntitiesByType

  @NotNull public <T extends Entity> @NotNull Collection<T> getNearbyEntitiesByType(@Nullable @Nullable Class<? extends T> clazz, double xzRadius, double yRadius, @Nullable @Nullable Predicate<? super T> predicate)

  Gets all nearby entities of the specified type, within the specified radius, with x and x radius matching (bounding box)

  Type Parameters:

  T - the entity type

  Parameters:

  clazz - Type to filter by

  xzRadius - X/Z radius to search within

  yRadius - Y radius to search within

  predicate - a predicate used to filter results

  Returns:

  the collection of entities near location. This will always be a non-null collection.

• getNearbyEntitiesByType

  @NotNull public <T extends Entity> @NotNull Collection<T> getNearbyEntitiesByType(@Nullable @Nullable Class<? extends Entity> clazz, double xRadius, double yRadius, double zRadius, @Nullable @Nullable Predicate<? super T> predicate)

  Gets all nearby entities of the specified type, within the specified radius (bounding box)

  Type Parameters:

  T - the entity type

  Parameters:

  clazz - Type to filter by

  xRadius - X Radius

  yRadius - Y Radius

  zRadius - Z Radius

  predicate - a predicate used to filter results

  Returns:

  the collection of entities near location. This will always be a non-null collection.

• equals

  public boolean equals(Object obj)

  Overrides:

  equals in class Object

• hashCode

  public int hashCode()

  Overrides:

  hashCode in class Object

• toString

  public String toString()

  Overrides:

  toString in class Object

• toVector

  @NotNull public @NotNull Vector toVector()

  Constructs a new Vector based on this Location

  Specified by:

  toVector in interface Position

  Returns:

  New Vector containing the coordinates represented by this Location

• clone

  @NotNull public @NotNull Location clone()

  Overrides:

  clone in class Object

• checkFinite

  public void checkFinite() throws IllegalArgumentException

  Check if each component of this Location is finite.

  Throws:

  IllegalArgumentException - if any component is not finite

• locToBlock

  public static int locToBlock(double loc)

  Safely converts a double (location coordinate) to an int (block coordinate)

  Parameters:

  loc - Precise coordinate

  Returns:

  Block coordinate

• serialize

  @NotNull public @NotNull Map<String,Object> serialize()

  Description copied from interface: ConfigurationSerializable

  Creates a Map representation of this class.

  This class must provide a method to restore this class, as defined in the ConfigurationSerializable interface javadocs.

  Specified by:

  serialize in interface ConfigurationSerializable

  Returns:

  Map containing the current state of this class

• deserialize

  @NotNull public static @NotNull Location deserialize(@NotNull @NotNull Map<String,Object> args)

  Required method for deserialization

  Parameters:

  args - map to deserialize

  Returns:

  deserialized location

  Throws:

  IllegalArgumentException - if the world don't exists

  See Also:

  • ConfigurationSerializable

• normalizeYaw

  public static float normalizeYaw(float yaw)

  Normalizes the given yaw angle to a value between +/-180 degrees.

  Parameters:

  yaw - the yaw in degrees

  Returns:

  the normalized yaw in degrees

  See Also:

  • getYaw()

• normalizePitch

  public static float normalizePitch(float pitch)

  Normalizes the given pitch angle to a value between +/-90 degrees.

  Parameters:

  pitch - the pitch in degrees

  Returns:

  the normalized pitch in degrees

  See Also:

  • getPitch()

• x

  public double x()

  Description copied from interface: Position

  Gets the x value for this position

  Specified by:

  x in interface Position

  Returns:

  the x value

• y

  public double y()

  Description copied from interface: Position

  Gets the y value for this position

  Specified by:

  y in interface Position

  Returns:

  the y value

• z

  public double z()

  Description copied from interface: Position

  Gets the z value for this position

  Specified by:

  z in interface Position

  Returns:

  the z value

• isFinite

  public boolean isFinite()

  Description copied from interface: Position

  Checks if each component of this position is finite.

  Specified by:

  isFinite in interface Position

• toLocation

  @NotNull public @NotNull Location toLocation(@NotNull @NotNull World world)

  Description copied from interface: Position

  Creates a new location object at this position with the specified world

  Specified by:

  toLocation in interface Position

  Parameters:

  world - the world for the location object

  Returns:

  a new location