Package org.bukkit.block

Interface BlockState

All Superinterfaces:

Metadatable

All Known Subinterfaces:

Banner, Barrel, Beacon, Bed, Beehive, Bell, BlastFurnace, BrewingStand, Campfire, Chest, CommandBlock, Comparator, Conduit, Container, CreatureSpawner, DaylightDetector, Dispenser, Dropper, EnchantingTable, EnderChest, EndGateway, EntityBlockStorage<T>, Furnace, Hopper, Jigsaw, Jukebox, Lectern, ShulkerBox, Sign, Skull, Smoker, Structure, TileState

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
@NotNull Block	getBlock()	Gets the block represented by this block state.
@NotNull BlockData	getBlockData()	Gets the data for this block state.
@NotNull Chunk	getChunk()	Gets the chunk which contains the block represented by this block state.
@NotNull MaterialData	getData()	Gets the metadata for this block state.
byte	getLightLevel()	Gets the current light level of the block represented by this block state.
@NotNull Location	getLocation()	Gets the location of this block state.
@Nullable Location	getLocation(@Nullable Location loc)	Stores the location of this block state in the provided Location object.
byte	getRawData()	Deprecated. Magic value
@NotNull Material	getType()	Gets the type of this block state.
@NotNull 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(@NotNull BlockData data)	Sets the data for this block state.
void	setData(@NotNull MaterialData data)	Sets the metadata for this block state.
void	setRawData(byte data)	Deprecated. Magic value
void	setType(@NotNull 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 Detail

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
@NotNull MaterialData getData()

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

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

void setData(@NotNull
             @NotNull MaterialData data)

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