程序包 org.bukkit.block

# 接口 Block

所有超级接口:
  `Metadatable`, `Translatable`

public interface Block extends Metadatable, Translatable
代表一个方块.

这是一种动态的对象, 在同一个世界的同一个位置只可以存在一个方块.

方块的一个实例可能会根据你对这个方块的一些操作而改变, 可以使用block.getState()来获取一个静态的, 不会被修改的Block对象.

需要注意的是, 在世界生成的过程中调用这个类可能是不安全的, 比如BlockPhysicsEvent事件!!!!

原文: Represents a block. This is a live object, and only one Block may exist for any given location in a world. The state of the block may change concurrently to your own handling of it; use block.getState() to get a snapshot state of a block which will not be modified.
Note that parts of this class which require access to the world at large (i.e. lighting and power) may not be able to be safely accessed during world generation when used in cases like BlockPhysicsEvent!!!!

- ## 方法概要

  修饰符和类型
  方法
  说明
  `boolean`
  `applyBoneMeal(@NotNull BlockFace face)`
  模拟使用骨粉向本方块施肥 (若可能).
  `boolean`
  `breakNaturally()`
  破坏此方块并生成掉落物, 就像是玩家不使用工具时挖掘方块一样.
  `boolean`
  `breakNaturally(@Nullable ItemStack tool)`
  破坏此方块并生成掉落物, 就像是玩家手持工具挖掘方块一样.
  `boolean`
  `canPlace(@NotNull BlockData data)`
  Checks if this block is a valid placement location for the specified block data.
  `@NotNull Biome`
  `getBiome()`
  返回方块所在位置的生物群系.
  `@NotNull BlockData`
  `getBlockData()`
  获取这个方块的完整方块数据.
  `int`
  `getBlockPower()`
  返回提供给此方块的红石充能等级.
  `int`
  `getBlockPower(@NotNull BlockFace face)`
  返回提供给方块某一面的红石充能等级.
  `@NotNull BoundingBox`
  `getBoundingBox()`
  Gets the approximate bounding box for this block.
  `float`
  `getBreakSpeed(@NotNull Player player)`
  Gets the speed at which the given player would break this block, taking into account tools, potion effects, whether or not the player is in water, enchantments, etc.
  `@NotNull Chunk`
  `getChunk()`
  获取此方块所在的区块.
  `@NotNull VoxelShape`
  `getCollisionShape()`
  Gets the collision shape of this block.
  `byte`
  `getData()`
  已过时。
  不安全的参数
  `@NotNull Collection<ItemStack>`
  `getDrops()`
  返回当破坏此方块时掉落的物品.
  `@NotNull Collection<ItemStack>`
  `getDrops(@NotNull ItemStack tool, @Nullable Entity entity)`
  返回当某实体使用某工具破坏此方块时掉落的物品.
  `@NotNull Collection<ItemStack>`
  `getDrops(@Nullable ItemStack tool)`
  返回当使用特定工具破坏此方块时掉落的物品.
  `@Nullable BlockFace`
  `getFace(@NotNull Block block)`
  获取本方块的哪一面朝向给定的方块.
  `double`
  `getHumidity()`
  获取方块所在生物群系的环境湿度.
  `byte`
  `getLightFromBlocks()`
  获取从方块照到这个方块上的光源亮度等级.
  `byte`
  `getLightFromSky()`
  获取从天空中照到此方块上的光照亮度等级.
  `byte`
  `getLightLevel()`
  获取这个方块的发光的亮度等级 (0-15).
  `@NotNull Location`
  `getLocation()`
  获取这个方块的位置.
  `@Nullable Location`
  `getLocation(@Nullable Location loc)`
  存储此方块的位置到到给定的位置实例中.
  `@NotNull PistonMoveReaction`
  `getPistonMoveReaction()`
  返回当此方块被活塞推动时的反应.
  `@NotNull Block`
  `getRelative(int modX, int modY, int modZ)`
  以此方块为基点, 在指定的偏移量上获取方块.
  `@NotNull Block`
  `getRelative(@NotNull BlockFace face)`
  获取这个方块某一面上紧邻的方块.
  `@NotNull Block`
  `getRelative(@NotNull BlockFace face, int distance)`
  获取这个方块某一面上指定距离的方块.
  `@NotNull BlockState`
  `getState()`
  捕获本方块当前的状态.
  `double`
  `getTemperature()`
  获取方块所在生物群系的环境温度.
  `@NotNull Material`
  `getType()`
  获取这个方块的材质种类.
  `@NotNull World`
  `getWorld()`
  获取这个方块所在的世界.
  `int`
  `getX()`
  获取这个方块的X轴坐标.
  `int`
  `getY()`
  获取这个方块的Y轴坐标.
  `int`
  `getZ()`
  获取这个方块的Z轴坐标.
  `boolean`
  `isBlockFaceIndirectlyPowered(@NotNull BlockFace face)`
  返回方块的其中一面是否被红石间接充能.
  `boolean`
  `isBlockFacePowered(@NotNull BlockFace face)`
  返回方块的其中一面是否被红石充能.
  `boolean`
  `isBlockIndirectlyPowered()`
  返回方块是否被红石间接充能.
  `boolean`
  `isBlockPowered()`
  返回方块是否被红石充能.
  `boolean`
  `isEmpty()`
  检测此方块是否为空.
  `boolean`
  `isLiquid()`
  检测方块是否为流体.
  `boolean`
  `isPassable()`
  检测能否自由通过此方块.
  `boolean`
  `isPreferredTool(@NotNull ItemStack tool)`
  Returns if the given item is a preferred choice to break this Block.
  `@Nullable RayTraceResult`
  `rayTrace(@NotNull Location start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode)`
  Performs a ray trace that checks for collision with this specific block in its current state using its precise collision shape.
  `void`
  `setBiome(@NotNull Biome bio)`
  设置方块所在位置的生物群系.
  `void`
  `setBlockData(@NotNull BlockData data)`
  设置此方块的BlockData.
  `void`
  `setBlockData(@NotNull BlockData data, boolean applyPhysics)`
  设置一个方块的BlockData, 并决定是否应用重力 (译者注: 更新方块的意思，如沙不掉落).
  `void`
  `setType(@NotNull Material type)`
  设置这个方块的材质种类.
  `void`
  `setType(@NotNull Material type, boolean applyPhysics)`
  设置一个方块的材质种类, 并决定是否应用重力 (译者注: 更新方块的意思, 如沙不掉落).

  ### 从接口继承的方法 org.bukkit.metadata.Metadatable

  `getMetadata, hasMetadata, removeMetadata, setMetadata`

  ### 从接口继承的方法 org.bukkit.Translatable

  `getTranslationKey`

- ## 方法详细资料

  - ### getData

    @Deprecated byte getData()
    已过时。
    不安全的参数
    获取这个方块的元数据.

    原文: Gets the metadata for this block

    返回:
      方块元数据

  - ### getBlockData

    @NotNull @NotNull BlockData getBlockData()
    获取这个方块的完整方块数据.

    原文: Gets the complete block data for this block

    返回:
      方块数据

  - ### getRelative

    @NotNull @NotNull Block getRelative(int modX, int modY, int modZ)
    以此方块为基点, 在指定的偏移量上获取方块.

    原文: Gets the block at the given offsets

    参数:
      `modX` - X-coordinate offset
      `modY` - Y-coordinate offset
      `modZ` - Z-coordinate offset
    返回:
      指定偏移量位置上的方块

  - ### getRelative

    @NotNull @NotNull Block getRelative(@NotNull @NotNull BlockFace face)
    获取这个方块某一面上紧邻的方块.

    此方法等同于getRelative(face, 1).

    原文: Gets the block at the given face

    This method is equal to getRelative(face, 1)

    参数:
      `face` - 方块的哪一面
    返回:
      此面上紧邻的方块
    另请参阅:
      - `getRelative(BlockFace, int)`

  - ### getRelative

    @NotNull @NotNull Block getRelative(@NotNull @NotNull BlockFace face, int distance)
    获取这个方块某一面上指定距离的方块.

    一个例子, 如果我要在一个方块的上面3格放置一个水方块.

         Block block = world.getBlockAt(100, 100, 100); //获取到方块
         Block shower = block.getRelative(BlockFace.UP, 2); //获取这个方块UP(上)面的2格的方块
         shower.setType(Material.WATER); //设置这个方块为水

    原文: Gets the block at the given distance of the given face

    For example, the following method places water at 100,102,100; two blocks above 100,100,100.

         Block block = world.getBlockAt(100, 100, 100);
         Block shower = block.getRelative(BlockFace.UP, 2);
         shower.setType(Material.WATER);

    参数:
      `face` - 方块的哪一面
      `distance` - 距离
    返回:
      位于指定朝向指定距离的方块

  - ### getType

    @NotNull @NotNull Material getType()
    获取这个方块的材质种类.

    原文: Gets the type of this block

    返回:
      方块类型

  - ### getLightLevel

    byte getLightLevel()
    获取这个方块的发光的亮度等级 (0-15).

    译注: 如果这个方块不发光则返回0.

    原文: Gets the light level between 0-15

    返回:
      亮度等级

  - ### getLightFromSky

    byte getLightFromSky()
    获取从天空中照到此方块上的光照亮度等级.

    会忽略掉来自方块(火把、萤石等)的光源.

    原文: Get the amount of light at this block from the sky.

    Any light given from other sources (such as blocks like torches) will be ignored.

    返回:
      光照亮度等级

  - ### getLightFromBlocks

    byte getLightFromBlocks()
    获取从方块照到这个方块上的光源亮度等级.

    会忽略掉来自非方块(太阳光等)的光源.

    原文: Get the amount of light at this block from nearby blocks.

    Any light given from other sources (such as the sun) will be ignored.

    返回:
      光源亮度等级

  - ### getWorld

    @NotNull @NotNull World getWorld()
    获取这个方块所在的世界.

    原文: Gets the world which contains this Block

    返回:
      World containing this block

  - ### getX

    int getX()
    获取这个方块的X轴坐标.

    原文: Gets the x-coordinate of this block

    返回:
      x-coordinate

  - ### getY

    int getY()
    获取这个方块的Y轴坐标.

    原文: Gets the y-coordinate of this block

    返回:
      y-coordinate

  - ### getZ

    int getZ()
    获取这个方块的Z轴坐标.

    原文: Gets the z-coordinate of this block

    返回:
      z-coordinate

  - ### getLocation

    @NotNull @NotNull Location getLocation()
    获取这个方块的位置.

    原文: Gets the Location of the block

    返回:
      方块的位置

  - ### getLocation

    @Contract("null -> null; !null -> !null") @Nullable @Nullable Location getLocation(@Nullable @Nullable Location loc)
    存储此方块的位置到到给定的位置实例中.

    如果给定的位置实例为null, 则将不进行任何操作并返回null.

    译注:下面是译者的一个例子

         Location loc = new Location(World, 15, 255, 14);
         Block block = World2.getBlockAt(28, 25, -18);
         loc = block.getLocation(loc)
         // 此时，loc的值为(World2, 28, 25, -18) 基本等效于 loc = block.getLocation()

    原文: Stores the location of the block in the provided Location object.

    If the provided Location is null this method does nothing and returns null.

    参数:
      `loc` - 要复制入的位置实例
    返回:
      给定的位置实例/null

  - ### getChunk

    @NotNull @NotNull Chunk getChunk()
    获取此方块所在的区块.

    原文: Gets the chunk which contains this block

    返回:
      方块所在的区块

  - ### setBlockData

    void setBlockData(@NotNull @NotNull BlockData data)
    设置此方块的BlockData.

    原文: Sets the complete data for this block

    参数:
      `data` - 新方块数据

  - ### setBlockData

    void setBlockData(@NotNull @NotNull BlockData data, boolean applyPhysics)
    设置一个方块的BlockData, 并决定是否应用重力 (译者注: 更新方块的意思，如沙不掉落).
    请注意, applyPhysics = false 有时并不安全. 只有你需要避免周围方块的更新才应该使用这个参数. 例如在创建一个 `Bisected` 方块时或者在使用自定义的 BlockPopulator 防止触发无限连锁更新的时候.

    不要使用这个方法来在一些 “不可能放置方块的地方” 放置方块. 即使可以成功放置, 这些方块也会在之后被移除. 如果把大量这种方块放置在很接近的地方可能会使服务器物理引擎过载奔溃.

    原文: Sets the complete data for this block
    Note that applyPhysics = false is not in general safe. It should only be used when you need to avoid triggering a physics update of neighboring blocks, for example when creating a `Bisected` block. If you are using a custom populator, then this parameter may also be required to prevent triggering infinite chunk loads on border blocks. This method should NOT be used to "hack" physics by placing blocks in impossible locations. Such blocks are liable to be removed on various events such as world upgrades. Furthermore setting large amounts of such blocks in close proximity may overload the server physics engine if an update is triggered at a later point. If this occurs, the resulting behavior is undefined.

    参数:
      `data` - 新方块数据
      `applyPhysics` - false 以取消方块的物理规则

  - ### setType

    void setType(@NotNull @NotNull Material type)
    设置这个方块的材质种类.

    原文: Sets the type of this block

    参数:
      `type` - 材质种类

  - ### setType

    void setType(@NotNull @NotNull Material type, boolean applyPhysics)
    设置一个方块的材质种类, 并决定是否应用重力 (译者注: 更新方块的意思, 如沙不掉落).
    请注意, applyPhysics = false 有时并不安全. 只有你需要避免周围方块的更新才应该使用这个参数. 例如在创建一个 `Bisected` 方块时或者在使用自定义的 BlockPopulator 防止触发无限连锁更新的时候.

    不要使用这个方法来在一些 “不可能放置方块的地方” 放置方块. 即使可以成功放置, 这些方块也会在之后被移除. 如果把大量这种方块放置在很接近的地方可能会使服务器物理引擎过载奔溃.

    原文: Sets the type of this block
    Note that applyPhysics = false is not in general safe. It should only be used when you need to avoid triggering a physics update of neighboring blocks, for example when creating a `Bisected` block. If you are using a custom populator, then this parameter may also be required to prevent triggering infinite chunk loads on border blocks. This method should NOT be used to "hack" physics by placing blocks in impossible locations. Such blocks are liable to be removed on various events such as world upgrades. Furthermore setting large amounts of such blocks in close proximity may overload the server physics engine if an update is triggered at a later point. If this occurs, the resulting behavior is undefined.

    参数:
      `type` - 材质种类
      `applyPhysics` - false 以取消方块的物理规则

  - ### getFace

    @Nullable @Nullable BlockFace getFace(@NotNull @NotNull Block block)
    获取本方块的哪一面朝向给定的方块.

    例如:

         Block current = world.getBlockAt(100, 100, 100); // 本方块
         Block target = world.getBlockAt(100, 101, 100); // 目标方块

         current.getFace(target) == BlockFace.Up; // 朝上

    如果给定方块不与本方块相连接, 将可能返回 null.

    原文:Gets the face relation of this block compared to the given block.

    For example:

         Block current = world.getBlockAt(100, 100, 100);
         Block target = world.getBlockAt(100, 101, 100);

         current.getFace(target) == BlockFace.Up;

    If the given block is not connected to this block, null may be returned
    参数:
      `block` - 要比较的方块
    返回:
      本方块相对于给定方块的朝向, 或为 null

  - ### getState

    @NotNull @NotNull BlockState getState()
    捕获本方块当前的状态. 你可以将此状态转换为任意可接受的类型的状态, 例如, 转为 `Furnace` 或 `Sign`.

    返回的对象将永不更新 (注:可以理解为方块在某一时刻的状态的快照), 并且你不能保证(举个例子)在你捕获此告示牌状态后此告示牌依然是告示牌.

    原文:Captures the current state of this block. You may then cast that state into any accepted type, such as Furnace or Sign.

    The returned object will never be updated, and you are not guaranteed that (for example) a sign is still a sign after you capture its state.

    返回:
      本方块当前的状态的 BlockState 对象

  - ### getBiome

    @NotNull @NotNull Biome getBiome()
    返回方块所在位置的生物群系.

    原文:Returns the biome that this block resides in

    返回:
      生物群系

  - ### setBiome

    void setBiome(@NotNull @NotNull Biome bio)
    设置方块所在位置的生物群系.

    原文:Sets the biome that this block resides in

    参数:
      `bio` - 新的生物群系

  - ### isBlockPowered

    boolean isBlockPowered()
    返回方块是否被红石充能.

    原文:Returns true if the block is being powered by Redstone.

    返回:
      是否被充能

  - ### isBlockIndirectlyPowered

    boolean isBlockIndirectlyPowered()
    返回方块是否被红石间接充能.

    原文:Returns true if the block is being indirectly powered by Redstone.

    返回:
      是否被间接充能

  - ### isBlockFacePowered

    boolean isBlockFacePowered(@NotNull @NotNull BlockFace face)
    返回方块的其中一面是否被红石充能.

    原文:Returns true if the block face is being powered by Redstone.

    参数:
      `face` - 方块的面
    返回:
      此面是否被充能

  - ### isBlockFaceIndirectlyPowered

    boolean isBlockFaceIndirectlyPowered(@NotNull @NotNull BlockFace face)
    返回方块的其中一面是否被红石间接充能.

    原文:Returns true if the block face is being indirectly powered by Redstone.

    参数:
      `face` - 方块的面
    返回:
      此面是否被间接充能

  - ### getBlockPower

    int getBlockPower(@NotNull @NotNull BlockFace face)
    返回提供给方块某一面的红石充能等级.

    原文:Returns the redstone power being provided to this block face

    参数:
      `face` - 要查询的方块的面或 BlockFace.SELF 查询方块本身
    返回:
      红石充能等级

  - ### getBlockPower

    int getBlockPower()
    返回提供给此方块的红石充能等级.

    原文:Returns the redstone power being provided to this block

    返回:
      红石充能等级

  - ### isEmpty

    boolean isEmpty()
    检测此方块是否为空.

    当 `getType()` 返回 `Material.AIR` 时认为此方块为空.

    原文:Checks if this block is empty.

    A block is considered empty when `getType()` returns `Material.AIR`.

    返回:
      此方块是否为空

  - ### isLiquid

    boolean isLiquid()
    检测方块是否为流体. 当 `getType()` 返回 `Material.WATER` 或 `Material.LAVA` 时认为此方块为流体.

    原文:Checks if this block is liquid.

    A block is considered liquid when `getType()` returns `Material.WATER` or `Material.LAVA`.

    返回:
      方块是否为流体

  - ### getTemperature

    double getTemperature()
    获取方块所在生物群系的环境温度.

    如果你要避免方块高度对温度的影响, 请使用`World.getTemperature(int, int)`.

    原文:Gets the temperature of this block.

    If the raw biome temperature without adjusting for height effects is required then please use `World.getTemperature(int, int)`.

    返回:
      方块温度

  - ### getHumidity

    double getHumidity()
    获取方块所在生物群系的环境湿度.

    原文:Gets the humidity of the biome of this block

    返回:
      方块所在生物群系的环境湿度

  - ### getPistonMoveReaction

    @NotNull @NotNull PistonMoveReaction getPistonMoveReaction()
    返回当此方块被活塞推动时的反应.

    原文:Returns the reaction of the block when moved by a piston

    返回:
      方块对活塞的反应

  - ### breakNaturally

    boolean breakNaturally()
    破坏此方块并生成掉落物, 就像是玩家不使用工具时挖掘方块一样.

    原文:Breaks the block and spawns items as if a player had digged it regardless of the tool.

    返回:
      若方块成功被破坏则返回true

  - ### breakNaturally

    boolean breakNaturally(@Nullable @Nullable ItemStack tool)
    破坏此方块并生成掉落物, 就像是玩家手持工具挖掘方块一样.

    原文:Breaks the block and spawns items as if a player had digged it with a specific tool

    参数:
      `tool` - 使用何种工具挖掘方块
    返回:
      true 若方块成功被破坏则返回true

  - ### applyBoneMeal

    boolean applyBoneMeal(@NotNull @NotNull BlockFace face)
    模拟使用骨粉向本方块施肥 (若可能).

    原文:Simulate bone meal application to this block (if possible).

    参数:
      `face` - 将骨粉施予方块的哪一面
    返回:
      成功施肥则返回true

  - ### getDrops

    @NotNull @NotNull Collection<ItemStack> getDrops()
    返回当破坏此方块时掉落的物品.

    原文:Returns a list of items which would drop by destroying this block

    返回:
      方块掉落物列表

  - ### getDrops

    @NotNull @NotNull Collection<ItemStack> getDrops(@Nullable @Nullable ItemStack tool)
    返回当使用特定工具破坏此方块时掉落的物品.

    原文:Returns a list of items which would drop by destroying this block with a specific tool

    参数:
      `tool` - 使用何种工具挖掘方块
    返回:
      方块掉落物列表

  - ### getDrops

    @NotNull @NotNull Collection<ItemStack> getDrops(@NotNull @NotNull ItemStack tool, @Nullable @Nullable Entity entity)
    返回当某实体使用某工具破坏此方块时掉落的物品.

    原文:Returns a list of items which would drop by the entity destroying this block with a specific tool

    参数:
      `tool` - 实体使用的工具
      `entity` - 破坏此方块的实体
    返回:
      方块掉落物列表

  - ### isPreferredTool

    boolean isPreferredTool(@NotNull @NotNull ItemStack tool)
    Returns if the given item is a preferred choice to break this Block. In some cases this determines if a block will drop anything or extra loot.
    参数:
      `tool` - The tool or item used for breaking this block
    返回:
      true if the tool is preferred for breaking this block.

  - ### getBreakSpeed

    float getBreakSpeed(@NotNull @NotNull Player player)
    Gets the speed at which the given player would break this block, taking into account tools, potion effects, whether or not the player is in water, enchantments, etc. The returned value is the amount of progress made in breaking the block each tick. When the total breaking progress reaches `1.0f`, the block is broken. Note that the break speed can change in the course of breaking a block, e.g. if a potion effect is applied or expires, or the player jumps/enters water.
    参数:
      `player` - player breaking the block
    返回:
      the speed at which the player breaks this block

  - ### isPassable

    boolean isPassable()
    检测能否自由通过此方块.

    如果方块没有可阻碍玩家穿过的可碰撞部分, 就可自由通过此方块.

    例如: 高草丛、各种花、告示牌等都是可通过的, 但开着的门、栅栏门、活板门等不可, 因为它们依然有可碰撞部分.

    原文:Checks if this block is passable.

    A block is passable if it has no colliding parts that would prevent players from moving through it.

    Examples: Tall grass, flowers, signs, etc. are passable, but open doors, fence gates, trap doors, etc. are not because they still have parts that can be collided with.

    返回:
      能否自由通过此方块

  - ### rayTrace

    @Nullable @Nullable RayTraceResult rayTrace(@NotNull @NotNull Location start, @NotNull @NotNull Vector direction, double maxDistance, @NotNull @NotNull FluidCollisionMode fluidCollisionMode)
    Performs a ray trace that checks for collision with this specific block in its current state using its precise collision shape.
    参数:
      `start` - the start location
      `direction` - the ray direction
      `maxDistance` - the maximum distance
      `fluidCollisionMode` - the fluid collision mode
    返回:
      the ray trace hit result, or `null` if there is no hit

  - ### getBoundingBox

    @NotNull @NotNull BoundingBox getBoundingBox()
    Gets the approximate bounding box for this block.

    This isn't exact as some blocks `Stairs` contain many bounding boxes to establish their complete form. Also, the box may not be exactly the same as the collision shape (such as cactus, which is 16/16 of a block with 15/16 collisional bounds). This method will return an empty bounding box if the geometric shape of the block is empty (such as air blocks).

    返回:
      the approximate bounding box of the block

  - ### getCollisionShape

    @NotNull @NotNull VoxelShape getCollisionShape()
    Gets the collision shape of this block.
    返回:
      a `VoxelShape` representing the collision shape of this block.

  - ### canPlace

    boolean canPlace(@NotNull @NotNull BlockData data)
    Checks if this block is a valid placement location for the specified block data.
    参数:
      `data` - the block data to check
    返回:
      `true` if the block data can be placed here