程序包 org.bukkit.block

# 接口 BlockState

所有超级接口:
  `Metadatable`

所有已知子接口:
  `Banner`, `Barrel`, `Beacon`, `Bed`, `Beehive`, `Bell`, `BlastFurnace`, `BrewingStand`, `BrushableBlock`, `CalibratedSculkSensor`, `Campfire`, `Chest`, `ChiseledBookshelf`, `CommandBlock`, `Comparator`, `Conduit`, `Container`, `Crafter`, `CreatureSpawner`, `DaylightDetector`, `DecoratedPot`, `Dispenser`, `Dropper`, `EnchantingTable`, `EnderChest`, `EndGateway`, `EntityBlockStorage<T>`, `Furnace`, `HangingSign`, `Hopper`, `Jigsaw`, `Jukebox`, `Lectern`, `SculkCatalyst`, `SculkSensor`, `SculkShrieker`, `ShulkerBox`, `Sign`, `Skull`, `Smoker`, `Structure`, `SuspiciousSand`, `TileState`, `TrialSpawner`, `Vault`

public interface BlockState extends Metadatable
表示方块某一时刻的状态的快照, 不会随方块本身的变更自动更改.

与每个坐标只能存在一个Block实例不同, 对于任何给定的Block, BlockState实例可以存在多个. 请注意, 其它插件可能会更改方块的状态, 而你的插件不会知道其变更; 或者其它插件可能会将方块更改为另一种类型, 从而导致你的BlockState失效.

- ## 方法概要

  修饰符和类型
  方法
  说明
  `@NotNull BlockState`
  `copy()`
  Returns a copy of this BlockState as an unplaced BlockState.
  `@NotNull BlockState`
  `copy(@NotNull Location location)`
  Copies the state to another block as an unplaced BlockState.
  `@NotNull Block`
  `getBlock()`
  获取此方块状态所表示的方块.
  `@NotNull BlockData`
  `getBlockData()`
  获取此方块状态的数据.
  `@NotNull Chunk`
  `getChunk()`
  获取此方块状态所在的区块.
  `@NotNull MaterialData`
  `getData()`
  获取此方块状态的元数据.
  `byte`
  `getLightLevel()`
  获取本状态表示的方块所提供的光照强度.
  `@NotNull Location`
  `getLocation()`
  获取此方块状态的位置.
  `@Nullable Location`
  `getLocation(@Nullable Location loc)`
  存储此方块状态的位置到给定的位置实例中.
  `byte`
  `getRawData()`
  已过时。
  不安全的参数
  `@NotNull Material`
  `getType()`
  获取此方块状态的类型.
  `@NotNull World`
  `getWorld()`
  获取方块所在的世界.
  `int`
  `getX()`
  获取此方块状态的x坐标.
  `int`
  `getY()`
  获取此方块状态的y坐标.
  `int`
  `getZ()`
  获取此方块状态的z坐标.
  `boolean`
  `isPlaced()`
  返回本状态是否已放置于世界.
  `void`
  `setBlockData(@NotNull BlockData data)`
  设置此方块状态的数据.
  `void`
  `setData(@NotNull MaterialData data)`
  设置此方块状态的元数据.
  `void`
  `setRawData(byte data)`
  已过时。
  不安全的参数
  `void`
  `setType(@NotNull Material type)`
  设置本方块状态的类型.
  `boolean`
  `update()`
  尝试更新此状态代表的方块, 将此状态中定义的新数据值应用于其方块.
  `boolean`
  `update(boolean force)`
  尝试更新此状态代表的方块, 将此状态中定义的新数据值应用于其方块.
  `boolean`
  `update(boolean force, boolean applyPhysics)`
  尝试更新此状态代表的方块, 将此状态中定义的新数据值应用于其方块.

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

  `getMetadata, hasMetadata, removeMetadata, setMetadata`

- ## 方法详细资料

  - ### getBlock

    @NotNull @NotNull Block getBlock()
    获取此方块状态所表示的方块.

    原文:Gets the block represented by this block state.

    返回:
      此方块状态所表示的方块
    抛出:
      `IllegalStateException` - 如果此方块未被放置

  - ### getData

    @NotNull @NotNull MaterialData getData()
    获取此方块状态的元数据.

    原文:Gets the metadata for this block state.

    返回:
      方块的元数据

  - ### getBlockData

    @NotNull @NotNull BlockData getBlockData()
    获取此方块状态的数据.

    原文:Gets the data for this block state.

    返回:
      方块的数据

  - ### copy

    @NotNull @Experimental @NotNull BlockState copy()
    Returns a copy of this BlockState as an unplaced BlockState.
    返回:
      a copy of the block state

  - ### copy

    @NotNull @Experimental @NotNull BlockState copy(@NotNull @NotNull Location location)
    Copies the state to another block as an unplaced BlockState.
    参数:
      `location` - the location to copy the block state to
    返回:
      the new block state

  - ### getType

    @NotNull @NotNull Material getType()
    获取此方块状态的类型.

    原文:Gets the type of this block state.

    返回:
      方块的类型

  - ### getLightLevel

    byte getLightLevel()
    获取本状态表示的方块所提供的光照强度.

    原文:Gets the current light level of the block represented by this block state.

    返回:
      光照强度, 范围: 0-15
    抛出:
      `IllegalStateException` - 如果此方块未被放置

  - ### getWorld

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

    原文:Gets the world which contains the block represented by this block state.

    返回:
      方块所在的世界
    抛出:
      `IllegalStateException` - 如果此方块未被放置

  - ### getX

    int getX()
    获取此方块状态的x坐标.

    原文:Gets the x-coordinate of this block state.

    返回:
      x坐标

  - ### getY

    int getY()
    获取此方块状态的y坐标.

    原文:Gets the y-coordinate of this block state.

    返回:
      y坐标

  - ### getZ

    int getZ()
    获取此方块状态的z坐标.

    原文:Gets the z-coordinate of this block state.

    返回:
      z坐标

  - ### getLocation

    @NotNull @NotNull Location getLocation()
    获取此方块状态的位置.

    如果此方块未被放置, 则返回的Location中的world将为null!

    原文:Gets the location of this block state.

    If this block state is not placed the location's world will be null!

    返回:
      位置

  - ### getLocation

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

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

    如果此方块未被放置, 则返回的Location中的world将为null!

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

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

    If this block state is not placed the location's world will be null!

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

  - ### getChunk

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

    原文:Gets the chunk which contains the block represented by this block state.

    返回:
      方块所在的区块
    抛出:
      `IllegalStateException` - 如果此方块未被放置

  - ### setData

    void setData(@NotNull @NotNull MaterialData data)
    设置此方块状态的元数据.

    原文:Sets the metadata for this block state.

    参数:
      `data` - 方块状态的元数据

  - ### setBlockData

    void setBlockData(@NotNull @NotNull BlockData data)
    设置此方块状态的数据.

    原文:Sets the data for this block state.

    参数:
      `data` - 方块数据

  - ### setType

    void setType(@NotNull @NotNull Material type)
    设置本方块状态的类型.

    原文:Sets the type of this block state.

    参数:
      `type` - 要改变的类型

  - ### update

    boolean update()
    尝试更新此状态代表的方块, 将此状态中定义的新数据值应用于其方块.

    这与调用 update(false) 等效. 也就是说, 如果方块类型不再与本状态的类型相同, 将不会修改方块本身的状态. 万一出现这种状况, 将返回 false.

    原文:Attempts to update the block represented by this state, setting it to the new values as defined by this state.

    This has the same effect as calling update(false). That is to say, this will not modify the state of a block if it is no longer the same type as it was when this state was taken. It will return false in this eventuality.

    返回:
      true 成功更新返回 true, 否则为 false
    另请参阅:
      - `update(boolean)`

  - ### update

    boolean update(boolean force)
    尝试更新此状态代表的方块, 将此状态中定义的新数据值应用于其方块.

    这与调用 update(force, true) 等效. 也就是说, 这将触发周围方块的物理更新.

    原文:Attempts to update the block represented by this state, setting it to the new values as defined by this state.

    This has the same effect as calling update(force, true). That is to say, this will trigger a physics update to surrounding blocks.

    参数:
      `force` - true以强制设置状态
    返回:
      成功更新返回 true, 否则为 false

  - ### update

    boolean update(boolean force, boolean applyPhysics)
    尝试更新此状态代表的方块, 将此状态中定义的新数据值应用于其方块.

    如果此方块未被放置, 这将没有任何效果并返回 false.

    除非 force 为 true, 当原方块的类型与此方块状态的类型不再相同时, 将不会修改方块本身的状态.

    原文:Attempts to update the block represented by this state, setting it to the new values as defined by this state.

    If this state is not placed, this will have no effect and return true.

    Unless force is true, this will not modify the state of a block if it is no longer the same type as it was when this state was taken. It will return false in this eventuality.

    If force is true, it will set the type of the block to match the new state, set the state data and then return true.

    If applyPhysics is true, it will trigger a physics update on surrounding blocks which could cause them to update or disappear.

    参数:
      `force` - true以强制设置状态
      `applyPhysics` - false以取消对周围方块的物理更新
    返回:
      成功更新返回 true, 否则为 false

  - ### getRawData

    @Deprecated byte getRawData()
    已过时。
    不安全的参数
    返回:
      原始字节数据

  - ### setRawData

    @Deprecated void setRawData(byte data)
    已过时。
    不安全的参数
    参数:
      `data` - 方块新数据值

  - ### isPlaced

    boolean isPlaced()
    返回本状态是否已放置于世界.

    如果方块状态未放置于世界, 一些方法将不能正常工作.

    译注:这里的具体含义指是否已设置状态的 world 字段. 从真实方块获取到的 BlockState 是已设置所在世界的, 从 ItemMeta 中获取的 BlockState 是虚拟的, 其未设置所在的世界. 因此对于虚拟的 BlockState, 与世界有关的操作都是不能进行的.

    原文:Returns whether this state is placed in the world.

    Some methods will not work if the block state isn't placed in the world.

    返回:
      是否已为本状态设置所在世界, 或这是虚拟的状态(false) (比如应用于一个物品堆)