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`, `SculkSensor`, `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()`
Deprecated.
use `getBlockData()`
`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`
`isCollidable()`
Checks if this block state is collidable.
`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)`
Deprecated.
use `setBlockData(BlockData)`
`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 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 @NotNull MaterialData getData()
Deprecated.
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

### 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 void setData(@NotNull @NotNull MaterialData data)
Deprecated.
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 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