Package org.bukkit.block

Interface Block

All Superinterfaces:

Metadatable

public interface Block
extends Metadatable

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 Summary

Modifier and Type	Method	Description
boolean	breakNaturally()	Breaks the block and spawns items as if a player had digged it regardless of the tool.
boolean	breakNaturally(@NotNull ItemStack tool, boolean triggerEffect)	Breaks the block and spawns items as if a player had digged it with a specific tool
boolean	breakNaturally(@Nullable ItemStack tool)	Breaks the block and spawns items as if a player had digged it with a specific tool
@NotNull Biome	getBiome()	Returns the biome that this block resides in
@NotNull BlockData	getBlockData()	Gets the complete block data for this block
default long	getBlockKey()	Returns this block's coordinates packed into a long value.
static long	getBlockKey(int x, int y, int z)	Returns the specified block coordinates packed into a long value
static int	getBlockKeyX(long packed)	Returns the x component from the packed value.
static int	getBlockKeyY(long packed)	Returns the y component from the packed value.
static int	getBlockKeyZ(long packed)	Returns the z component from the packed value.
int	getBlockPower()	Returns the redstone power being provided to this block
int	getBlockPower(@NotNull BlockFace face)	Returns the redstone power being provided to this block face
@NotNull BoundingBox	getBoundingBox()	Gets the approximate bounding box for this block.
@NotNull Chunk	getChunk()	Gets the chunk which contains this block
byte	getData()	Deprecated. Magic value
@NotNull Collection<ItemStack>	getDrops()	Returns a list of items which would drop by destroying this block
@NotNull Collection<ItemStack>	getDrops(@NotNull ItemStack tool, @Nullable Entity entity)	Returns a list of items which would drop by the entity destroying this block with a specific tool
@NotNull Collection<ItemStack>	getDrops(@Nullable ItemStack tool)	Returns a list of items which would drop by destroying this block with a specific tool
@Nullable BlockFace	getFace(@NotNull Block block)	Gets the face relation of this block compared to the given block.
double	getHumidity()	Gets the humidity of the biome of this block
byte	getLightFromBlocks()	Get the amount of light at this block from nearby blocks.
byte	getLightFromSky()	Get the amount of light at this block from the sky.
byte	getLightLevel()	Gets the light level between 0-15
@NotNull Location	getLocation()	Gets the Location of the block
@Nullable Location	getLocation(@Nullable Location loc)	Stores the location of the block in the provided Location object.
@NotNull PistonMoveReaction	getPistonMoveReaction()	Returns the reaction of the block when moved by a piston
@NotNull Block	getRelative(int modX, int modY, int modZ)	Gets the block at the given offsets
@NotNull Block	getRelative(@NotNull BlockFace face)	Gets the block at the given face
@NotNull Block	getRelative(@NotNull BlockFace face, int distance)	Gets the block at the given distance of the given face
BlockSoundGroup	getSoundGroup()	Gets the BlockSoundGroup for this block.
@NotNull BlockState	getState()	Captures the current state of this block.
@NotNull BlockState	getState(boolean useSnapshot)
double	getTemperature()	Gets the temperature of this block.
@NotNull Material	getType()	Gets the type of this block
@NotNull World	getWorld()	Gets the world which contains this Block
int	getX()	Gets the x-coordinate of this block
int	getY()	Gets the y-coordinate of this block
int	getZ()	Gets the z-coordinate of this block
boolean	isBlockFaceIndirectlyPowered(@NotNull BlockFace face)	Returns true if the block face is being indirectly powered by Redstone.
boolean	isBlockFacePowered(@NotNull BlockFace face)	Returns true if the block face is being powered by Redstone.
boolean	isBlockIndirectlyPowered()	Returns true if the block is being indirectly powered by Redstone.
boolean	isBlockPowered()	Returns true if the block is being powered by Redstone.
boolean	isEmpty()	Checks if this block is empty.
boolean	isLiquid()	Checks if this block is liquid.
boolean	isPassable()	Checks if this block is passable.
@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)	Sets the biome that this block resides in
void	setBlockData(@NotNull BlockData data)	Sets the complete data for this block
void	setBlockData(@NotNull BlockData data, boolean applyPhysics)	Sets the complete data for this block Note that applyPhysics = false is not in general safe.
void	setType(@NotNull Material type)	Sets the type of this block
void	setType(@NotNull Material type, boolean applyPhysics)	Sets the type of this block Note that applyPhysics = false is not in general safe.

Methods inherited from interface org.bukkit.metadata.Metadatable

getMetadata, hasMetadata, removeMetadata, setMetadata

Method Detail

getData

@Deprecated
byte getData()

Deprecated.

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(BlockFace, int)

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

default long getBlockKey()

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(int, int, int)

getBlockKey

static long getBlockKey(int x,
                        int y,
                        int z)

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

static int getBlockKeyX(long packed)

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:

getBlockKey(int, int, int)

getBlockKeyY

static int getBlockKeyY(long packed)

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:

getBlockKey(int, int, int)

getBlockKeyZ

static int getBlockKeyZ(long packed)

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:

getBlockKey(int, int, int)

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 TE, should we create a fully copy of the TileEntity

Returns:

BlockState with the current state of this block

See Also:

optionally disables use of snapshot, to operate on real block data

getBiome

@NotNull
@NotNull Biome getBiome()

Returns the biome that this block resides in

Returns:

Biome type containing this block

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

getTemperature

double getTemperature()

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

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

boolean breakNaturally(@NotNull
                       @NotNull ItemStack tool,
                       boolean triggerEffect)

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

triggerEffect - Play the block break particle effect and sound

Returns:

true if the block was destroyed

getDrops

@NotNull
@NotNull Collection<ItemStack> getDrops()

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

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 would drop by destroying this block with a specific tool

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(@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

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

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

getSoundGroup

@NotNull
BlockSoundGroup getSoundGroup()

Gets the BlockSoundGroup for this block.

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

Returns:

the sound group for this block