Package org.bukkit.block

Interface BlockState

All Superinterfaces:

Metadatable

All Known Subinterfaces:

Banner, Barrel, Beacon, Bed, Bell, BlastFurnace, BrewingStand, Campfire, Chest, CommandBlock, Comparator, Conduit, Container, CreatureSpawner, DaylightDetector, Dispenser, Dropper, EnchantingTable, EnderChest, EndGateway, FlowerPot, Furnace, Hopper, Jigsaw, Jukebox, Lectern, NoteBlock, 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
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 Detail

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

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