程序包 org.bukkit

类 Location

java.lang.Object
org.bukkit.Location
所有已实现的接口:
Cloneable, ConfigurationSerializable
public class Location extends Object implements Cloneable, ConfigurationSerializable
世界中的三维位置,包含x,y,z.
除了角度制只能是以度数为单位的限制外, 不对任何角度值施加任何约束. 这意味着负的角度值或大于360°的角度值也是有效的, 但可以将它们转化为其它任何等效的表示.
译注:yaw和pitch分别代表自转角(又称偏航角)、旋进角(又称进动角、俯仰角). 两个值一起表示位置的朝向(与向量的概念重合, 本类有很多方法就是与Vector重合的). 这里的翻译分别取偏航角、俯仰角. 另请参见util包下的Vector(向量)、EulerAngle(欧拉角).

  • 构造器详细资料

    • Location

      public Location(@Nullable @Nullable World world, double x, double y, double z)
      以给定的坐标构造一个Location对象.

      原文:Constructs a new Location with the given coordinates

      参数:
      world - 位置所在世界
      x - 位置x轴坐标
      y - 位置y轴坐标
      z - 位置z轴坐标

    • Location

      public Location(@Nullable @Nullable World world, double x, double y, double z, float yaw, float pitch)
      以给定的坐标和朝向构造一个Location对象.

      原文:Constructs a new Location with the given coordinates and direction

      参数:
      world - 位置所在世界
      x - 位置x轴坐标
      y - 位置y轴坐标
      z - 位置z轴坐标
      yaw - x轴平面上的绝对的旋转角度, 以度为单位
      pitch - y轴平面上的绝对的旋转角度, 以度为单位

  • 方法详细资料

    • setWorld

      public void setWorld(@Nullable @Nullable World world)
      设置本位置所在的世界.

      原文:Sets the world that this location resides in

      参数:
      world - 位置所在的新世界

    • isWorldLoaded

      public boolean isWorldLoaded()
      检查该位置所处世界是否存在并已加载.

      原文:Checks if world in this location is present and loaded.

      返回:
      true表示已加载

    • getWorld

      @Nullable public @Nullable World getWorld()
      获取本位置所在的世界.

      原文:Gets the world that this location resides in

      返回:
      世界, 若未设置返回null
      抛出:
      IllegalArgumentException - 当世界未加载时
      另请参阅:

    • getChunk

      @NotNull public @NotNull Chunk getChunk()
      获取此位置位于哪一区块.

      原文:Gets the chunk at the represented location

      返回:
      本位置所在区块

    • getBlock

      @NotNull public @NotNull Block getBlock()
      获取本位置对应的方块.

      原文:Gets the block at the represented location

      返回:
      所在位置对应的方块

    • setX

      public void setX(double x)
      设置本位置的x轴坐标.

      原文:Sets the x-coordinate of this location

      参数:
      x - x轴坐标

    • getX

      public double getX()
      获取本位置的x轴坐标.

      原文:Gets the x-coordinate of this location

      返回:
      x轴坐标

    • getBlockX

      public int getBlockX()
      获取向下取整的x轴坐标, 表示本位置包含的方块.

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

      返回:
      方块x轴坐标

    • setY

      public void setY(double y)
      设置本位置的y轴坐标.

      原文:Sets the y-coordinate of this location

      参数:
      y - y轴坐标

    • getY

      public double getY()
      获取本位置的y轴坐标.

      原文:Gets the y-coordinate of this location

      返回:
      y轴坐标

    • getBlockY

      public int getBlockY()
      获取向下取整的y轴坐标, 表示本位置包含的方块.

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

      返回:
      方块y轴坐标

    • setZ

      public void setZ(double z)
      设置本位置的z坐标轴.

      原文:Sets the z-coordinate of this location

      参数:
      z - z坐标轴

    • getZ

      public double getZ()
      获取本位置的z坐标轴.

      原文:Gets the z-coordinate of this location

      返回:
      z坐标轴

    • getBlockZ

      public int getBlockZ()
      获取向下取整的z轴坐标, 表示本位置包含的方块.

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

      返回:
      方块z轴坐标

    • setYaw

      public void setYaw(float yaw)
      设置本位置的偏航角(yaw), 以度为单位.
      • 偏航角为0或360°时表示z轴正方向.
      • 偏航角为180°时表示z轴负方向.
      • 偏航角为90°时表示x轴负方向.
      • 偏航角为270°时表示x轴正方向.
      增加偏航角值相当于使你转向右侧, 增加偏向下一个坐标轴的比例并减少偏向前一个轴的比例.

      原文: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.
      参数:
      yaw - 自转角(偏航角)

    • getYaw

      public float getYaw()
      获取本位置的偏航角(yaw), 以度为单位.
      • 偏航角为0或360°时表示z轴正方向.
      • 偏航角为180°时表示z轴负方向.
      • 偏航角为90°时表示x轴负方向.
      • 偏航角为270°时表示x轴正方向.
      增加偏航角值相当于使你转向右侧, 增加偏向下一个坐标轴的比例并减少偏向前一个轴的比例.

      原文: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.
      返回:
      自转角(偏航角)

    • setPitch

      public void setPitch(float pitch)
      设置本位置的俯仰角(pitch), 以度为单位.
      • 俯仰角为0时表示水平朝向.
      • 俯仰角为90°时表示向下的朝向,或y轴的负方向
      • 俯仰角为-90°时表示向上的朝向,或y轴的正方向
      增加俯仰角值相当于俯视的效果.

      原文: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.
      参数:
      pitch - 倾斜角(俯仰角)

    • getPitch

      public float getPitch()
      获取本位置的俯仰角(pitch), 以度为单位.
      • 俯仰角为0时表示水平朝向.
      • 俯仰角为90°时表示向下的朝向,或y轴的负方向
      • 俯仰角为-90°时表示向上的朝向,或y轴的正方向
      增加俯仰角值相当于俯视的效果.

      原文: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.
      返回:
      倾斜角(俯仰角)

    • getDirection

      @NotNull public @NotNull Vector getDirection()
      获取本位置所面向的方向的单位向量.

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

      返回:
      指向此位置的偏航角和俯仰角的向量

    • setDirection

      @NotNull public @NotNull Location setDirection(@NotNull @NotNull Vector vector)
      将偏航角和俯仰角设为指向某一向量的方向.

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

      参数:
      vector - 方向向量
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)

    • add

      @NotNull public @NotNull Location add(@NotNull @NotNull Location vec)
      将本位置的坐标加上另一个位置的坐标.

      原文:Adds the location by another.

      参数:
      vec - 另一个位置
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      抛出:
      IllegalArgumentException - 若两个位置所处世界各不相同
      另请参阅:

    • add

      @NotNull public @NotNull Location add(@NotNull @NotNull Vector vec)
      将本位置的坐标加上一个向量的坐标.

      原文:Adds the location by a vector.

      参数:
      vec - 向量
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      另请参阅:

    • add

      @NotNull public @NotNull Location add(double x, double y, double z)
      将本位置的坐标加上另一个位置的坐标. 与位置所处世界无关.

      原文:Adds the location by another. Not world-aware.

      参数:
      x - X坐标
      y - Y坐标
      z - Z坐标
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      另请参阅:

    • subtract

      @NotNull public @NotNull Location subtract(@NotNull @NotNull Location vec)
      将本位置的坐标减去另一个位置的坐标.

      原文:Subtracts the location by another.

      参数:
      vec - 另一个位置
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      抛出:
      IllegalArgumentException - 若两个位置所处世界各不相同
      另请参阅:

    • subtract

      @NotNull public @NotNull Location subtract(@NotNull @NotNull Vector vec)
      从本位置的坐标中减去向量的坐标.

      原文:Subtracts the location by a vector.

      参数:
      vec - 向量
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      另请参阅:

    • subtract

      @NotNull public @NotNull Location subtract(double x, double y, double z)
      从本位置的坐标中减去另一个位置的坐标. 与位置所处世界无关且其方向角独立不参与运算.

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

      参数:
      x - X坐标
      y - Y坐标
      z - Z坐标
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      另请参阅:

    • length

      public double length()
      获取位置的模值,定义为 sqrt(x^2+y^2+z^2). 这个方法的返回值没有被缓存,且使用了开销较大的平方以及开根函数, 所以不要反复调用这个方法来获取向量的模值. 当向量的模过大时,开根函数有可能发生溢出,并会返回Double.NaN. 与位置所处世界无关且其方向角独立不参与运算.

      原文: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.

      返回:
      模
      另请参阅:

    • lengthSquared

      public double lengthSquared()
      获取位置长度(又称模)的平方 (三个坐标分别平方然后加起来). 与位置所处世界无关且其方向角独立不参与运算.

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

      返回:
      模的平方
      另请参阅:

    • distance

      public double distance(@NotNull @NotNull Location o)
      获取本位置与与另一个位置之间的距离. 这个方法的返回值没有被缓存,且使用了开销较大的平方以及开根函数, 所以不要反复调用这个方法来获取位置的模值. 当位置的距离过大时,开根函数有可能发生溢出,并会返回Double.NaN.

      原文: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.

      参数:
      o - The other location
      返回:
      the distance
      抛出:
      IllegalArgumentException - for differing worlds
      另请参阅:

    • distanceSquared

      public double distanceSquared(@NotNull @NotNull Location o)
      获取本位置与与另一个位置之间的距离的平方.

      原文:Get the squared distance between this location and another.

      参数:
      o - 另一个位置
      返回:
      距离的平方
      抛出:
      IllegalArgumentException - 若两个位置所处世界各不相同
      另请参阅:

    • multiply

      @NotNull public @NotNull Location multiply(double m)
      坐标数乘, 将所有坐标轴上扩展某个倍数.

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

      参数:
      m - 因数,即数乘的倍数,整数
      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      另请参阅:

    • zero

      @NotNull public @NotNull Location zero()
      清零此位置的xyz坐标数值. 与位置所处世界无关.

      原文:Zero this location's components. Not world-aware.

      返回:
      相同的位置对象(不是位置相同,但位置对象相同)
      另请参阅:

    • equals

      public boolean equals(Object obj)
      覆盖:
      equals 在类中 Object

    • hashCode

      public int hashCode()
      覆盖:
      hashCode 在类中 Object

    • toString

      public String toString()
      覆盖:
      toString 在类中 Object

    • toVector

      @NotNull public @NotNull Vector toVector()
      基于此位置构造一个新的向量.

      原文:Constructs a new Vector based on this Location

      返回:
      包含该位置坐标的向量表示

    • clone

      @NotNull public @NotNull Location clone()
      覆盖:
      clone 在类中 Object

    • checkFinite

      public void checkFinite() throws IllegalArgumentException
      检测该Location的xyz坐标和偏航角、俯仰角是否合法 (限制的最大值为Double.MAX_VALUE).

      原文:Check if each component of this Location is finite.

      抛出:
      IllegalArgumentException - 若有任意一个坐标/角度值不合法时抛出

    • locToBlock

      public static int locToBlock(double loc)
      把double类型数值(位置坐标)安全地转换为int类型数值(方块坐标).

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

      参数:
      loc - 精确坐标
      返回:
      方块坐标

    • serialize

      @NotNull public @NotNull Map<String,Object> serialize()
      从接口复制的说明: 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.

      指定者:
      serialize 在接口中 ConfigurationSerializable
      返回:
      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

      参数:
      args - 需要反序列化的map
      返回:
      反序列化后的位置
      抛出:
      IllegalArgumentException - 如果位置所处世界不存在
      另请参阅:

    • normalizeYaw

      public static float normalizeYaw(float yaw)
      将给定的偏航角归一化至+/-180范围内.

      译注:比如角度值的绝对值大于180, 用此方法可使角度的绝对值在0-180以内.

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

      参数:
      yaw - 偏航角, 使用角度制
      返回:
      标准化的偏航角, 使用角度制
      另请参阅:

    • normalizePitch

      public static float normalizePitch(float pitch)
      将给定的俯仰角归一化至+/-180范围内.

      译注:比如角度值的绝对值大于180, 用此方法可使角度的绝对值在0-180以内.

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

      参数:
      pitch - 俯仰角, 使用角度制
      返回:
      标准化的俯仰角, 使用角度制
      另请参阅: