Package org.bukkit.block

Interface BlockState

All Superinterfaces:
Metadatable
All Known Subinterfaces:
Banner, Barrel, Beacon, Bed, Beehive, Bell, BlastFurnace, BrewingStand, BrushableBlock, CalibratedSculkSensor, Campfire, Chest, ChiseledBookshelf, CommandBlock, Comparator, Conduit, Container, Crafter, CreakingHeart, 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
Represents a captured state of a block, which will not change automatically.

Unlike Block, which only one object can exist per coordinate, BlockState can exist multiple times for any given Block. Note that another plugin may change the state of the block and you will not know, or they may change the block to another type entirely, causing your BlockState to become invalid.

  • Method Summary

    Modifier and Type
    Method
    Description
    BlockState
    copy()
    Returns a copy of this BlockState as an unplaced BlockState.
    BlockState
    copy(Location location)
    Copies the state to another block as an unplaced BlockState.
    Block
    getBlock()
    Gets the block represented by this block state.
    BlockData
    getBlockData()
    Gets the data for this block state.
    Chunk
    getChunk()
    Gets the chunk which contains the block represented by this block state.
    MaterialData
    getData()
    Gets the metadata for this block state.
    byte
    getLightLevel()
    Gets the current light level of the block represented by this block state.
    Location
    getLocation()
    Gets the location of this block state.
    Location
    getLocation(Location loc)
    Stores the location of this block state in the provided Location object.
    byte
    getRawData()
    Deprecated.
    Magic value
    Material
    getType()
    Gets the type of this block state.
    World
    getWorld()
    Gets the world which contains the block represented by this block state.
    int
    getX()
    Gets the x-coordinate of this block state.
    int
    getY()
    Gets the y-coordinate of this block state.
    int
    getZ()
    Gets the z-coordinate of this block state.
    boolean
    isPlaced()
    Returns whether this state is placed in the world.
    void
    setBlockData(BlockData data)
    Sets the data for this block state.
    void
    setData(MaterialData data)
    Sets the metadata for this block state.
    void
    setRawData(byte data)
    Deprecated.
    Magic value
    void
    setType(Material type)
    Sets the type of this block state.
    boolean
    update()
    Attempts to update the block represented by this state, setting it to the new values as defined by this state.
    boolean
    update(boolean force)
    Attempts to update the block represented by this state, setting it to the new values as defined by this state.
    boolean
    update(boolean force, boolean applyPhysics)
    Attempts to update the block represented by this state, setting it to the new values as defined by this state.

    Methods inherited from interface org.bukkit.metadata.Metadatable

    getMetadata, hasMetadata, removeMetadata, setMetadata

  • Method Details

    • getBlock

      @NotNull Block getBlock()
      Gets the block represented by this block state.
      Returns:
      the block represented by this block state
      Throws:
      IllegalStateException - if this block state is not placed

    • getData

      @NotNull MaterialData getData()
      Gets the metadata for this block state.
      Returns:
      block specific metadata

    • getBlockData

      @NotNull BlockData getBlockData()
      Gets the data for this block state.
      Returns:
      block specific data

    • copy

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

    • copy

      @NotNull @Experimental BlockState copy(@NotNull Location location)
      Copies the state to another block as an unplaced BlockState.
      Parameters:
      location - the location to copy the block state to
      Returns:
      the new block state

    • getType

      @NotNull Material getType()
      Gets the type of this block state.
      Returns:
      block type

    • getLightLevel

      byte getLightLevel()
      Gets the current light level of the block represented by this block state.
      Returns:
      the light level between 0-15
      Throws:
      IllegalStateException - if this block state is not placed

    • getWorld

      @NotNull World getWorld()
      Gets the world which contains the block represented by this block state.
      Returns:
      the world containing the block represented by this block state
      Throws:
      IllegalStateException - if this block state is not placed

    • getX

      int getX()
      Gets the x-coordinate of this block state.
      Returns:
      x-coordinate

    • getY

      int getY()
      Gets the y-coordinate of this block state.
      Returns:
      y-coordinate

    • getZ

      int getZ()
      Gets the z-coordinate of this block state.
      Returns:
      z-coordinate

    • getLocation

      @NotNull Location getLocation()
      Gets the location of this block state.

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

      Returns:
      the location

    • getLocation

      @Contract("null -> null; !null -> !null") @Nullable Location getLocation(@Nullable Location loc)
      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!

      Parameters:
      loc - the location to copy into
      Returns:
      The Location object provided or null

    • getChunk

      @NotNull Chunk getChunk()
      Gets the chunk which contains the block represented by this block state.
      Returns:
      the containing Chunk
      Throws:
      IllegalStateException - if this block state is not placed

    • setData

      void setData(@NotNull MaterialData data)
      Sets the metadata for this block state.
      Parameters:
      data - New block specific metadata

    • setBlockData

      void setBlockData(@NotNull BlockData data)
      Sets the data for this block state.
      Parameters:
      data - New block specific data

    • setType

      void setType(@NotNull Material type)
      Sets the type of this block state.
      Parameters:
      type - Material to change this block state to

    • update

      boolean update()
      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.

      Returns:
      true if the update was successful, otherwise false
      See Also:

    • update

      boolean update(boolean force)
      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.

      Parameters:
      force - true to forcefully set the state
      Returns:
      true if the update was successful, otherwise false

    • update

      boolean update(boolean force, boolean applyPhysics)
      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.

      Parameters:
      force - true to forcefully set the state
      applyPhysics - false to cancel updating physics on surrounding blocks
      Returns:
      true if the update was successful, otherwise false

    • getRawData

      @Deprecated(since="1.6.2") byte getRawData()
      Deprecated.
      Magic value
      Returns:
      The data as a raw byte.

    • setRawData

      @Deprecated(since="1.6.2") void setRawData(byte data)
      Deprecated.
      Magic value
      Parameters:
      data - The new data value for the block.

    • isPlaced

      boolean isPlaced()
      Returns whether this state is placed in the world.

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

      Returns:
      whether the state is placed in the world or 'virtual' (e.g. on an itemstack)