Block

endstone.block

Classes relating to the blocks in a world, including special states.

Classes:

Name	Description
Biome	Represents a biome.
Block	Represents a block.
BlockData	Represents the data related to a live block.
BlockFace
BlockState	Represents a captured state of a block, which will not update automatically.
BlockType	Represents a block type.
Campfire	Represents a captured state of a campfire.
Container	Represents a captured state of a container block, such as a chest.
CreatureSpawner	Represents a captured state of a creature spawner.
Furnace	Represents a captured state of a furnace.
ItemFrame	Represents a captured state of an item frame.
Lectern	Represents a captured state of a lectern.
Sign	Represents a captured state of a sign.
SignSide	Represents a side of a sign.

Biome

Represents a biome.

Methods:

Name	Description
get	Attempts to get the Biome with the given name.

Attributes:

Name	Type	Description
id	Identifier[Biome]	The identifier of this biome.
translation_key	str	The translation key, suitable for use in a translation component.

id property

id: Identifier[Biome]

The identifier of this biome.

translation_key property

translation_key: str

The translation key, suitable for use in a translation component.

get staticmethod

get(name: Identifier[Biome] | str) -> Biome

Attempts to get the Biome with the given name.

Parameters:

Name	Type	Description	Default
name	Identifier[Biome] | str	The identifier of the biome (e.g. minecraft:plains).	required

Returns:

Type	Description
Biome	The Biome, or None if no biome with that name exists.

Block

Represents a block.

Methods:

Name	Description
capture_state	Captures the current state of this block.
get_relative
set_data	Sets the complete data for this block.
set_type	Sets the type of this block.

Attributes:

Name	Type	Description
biome	Biome	The biome that this block resides in.
data	BlockData	The complete block data for this block.
dimension	Dimension	The dimension which contains this Block.
location	Location	The location of this block.
type	BlockType	The type of the block.
x	int	X-coordinate of this block.
y	int	Y-coordinate of this block.
z	int	Z-coordinate of this block.

biome property

biome: Biome

The biome that this block resides in.

data property

data: BlockData

The complete block data for this block.

dimension property

dimension: Dimension

The dimension which contains this Block.

location property

location: Location

The location of this block.

type property

type: BlockType

The type of the block.

x property

x: int

X-coordinate of this block.

y property

y: int

Y-coordinate of this block.

z property

z: int

Z-coordinate of this block.

capture_state

capture_state() -> BlockState

Captures the current state of this block.

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:

Type	Description
BlockState	A BlockState snapshot of the current state of this block.

get_relative

get_relative(
    offset_x: int, offset_y: int, offset_z: int
) -> Block

get_relative(face: BlockFace, distance: int = 1) -> Block

set_data

set_data(
    data: BlockData, apply_physics: bool = True
) -> None

Sets the complete data for this block.

Parameters:

Name	Type	Description	Default
data	BlockData	New block-specific data.	required
apply_physics	bool	False to cancel physics on the changed block.	True

set_type

set_type(
    type: Identifier[BlockType] | str,
    apply_physics: bool = True,
) -> None

Sets the type of this block.

Parameters:

Name	Type	Description	Default
type	Identifier[BlockType] | str	New type for this block (e.g. minecraft:stone).	required
apply_physics	bool	False to cancel physics on the changed block.	True

BlockData

Represents the data related to a live block.

Attributes:

Name	Type	Description
block_states	dict[str, bool | str | int]	The block states for this block.
runtime_id	int	The runtime id for this block.
translation_key	str	The translation key for this block.
type	BlockType	The block type represented by this block data.

block_states property

block_states: dict[str, bool | str | int]

The block states for this block.

When passed into Server.create_block_data(type, block_states) these will unambiguously recreate this instance.

runtime_id property

runtime_id: int

The runtime id for this block.

translation_key property

translation_key: str

The translation key for this block.

type property

type: BlockType

The block type represented by this block data.

BlockFace

Bases: Enum

Attributes:

Name	Type	Description
DOWN
EAST
NORTH
SOUTH
UP
WEST

DOWN class-attribute instance-attribute

DOWN = 0

EAST class-attribute instance-attribute

EAST = 5

NORTH class-attribute instance-attribute

NORTH = 2

SOUTH class-attribute instance-attribute

SOUTH = 3

UP class-attribute instance-attribute

UP = 1

WEST class-attribute instance-attribute

WEST = 4

BlockState

Represents a captured state of a block, which will not update 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.

Methods:

Name	Description
update	Attempts to update the block represented by this state, setting it to the new values defined by this state.

Attributes:

Name	Type	Description
block	Block	The block represented by this block state.
data	BlockData	The data for this block state.
dimension	Dimension	The dimension which contains the block represented by this block state.
location	Location	The location of this block state.
type	BlockType	The type of this block state.
x	int	X-coordinate of this block state.
y	int	Y-coordinate of this block state.
z	int	Z-coordinate of this block state.

block property

block: Block

The block represented by this block state.

data property writable

data: BlockData

The data for this block state.

dimension property

dimension: Dimension

The dimension which contains the block represented by this block state.

location property

location: Location

The location of this block state.

type property writable

type: BlockType

The type of this block state.

x property

x: int

X-coordinate of this block state.

y property

y: int

Y-coordinate of this block state.

z property

z: int

Z-coordinate of this block state.

update

update(
    force: bool = False, apply_physics: bool = True
) -> bool

Attempts to update the block represented by this state, setting it to the new values defined by this state.

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; in that case it returns False.

If force is True, the block type is set to match the new state, the state data is applied, and True is returned.

If apply_physics is True, a physics update is triggered on surrounding blocks, which could cause them to update or disappear.

Parameters:

Name	Type	Description	Default
force	bool	True to forcefully set the state.	False
apply_physics	bool	False to cancel updating physics on surrounding blocks.	True

Returns:

Type	Description
bool	True if the update was successful, False otherwise.

BlockType

Represents a block type.

Methods:

Name	Description
create_block_data	Creates a new BlockData instance for this block type, with all properties initialized to defaults.
get	Attempts to get the BlockType with the given name.

Attributes:

Name	Type	Description
has_item_type	bool	True if this BlockType has a corresponding ItemType.
id	Identifier[BlockType]	The identifier of this block type.
translation_key	str	The translation key, suitable for use in a translation component.

has_item_type property

has_item_type: bool

True if this BlockType has a corresponding ItemType.

id property

id: Identifier[BlockType]

The identifier of this block type.

translation_key property

translation_key: str

The translation key, suitable for use in a translation component.

create_block_data

create_block_data() -> BlockData

Creates a new BlockData instance for this block type, with all properties initialized to defaults.

Returns:

Type	Description
BlockData	A new BlockData instance.

get staticmethod

get(name: Identifier[BlockType] | str) -> BlockType

Attempts to get the BlockType with the given name.

Parameters:

Name	Type	Description	Default
name	Identifier[BlockType] | str	The identifier of the block type (e.g. minecraft:stone).	required

Returns:

Type	Description
BlockType	The BlockType, or None if no block type with that name exists.

Campfire

Bases: BlockState

Represents a captured state of a campfire.

Methods:

Name	Description
get_cook_time	Gets how long the item in the given slot has been cooking for, in ticks.
get_item	Gets the item currently cooking in the given slot.
set_cook_time	Sets how long the item in the given slot has been cooking for.
set_item	Sets the item currently cooking in the given slot.

Attributes:

Name	Type	Description
size	int	The number of items this campfire can cook at once.

size property

size: int

The number of items this campfire can cook at once.

get_cook_time

get_cook_time(index: int) -> int

Gets how long the item in the given slot has been cooking for, in ticks.

Parameters:

Name	Type	Description	Default
index	int	The slot, between 0 and size - 1.	required

Returns:

Type	Description
int	The cook time, in ticks.

get_item

get_item(index: int) -> ItemStack | None

Gets the item currently cooking in the given slot.

Parameters:

Name	Type	Description	Default
index	int	The slot, between 0 and size - 1.	required

Returns:

Type	Description
ItemStack | None	The item, or None if the slot is empty.

set_cook_time

set_cook_time(index: int, cook_time: int) -> None

Sets how long the item in the given slot has been cooking for.

Parameters:

Name	Type	Description	Default
index	int	The slot, between 0 and size - 1.	required
cook_time	int	The cook time, in ticks.	required

set_item

set_item(index: int, item: ItemStack | None) -> None

Sets the item currently cooking in the given slot.

Parameters:

Name	Type	Description	Default
index	int	The slot, between 0 and size - 1.	required
item	ItemStack | None	The item, or None to empty the slot.	required

Container

Bases: BlockState

Represents a captured state of a container block, such as a chest.

Attributes:

Name	Type	Description
inventory	Inventory	The inventory of the block represented by this block state.

inventory property

inventory: Inventory

The inventory of the block represented by this block state.

If the block was changed to a different type in the meantime, the returned inventory might no longer be valid.

CreatureSpawner

Bases: BlockState

Represents a captured state of a creature spawner.

Attributes:

Name	Type	Description
delay	int	The delay until the spawner spawns the next batch of actors, in ticks.
max_nearby_entities	int	The maximum number of similar actors allowed nearby before the spawner stops spawning.
max_spawn_delay	int	The maximum delay the spawner will wait between spawns, in ticks.
min_spawn_delay	int	The minimum delay the spawner will wait between spawns, in ticks.
required_player_range	int	How far away a player must be for the spawner to be active, in blocks.
spawn_count	int	How many actors the spawner attempts to spawn at a time.
spawn_range	int	The radius around the spawner in which actors are spawned, in blocks.
spawned_type	ActorType	The type of actor this spawner will spawn.

delay property writable

delay: int

The delay until the spawner spawns the next batch of actors, in ticks.

max_nearby_entities property writable

max_nearby_entities: int

The maximum number of similar actors allowed nearby before the spawner stops spawning.

max_spawn_delay property writable

max_spawn_delay: int

The maximum delay the spawner will wait between spawns, in ticks.

min_spawn_delay property writable

min_spawn_delay: int

The minimum delay the spawner will wait between spawns, in ticks.

required_player_range property writable

required_player_range: int

How far away a player must be for the spawner to be active, in blocks.

spawn_count property writable

spawn_count: int

How many actors the spawner attempts to spawn at a time.

spawn_range property writable

spawn_range: int

The radius around the spawner in which actors are spawned, in blocks.

spawned_type property writable

spawned_type: ActorType

The type of actor this spawner will spawn.

Furnace

Bases: Container

Represents a captured state of a furnace.

Attributes:

Name	Type	Description
burn_time	int	The burn time.
cook_time	int	The cook time.

burn_time property writable

burn_time: int

The burn time.

This is the number of ticks the current fuel keeps the furnace lit for. A burn time greater than 0 will cause this block to be lit, whilst a time less than 0 will extinguish it.

cook_time property writable

cook_time: int

The cook time.

This is the amount of time the item has been cooking for.

ItemFrame

Bases: BlockState

Represents a captured state of an item frame.

Attributes:

Name	Type	Description
item	ItemStack | None	The item in this frame.
item_drop_chance	float	The chance of the item being dropped upon this frame's destruction.
rotation	Rotation	The rotation of the frame's item.

item property writable

item: ItemStack | None

The item in this frame.

Reading this returns a defensive copy of the item, or None if the frame is empty. Assign None to empty the frame.

Assigning resets the rotation of the frame, as placing an item in a frame does in-game.

item_drop_chance property writable

item_drop_chance: float

The chance of the item being dropped upon this frame's destruction.

A drop chance of 0.0 will never drop, a drop chance of 1.0 will always drop.

rotation property writable

rotation: Rotation

The rotation of the frame's item.

Lectern

Bases: Container

Represents a captured state of a lectern.

Attributes:

Name	Type	Description
page	int	The page currently displayed on the lectern.

page property writable

page: int

The page currently displayed on the lectern.

The page is 0-indexed, and is clamped to the number of pages in the book the lectern holds.

Sign

Bases: BlockState

Represents a captured state of a sign.

Classes:

Name	Description
Side	Represents a side of a sign.

Methods:

Name	Description
get_side	Gets the side of this sign.

Attributes:

Name	Type	Description
waxed	bool	Whether this sign is waxed.

waxed property writable

waxed: bool

Whether this sign is waxed.

A waxed sign cannot be edited by players.

Side

Bases: Enum

Represents a side of a sign.

Attributes:

Name	Type	Description
BACK
FRONT

BACK class-attribute instance-attribute

BACK = 1

FRONT class-attribute instance-attribute

FRONT = 0

get_side

get_side(side: Side) -> SignSide

Gets the side of this sign.

Parameters:

Name	Type	Description	Default
side	Side	The side of the sign.	required

Returns:

Type	Description
SignSide	The given side of the sign.

SignSide

Represents a side of a sign.

Methods:

Name	Description
get_line	Gets the line of text at the specified index on this side of the sign.
set_line	Sets the line of text at the specified index on this side of the sign.

Attributes:

Name	Type	Description
color	tuple[int, ...]	The color of this side of the sign.
glowing_text	bool	Whether this side of the sign has glowing text.
lines	list[str]	All the lines of text currently on this side of the sign.

color property writable

color: tuple[int, ...]

The color of this side of the sign.

Bedrock stores the text color of a sign as a color rather than as one of the dyes, so this is a Color where Bukkit has a DyeColor.

glowing_text property writable

glowing_text: bool

Whether this side of the sign has glowing text.

lines property

lines: list[str]

All the lines of text currently on this side of the sign.

get_line

get_line(index: int) -> str

Gets the line of text at the specified index on this side of the sign.

For example, get_line(0) will return the first line of text.

Parameters:

Name	Type	Description	Default
index	int	The index of the line to get, between 0 and 3.	required

Returns:

Type	Description
str	The text of the line, empty if the line is blank.

set_line

set_line(index: int, line: str) -> None

Sets the line of text at the specified index on this side of the sign.

For example, set_line(0, "Line One") will set the first line to "Line One".

Parameters:

Name	Type	Description	Default
index	int	The index of the line to set, between 0 and 3.	required
line	str	The new text to set.	required