Package org.bukkit.block

Interface Block

All Superinterfaces:
Metadatable, Translatable, Translatable
public interface Block extends Metadatable, Translatable, Translatable
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!!!!

  • Method Details

    • getData

      @Deprecated(since="1.6.2", forRemoval=true) byte getData()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Magic value
      Gets the metadata for this block
      Returns:
      block specific metadata

    • getBlockData

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

    • getRelative

      @NotNull @NotNull Block getRelative(int modX, int modY, int modZ)
      Gets the block at the given offsets
      Parameters:
      modX - X-coordinate offset
      modY - Y-coordinate offset
      modZ - Z-coordinate offset
      Returns:
      Block at the given offsets

    • getRelative

      @NotNull @NotNull Block getRelative(@NotNull @NotNull BlockFace face)
      Gets the block at the given face

      This method is equal to getRelative(face, 1)

      Parameters:
      face - Face of this block to return
      Returns:
      Block at the given face
      See Also:

    • getRelative

      @NotNull @NotNull Block getRelative(@NotNull @NotNull BlockFace face, int distance)
      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);
      Parameters:
      face - Face of this block to return
      distance - Distance to get the block at
      Returns:
      Block at the given face

    • getType

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

    • getLightLevel

      byte getLightLevel()
      Gets the light level between 0-15
      Returns:
      light level

    • 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.

      Returns:
      Sky light level

    • 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.

      Returns:
      Block light level

    • getWorld

      @NotNull @NotNull World getWorld()
      Gets the world which contains this Block
      Returns:
      World containing this block

    • getX

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

    • getY

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

    • getZ

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

    • getBlockKey

      @Deprecated(since="1.18.1") default long getBlockKey()
      Deprecated.
      see getBlockKey(int, int, int)
      Returns this block's coordinates packed into a long value. Computed via: Block.getBlockKey(this.getX(), this.getY(), this.getZ())
      Returns:
      This block's x, y, and z coordinates packed into a long value
      See Also:

    • getBlockKey

      @Deprecated(since="1.18.1") static long getBlockKey(int x, int y, int z)
      Deprecated.
      only encodes y block ranges from -512 to 511 and represents an already changed implementation detail
      Returns the specified block coordinates packed into a long value

      The return value can be computed as follows:
      long value = ((long)x & 0x7FFFFFF) | (((long)z & 0x7FFFFFF) << 27) | ((long)y << 54);

      And may be unpacked as follows:
      int x = (int) ((packed << 37) >> 37);
      int y = (int) (packed >> 54);
      int z = (int) ((packed << 10) >> 37);

      Returns:
      This block's x, y, and z coordinates packed into a long value

    • getBlockKeyX

      @Deprecated(since="1.18.1") static int getBlockKeyX(long packed)
      Deprecated.
      see getBlockKey(int, int, int)
      Returns the x component from the packed value.
      Parameters:
      packed - The packed value, as computed by getBlockKey(int, int, int)
      Returns:
      The x component from the packed value.
      See Also:

    • getBlockKeyY

      @Deprecated(since="1.18.1") static int getBlockKeyY(long packed)
      Deprecated.
      see getBlockKey(int, int, int)
      Returns the y component from the packed value.
      Parameters:
      packed - The packed value, as computed by getBlockKey(int, int, int)
      Returns:
      The y component from the packed value.
      See Also:

    • getBlockKeyZ

      @Deprecated(since="1.18.1") static int getBlockKeyZ(long packed)
      Deprecated.
      see getBlockKey(int, int, int)
      Returns the z component from the packed value.
      Parameters:
      packed - The packed value, as computed by getBlockKey(int, int, int)
      Returns:
      The z component from the packed value.
      See Also:

    • isValidTool

      @Deprecated(since="1.21", forRemoval=true) boolean isValidTool(@NotNull @NotNull ItemStack itemStack)
      Deprecated, for removal: This API element is subject to removal in a future version.
      partially replaced by isPreferredTool(ItemStack)
      Checks if the itemstack is a valid tool to break the block with
      Parameters:
      itemStack - The (tool) itemstack
      Returns:
      whether the block will drop items

    • getLocation

      @NotNull @NotNull Location getLocation()
      Gets the Location of the block
      Returns:
      Location of block

    • getLocation

      @Contract("null -> null; !null -> !null") @Nullable @Nullable Location getLocation(@Nullable @Nullable Location loc)
      Stores the location of the block in the provided Location object.

      If the provided Location is null this method does nothing and returns 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 this block
      Returns:
      Containing Chunk

    • setBlockData

      void setBlockData(@NotNull @NotNull BlockData data)
      Sets the complete data for this block
      Parameters:
      data - new block specific data

    • setBlockData

      void setBlockData(@NotNull @NotNull BlockData data, boolean applyPhysics)
      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.
      Parameters:
      data - new block specific data
      applyPhysics - false to cancel physics from the changed block

    • setType

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

    • setType

      void setType(@NotNull @NotNull Material type, boolean applyPhysics)
      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.
      Parameters:
      type - Material to change this block to
      applyPhysics - False to cancel physics on the changed block.

    • getFace

      @Nullable @Nullable BlockFace getFace(@NotNull @NotNull Block block)
      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
      Parameters:
      block - Block to compare against this block
      Returns:
      BlockFace of this block which has the requested block, or null

    • getState

      @NotNull @NotNull BlockState getState()
      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.

      Returns:
      BlockState with the current state of this block.

    • getState

      @NotNull @NotNull BlockState getState(boolean useSnapshot)
      Parameters:
      useSnapshot - if this block is a block entity, should we create a full copy of the BlockEntity
      Returns:
      BlockState with the current state of this block
      See Also:

    • getBiome

      @NotNull @NotNull Biome getBiome()
      Returns the biome that this block resides in
      Returns:
      Biome type containing this block
      See Also:

    • getComputedBiome

      @NotNull @NotNull Biome getComputedBiome()
      Gets the computed biome at the location of this Block.
      Returns:
      computed biome at the location of this Block.
      See Also:

    • setBiome

      void setBiome(@NotNull @NotNull Biome bio)
      Sets the biome that this block resides in
      Parameters:
      bio - new Biome type for this block

    • isBlockPowered

      boolean isBlockPowered()
      Returns true if the block is being powered by Redstone.
      Returns:
      True if the block is powered.

    • isBlockIndirectlyPowered

      boolean isBlockIndirectlyPowered()
      Returns true if the block is being indirectly powered by Redstone.
      Returns:
      True if the block is indirectly powered.

    • isBlockFacePowered

      boolean isBlockFacePowered(@NotNull @NotNull BlockFace face)
      Returns true if the block face is being powered by Redstone.
      Parameters:
      face - The block face
      Returns:
      True if the block face is powered.

    • isBlockFaceIndirectlyPowered

      boolean isBlockFaceIndirectlyPowered(@NotNull @NotNull BlockFace face)
      Returns true if the block face is being indirectly powered by Redstone.
      Parameters:
      face - The block face
      Returns:
      True if the block face is indirectly powered.

    • getBlockPower

      int getBlockPower(@NotNull @NotNull BlockFace face)
      Returns the redstone power being provided to this block face
      Parameters:
      face - the face of the block to query or BlockFace.SELF for the block itself
      Returns:
      The power level.

    • getBlockPower

      int getBlockPower()
      Returns the redstone power being provided to this block
      Returns:
      The power level.

    • isEmpty

      boolean isEmpty()
      Checks if this block is empty.

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

      Returns:
      true if this block is empty

    • isLiquid

      boolean isLiquid()
      Checks if this block is liquid.

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

      Returns:
      true if this block is liquid

    • isBuildable

      boolean isBuildable()
      Check if this block is solid

      Determined by Minecraft, typically a block a player can use to place a new block to build things. An example of a non buildable block would be liquids, flowers, or fire

      Returns:
      true if block is buildable

    • isBurnable

      boolean isBurnable()
      Check if this block is burnable

      Determined by Minecraft, typically a block that fire can destroy (Wool, Wood)

      Returns:
      true if block is burnable

    • isReplaceable

      boolean isReplaceable()
      Checks if this block can be immediately replaced by another block, such as placing a new block in air or tall grass.
      Returns:
      true if block is replaceable

    • isSolid

      boolean isSolid()
      Check if this block is solid

      Determined by Minecraft, typically a block a player can stand on and can't be passed through. This API is faster than accessing Material#isSolid as it avoids a material lookup and switch statement.

      Returns:
      true if block is solid

    • isCollidable

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

    • getTemperature

      double getTemperature()
      Gets the temperature of this block.
      Returns:
      Temperature of this block

    • getHumidity

      double getHumidity()
      Gets the humidity of the biome of this block
      Returns:
      Humidity of this block

    • getPistonMoveReaction

      @NotNull @NotNull PistonMoveReaction getPistonMoveReaction()
      Returns the reaction of the block when moved by a piston
      Returns:
      reaction

    • breakNaturally

      boolean breakNaturally()
      Breaks the block and spawns items as if a player had digged it regardless of the tool.
      Returns:
      true if the block was destroyed

    • breakNaturally

      boolean breakNaturally(@Nullable @Nullable ItemStack tool)
      Breaks the block and spawns items as if a player had digged it with a specific tool
      Parameters:
      tool - The tool or item in hand used for digging
      Returns:
      true if the block was destroyed

    • breakNaturally

      default boolean breakNaturally(boolean triggerEffect)
      Breaks the block and spawns item drops as if a player had broken it
      Parameters:
      triggerEffect - Play the block break particle effect and sound
      Returns:
      true if the block was destroyed
      See Also:

    • breakNaturally

      boolean breakNaturally(boolean triggerEffect, boolean dropExperience)
      Breaks the block and spawns item drops as if a player had broken it
      Parameters:
      triggerEffect - Play the block break particle effect and sound
      dropExperience - drop exp if the block normally does so
      Returns:
      true if the block was destroyed

    • breakNaturally

      default boolean breakNaturally(@NotNull @NotNull ItemStack tool, boolean triggerEffect)
      Breaks the block and spawns item drops as if a player had broken it with a specific tool
      Parameters:
      tool - The tool or item in hand used for digging
      triggerEffect - Play the block break particle effect and sound
      Returns:
      true if the block was destroyed
      See Also:

    • breakNaturally

      boolean breakNaturally(@NotNull @NotNull ItemStack tool, boolean triggerEffect, boolean dropExperience)
      Breaks the block and spawns item drops as if a player had broken it with a specific tool
      Parameters:
      tool - The tool or item in hand used for digging
      triggerEffect - Play the block break particle effect and sound
      dropExperience - drop exp if the block normally does so
      Returns:
      true if the block was destroyed

    • breakNaturally

      boolean breakNaturally(@NotNull @NotNull ItemStack tool, boolean triggerEffect, boolean dropExperience, boolean forceEffect)
      Breaks the block and spawns item drops as if a player had broken it with a specific tool
      Parameters:
      tool - The tool or item in hand used for digging
      triggerEffect - Play the block break particle effect and sound
      dropExperience - drop exp if the block normally does so
      forceEffect - Forces the break effect to be triggered even if the tool is not the correct tool for the block
      Returns:
      true if the block was destroyed

    • tick

      void tick()
      Causes the block to be ticked, this is different from randomTick(), in that it is usually scheduled to occur, for example redstone components being activated, sand falling, etc.

      This method may directly fire events relating to block ticking.

      See Also:

    • fluidTick

      void fluidTick()
      Causes the fluid to be ticked, this is different from randomTick(), in that it is usually scheduled to occur, for example causing waterlogged blocks to spread.

      This method may directly fire events relating to fluid ticking.

      See Also:

    • randomTick

      void randomTick()
      Causes the block to be ticked randomly. This has a chance to execute naturally if BlockData.isRandomlyTicked() is true.

      For certain blocks, this behavior may be the same as tick().

      This method may directly fire events relating to block random ticking.

      See Also:

    • applyBoneMeal

      boolean applyBoneMeal(@NotNull @NotNull BlockFace face)
      Simulate bone meal application to this block (if possible).
      Parameters:
      face - the face on which bonemeal should be applied
      Returns:
      true if the block was bonemealed, false otherwise

    • getDrops

      @NotNull @NotNull Collection<ItemStack> getDrops()
      Returns a list of items which could drop by destroying this block.

      The items are not guaranteed to be consistent across multiple calls to this method as this just uses the block type's loot table.

      Returns:
      a list of dropped items for this type of block

    • getDrops

      @NotNull @NotNull Collection<ItemStack> getDrops(@Nullable @Nullable ItemStack tool)
      Returns a list of items which could drop by destroying this block with a specific tool.

      The items are not guaranteed to be consistent across multiple calls to this method as this just uses the block type's loot table.

      Parameters:
      tool - The tool or item in hand used for digging
      Returns:
      a list of dropped items for this type of block

    • getDrops

      @NotNull @NotNull Collection<ItemStack> getDrops(@Nullable @Nullable ItemStack tool, @Nullable @Nullable Entity entity)
      Returns a list of items which could drop by the entity destroying this block with a specific tool.

      The items are not guaranteed to be consistent across multiple calls to this method as this just uses the block type's loot table.

      Parameters:
      tool - The tool or item in hand used for digging
      entity - the entity destroying the block
      Returns:
      a list of dropped items for this type of block

    • 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.
      Parameters:
      tool - The tool or item used for breaking this block
      Returns:
      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.
      Parameters:
      player - player breaking the block
      Returns:
      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.

      Returns:
      true if passable

    • 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.
      Parameters:
      start - the start location
      direction - the ray direction
      maxDistance - the maximum distance
      fluidCollisionMode - the fluid collision mode
      Returns:
      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).

      Returns:
      the approximate bounding box of the block

    • getCollisionShape

      @NotNull @NotNull VoxelShape getCollisionShape()
      Gets the collision shape of this block.
      Returns:
      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.
      Parameters:
      data - the block data to check
      Returns:
      true if the block data can be placed here

    • getSoundGroup

      @NotNull @Deprecated(forRemoval=true, since="1.18.2") BlockSoundGroup getSoundGroup()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getBlockSoundGroup()
      Gets the BlockSoundGroup for this block.

      This object contains the block, step, place, hit, and fall sounds.

      Returns:
      the sound group for this block

    • getBlockSoundGroup

      @NotNull SoundGroup getBlockSoundGroup()
      Gets the SoundGroup for this block.
      Returns:
      the sound group for this block

    • getTranslationKey

      @NotNull @Deprecated(forRemoval=true) @NotNull String getTranslationKey()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use Translatable.translationKey()
      Description copied from interface: Translatable
      Get the translation key, suitable for use in a translation component.
      Specified by:
      getTranslationKey in interface Translatable
      Returns:
      the translation key

    • getDestroySpeed

      default float getDestroySpeed(@NotNull @NotNull ItemStack itemStack)
      Gets the speed at which this block will be destroyed by a given ItemStack

      Default value is 1.0

      Parameters:
      itemStack - ItemStack used to mine this Block
      Returns:
      the speed that this Block will be mined by the given ItemStack

    • getDestroySpeed

      default float getDestroySpeed(@NotNull @NotNull ItemStack itemStack, boolean considerEnchants)
      Gets the speed at which this block will be destroyed by a given ItemStack

      Default value is 1.0

      Parameters:
      itemStack - ItemStack used to mine this Block
      considerEnchants - true to look at enchants on the itemstack
      Returns:
      the speed that this Block will be mined by the given ItemStack

    • isSuffocating

      boolean isSuffocating()
      Checks if the block can suffocate.
      Returns:
      true if the block can suffocate