Location (Bukkit 1.12.2-R0.1-SNAPSHOT API 中文文档)

java.lang.Object
- org.bukkit.Location

所有已实现的接口:

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

构造器概要

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

方法概要

所有方法静态方法实例方法具体方法
限定符和类型	方法和说明
`Location`	`add(double x, double y, double z)` 将本位置的坐标加上另一个位置的坐标.
`Location`	`add(Location vec)` 将本位置的坐标加上另一个位置的坐标.
`Location`	`add(Vector vec)` 将本位置的坐标加上一个向量的坐标.
`void`	`checkFinite()` 检测该Location的xyz坐标和偏航角、俯仰角是否合法 (限制的最大值为Double.MAX_VALUE).
`Location`	`clone()`
`static Location`	`deserialize(java.util.Map<java.lang.String,java.lang.Object> args)` 实现配置序列化与反序列化所需方法.
`double`	`distance(Location o)` 获取本位置与与另一个位置之间的距离.
`double`	`distanceSquared(Location o)` 获取本位置与与另一个位置之间的距离的平方.
`boolean`	`equals(java.lang.Object obj)`
`Block`	`getBlock()` 获取本位置对应的方块.
`int`	`getBlockX()` 获取向下取整的x轴坐标, 表示本位置包含的方块.
`int`	`getBlockY()` 获取向下取整的y轴坐标, 表示本位置包含的方块.
`int`	`getBlockZ()` 获取向下取整的z轴坐标, 表示本位置包含的方块.
`Chunk`	`getChunk()` 获取此位置位于哪一区块.
`Vector`	`getDirection()` 获取本位置所面向的方向的单位向量.
`float`	`getPitch()` 获取本位置的俯仰角(pitch), 以度为单位.
`World`	`getWorld()` 获取本位置所在的世界.
`double`	`getX()` 获取本位置的x轴坐标.
`double`	`getY()` 获取本位置的y轴坐标.
`float`	`getYaw()` 获取本位置的偏航角(yaw), 以度为单位.
`double`	`getZ()` 获取本位置的z坐标轴.
`int`	`hashCode()`
`double`	`length()` 获取位置的模值,定义为 sqrt(x^2+y^2+z^2).
`double`	`lengthSquared()` 获取位置长度(又称模)的平方 (三个坐标分别平方然后加起来).
`static int`	`locToBlock(double loc)` 把double类型数值(位置坐标)安全地转换为int类型数值(方块坐标).
`Location`	`multiply(double m)` 坐标数乘, 将所有坐标轴上扩展某个倍数.
`java.util.Map<java.lang.String,java.lang.Object>`	`serialize()` Creates a Map representation of this class.
`Location`	`setDirection(Vector vector)` 将`偏航角`和`俯仰角`设为指向某一向量的方向.
`void`	`setPitch(float pitch)` 设置本位置的俯仰角(pitch), 以度为单位.
`void`	`setWorld(World world)` 设置本位置所在的世界.
`void`	`setX(double x)` 设置本位置的x轴坐标.
`void`	`setY(double y)` 设置本位置的y轴坐标.
`void`	`setYaw(float yaw)` 设置本位置的偏航角(yaw), 以度为单位.
`void`	`setZ(double z)` 设置本位置的z坐标轴.
`Location`	`subtract(double x, double y, double z)` 从本位置的坐标中减去另一个位置的坐标.
`Location`	`subtract(Location vec)` 将本位置的坐标减去另一个位置的坐标.
`Location`	`subtract(Vector vec)` 从本位置的坐标中减去向量的坐标.
`java.lang.String`	`toString()`
`Vector`	`toVector()` 基于此位置构造一个新的`向量`.
`Location`	`zero()` 清零此位置的xyz坐标数值.

从类继承的方法 java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- 构造器详细资料
  - Location
```
public Location(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(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(World world)
```
    设置本位置所在的世界.
    原文:Sets the world that this location resides in
    
    参数:
    
    world - 位置所在的新世界
  - getWorld
```
public World getWorld()
```
    获取本位置所在的世界.
    原文:Gets the world that this location resides in
    
    返回:
    
    世界
  - getChunk
```
public Chunk getChunk()
```
    获取此位置位于哪一区块.
    原文:Gets the chunk at the represented location
    
    返回:
    
    本位置所在区块
  - getBlock
```
public 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
```
public Vector getDirection()
```
    获取本位置所面向的方向的单位向量.
    原文:Gets a unit-vector pointing in the direction that this Location is facing.
    
    返回:
    
    指向此位置的偏航角和俯仰角的向量
  - setDirection
```
public Location setDirection(Vector vector)
```
    将偏航角和俯仰角设为指向某一向量的方向.
    原文:Sets the yaw and pitch to point in the direction of the vector.
    
    参数:
    
    vector - 方向向量
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
  - add
```
public Location add(Location vec)
```
    将本位置的坐标加上另一个位置的坐标.
    原文:Adds the location by another.
    
    参数:
    
    vec - 另一个位置
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
    
    抛出:
    
    java.lang.IllegalArgumentException - 若两个位置所处世界各不相同
    
    另请参阅:
    
    Vector
  - add
```
public Location add(Vector vec)
```
    将本位置的坐标加上一个向量的坐标.
    原文:Adds the location by a vector.
    
    参数:
    
    vec - 向量
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
    
    另请参阅:
    
    Vector
  - add
```
public Location add(double x,
                    double y,
                    double z)
```
    将本位置的坐标加上另一个位置的坐标. 与位置所处世界无关.
    原文:Adds the location by another. Not world-aware.
    
    参数:
    
    x - X坐标
    
    y - Y坐标
    
    z - Z坐标
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
    
    另请参阅:
    
    Vector
  - subtract
```
public Location subtract(Location vec)
```
    将本位置的坐标减去另一个位置的坐标.
    原文:Subtracts the location by another.
    
    参数:
    
    vec - 另一个位置
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
    
    抛出:
    
    java.lang.IllegalArgumentException - 若两个位置所处世界各不相同
    
    另请参阅:
    
    Vector
  - subtract
```
public Location subtract(Vector vec)
```
    从本位置的坐标中减去向量的坐标.
    原文:Subtracts the location by a vector.
    
    参数:
    
    vec - 向量
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
    
    另请参阅:
    
    Vector
  - subtract
```
public Location subtract(double x,
                         double y,
                         double z)
```
    从本位置的坐标中减去另一个位置的坐标. 与位置所处世界无关且其方向角独立不参与运算.
    原文:Subtracts the location by another. Not world-aware and orientation independent.
    
    参数:
    
    x - X coordinate
    
    y - Y coordinate
    
    z - Z coordinate
    
    返回:
    
    the same location
    
    另请参阅:
    
    Vector
  - 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.
    
    返回:
    
    模
    
    另请参阅:
    
    Vector
  - lengthSquared
```
public double lengthSquared()
```
    获取位置长度(又称模)的平方 (三个坐标分别平方然后加起来). 与位置所处世界无关且其方向角独立不参与运算.
    原文:Gets the magnitude of the location squared. Not world-aware and orientation independent.
    
    返回:
    
    模的平方
    
    另请参阅:
    
    Vector
  - distance
```
public double distance(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
    
    抛出:
    
    java.lang.IllegalArgumentException - for differing worlds
    
    另请参阅:
    
    Vector
  - distanceSquared
```
public double distanceSquared(Location o)
```
    获取本位置与与另一个位置之间的距离的平方.
    原文:Get the squared distance between this location and another.
    
    参数:
    
    o - 另一个位置
    
    返回:
    
    距离的平方
    
    抛出:
    
    java.lang.IllegalArgumentException - 若两个位置所处世界各不相同
    
    另请参阅:
    
    Vector
  - multiply
```
public Location multiply(double m)
```
    坐标数乘, 将所有坐标轴上扩展某个倍数.
    原文:Performs scalar multiplication, multiplying all components with a scalar. Not world-aware.
    
    参数:
    
    m - 因数,即数乘的倍数,整数
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
    
    另请参阅:
    
    Vector
  - zero
```
public Location zero()
```
    清零此位置的xyz坐标数值. 与位置所处世界无关.
    原文:Zero this location's components. Not world-aware.
    
    返回:
    
    相同的位置对象(不是位置相同,但位置对象相同)
    
    另请参阅:
    
    Vector
  - equals
```
public boolean equals(java.lang.Object obj)
```
    覆盖:
    
    equals 在类中 java.lang.Object
  - hashCode
```
public int hashCode()
```
    覆盖:
    
    hashCode 在类中 java.lang.Object
  - toString
```
public java.lang.String toString()
```
    覆盖:
    
    toString 在类中 java.lang.Object
  - toVector
```
public Vector toVector()
```
    基于此位置构造一个新的向量.
    原文:Constructs a new Vector based on this Location
    
    返回:
    
    包含该位置坐标的向量表示
  - clone
```
public Location clone()
```
    覆盖:
    
    clone 在类中 java.lang.Object
  - checkFinite
```
public void checkFinite()
                 throws java.lang.IllegalArgumentException
```
    检测该Location的xyz坐标和偏航角、俯仰角是否合法 (限制的最大值为Double.MAX_VALUE).
    原文:Check if each component of this Location is finite.
    
    抛出:
    
    java.lang.IllegalArgumentException - 若有任意一个坐标/角度值不合法时抛出
  - locToBlock
```
public static int locToBlock(double loc)
```
    把double类型数值(位置坐标)安全地转换为int类型数值(方块坐标).
    原文:Safely converts a double (location coordinate) to an int (block coordinate)
    
    参数:
    
    loc - 精确坐标
    
    返回:
    
    方块坐标
  - serialize
```
public java.util.Map<java.lang.String,java.lang.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
```
public static Location deserialize(java.util.Map<java.lang.String,java.lang.Object> args)
```
    实现配置序列化与反序列化所需方法.
    原文:Required method for deserialization
    
    参数:
    
    args - 需要反序列化的map
    
    返回:
    
    反序列化后的位置
    
    抛出:
    
    java.lang.IllegalArgumentException - 如果位置所处世界不存在
    
    另请参阅:
    
    ConfigurationSerializable

类 Location

构造器概要

方法概要

从类继承的方法 java.lang.Object

构造器详细资料

Location

Location

方法详细资料

setWorld

getWorld

getChunk

getBlock

setX

getX

getBlockX

setY

getY

getBlockY

setZ

getZ

getBlockZ

setYaw

getYaw

setPitch

getPitch

getDirection

setDirection

add

add

add

subtract

subtract

subtract

length

lengthSquared

distance

distanceSquared

multiply

zero

equals

hashCode

toString

toVector

clone

checkFinite

locToBlock

serialize

deserialize