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, CreatureSpawner, DaylightDetector, DecoratedPot, Dispenser, Dropper, EnchantingTable, EnderChest, EndGateway, EntityBlockStorage<T>, Furnace, HangingSign, Hopper, Jigsaw, Jukebox, Lectern, LockableTileState, MovingPiston, SculkCatalyst, SculkSensor, SculkShrieker, ShulkerBox, Sign, Skull, Smoker, Structure, SuspiciousSand, TileState, TileStateInventoryHolder, 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 Details

    • getBlock

      @NotNull @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 @Deprecated(forRemoval=true, since="1.13") @NotNull MaterialData getData()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getBlockData()
      Gets the metadata for this block state.
      Returns:
      block specific metadata

    • getBlockData

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

    • copy

      @NotNull @Experimental @NotNull BlockState copy()
      Returns a copy of this BlockState as an unplaced BlockState.
      Returns:
      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.
      Parameters:
      location - the location to copy the block state to
      Returns:
      the new block state

    • getType

      @NotNull @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 @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 @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 @Nullable Location getLocation(@Nullable @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 @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

      @Deprecated(forRemoval=true, since="1.13") void setData(@NotNull @NotNull MaterialData data)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setBlockData(BlockData)
      Sets the metadata for this block state.
      Parameters:
      data - New block specific metadata

    • setBlockData

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

    • setType

      void setType(@NotNull @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 byte getRawData()
      Deprecated.
      Magic value
      Returns:
      The data as a raw byte.

    • setRawData

      @Deprecated 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)

    • isCollidable

      boolean isCollidable()
      Checks if this block state is collidable.
      Returns:
      true if collidable

    • getDrops

      @NotNull default @Unmodifiable Collection<ItemStack> getDrops()
      Returns an immutable list of items which would drop by destroying this block state.
      Returns:
      an immutable list of dropped items for the block state
      Throws:
      IllegalStateException - if this block state is not placed

    • getDrops

      @NotNull default @Unmodifiable Collection<ItemStack> getDrops(@Nullable ItemStack tool)
      Returns an immutable list of items which would drop by destroying this block state with a specific tool
      Parameters:
      tool - The tool or item in hand used for digging
      Returns:
      an immutable list of dropped items for the block state
      Throws:
      IllegalStateException - if this block state is not placed

    • getDrops

      @NotNull @Unmodifiable Collection<ItemStack> getDrops(@Nullable ItemStack tool, @Nullable Entity entity)
      Returns an immutable list of items which would drop by the entity destroying this block state with a specific tool
      Parameters:
      tool - The tool or item in hand used for digging
      entity - the entity destroying the block
      Returns:
      an immutable list of dropped items for the block state
      Throws:
      IllegalStateException - if this block state is not placed