Block in the world

Block

A Block represents a single block in the world. You get block references from World.block_at() or event properties.

---

Constructor

Block(world=None, x=None, y=None, z=None, material=None)

Create a block reference.

• Parameters:
• world (World | str | None) — World reference.
• x (int | None) — X coordinate.
• y (int | None) — Y coordinate.
• z (int | None) — Z coordinate.
• material (Material | str | None) — Block material.

---

Class Methods

create

block = await Block.create(location, material)

Create (place) a block at a location.

• Parameters:
• location (Location) — Where to place the block.
• material (Material | str) — Block material.
• Returns: Awaitable[Block]

block = await Block.create(player.location.add(0, -1, 0), Material.DIAMOND_BLOCK)

---

Attributes

x

• Type: int

Block X coordinate.

y

• Type: int

Block Y coordinate.

z

• Type: int

Block Z coordinate.

type

• Type: Material

The block's material type.

location

• Type: Location

The block's location.

world

• Type: World

The world this block is in.

is_solid

• Type: bool

Whether the block is solid (not air, water, etc.).

data

• Type: any

The block's data state (e.g., slab halves, stair direction). Varies by block type.

light_level

• Type: int

Light level at this block (0–15).

biome

• Type: Biome

The biome at this block's location.

---

Methods

break_naturally

await block.break_naturally()

Break the block as if a player mined it (drops items).

• Returns: Awaitable[None]

set_type

await block.set_type(material)

Change the block's material.

• Parameters:
• material (Material) — The new material.
• Returns: Awaitable[None]

await block.set_type(Material.AIR)  # Delete the block

set_data

await block.set_data(data)

Set the block's data state.

• Parameters:
• data (any) — Block data value.
• Returns: Awaitable[None]

---

Container Properties

These work on blocks that hold inventories (chests, hoppers, dispensers, droppers, barrels, etc.).

inventory

• Type: Inventory | None

The block's inventory, or None if the block isn't a container.

chest = world.block_at(10, 64, 20)
inv = chest.inventory
if inv:
    items = inv.contents

is_container

• Type: bool

Whether this block has an inventory.

state_type

• Type: str

The tile entity type name (e.g. "Sign", "Chest", "Furnace", "Hopper").

---

Sign Methods

These work on sign blocks (oak sign, birch sign, etc.). Properties return None if the block isn't a sign.

sign_lines

• Type: list[str] | None

Front side text as a list of 4 strings.

sign = world.block_at(10, 64, 20)
lines = sign.sign_lines  # ["Hello", "World", "", ""]

sign_back_lines

• Type: list[str] | None

Back side text as a list of 4 strings.

set_sign_line

await block.set_sign_line(index, text)

Set a single front sign line.

• Parameters:
• index (int) — Line index (0–3).
• text (str) — Line text.
• Returns: Awaitable[None]

set_sign_lines

await block.set_sign_lines(lines)

Set all front sign lines at once.

• Parameters:
• lines (list[str]) — Up to 4 lines.
• Returns: Awaitable[None]

await sign.set_sign_lines(["Welcome", "to the", "shop!", ""])

set_sign_back_line / set_sign_back_lines

Same as front-side methods, but for the back of the sign.

set_sign_glowing

await block.set_sign_glowing(glowing)

Set whether the front sign text glows.

• Parameters:
• glowing (bool) — Whether text should glow.
• Returns: Awaitable[None]

is_sign_glowing

• Type: bool | None

Whether the front sign text is glowing. None if not a sign.

---

Furnace Methods

These work on furnace blocks (furnace, blast furnace, smoker). Properties return None if the block isn't a furnace.

furnace_burn_time

• Type: int | None

Remaining fuel burn time in ticks.

furnace_cook_time

• Type: int | None

Current cooking progress in ticks.

furnace_cook_time_total

• Type: int | None

Total cook time needed for the current item.

set_furnace_burn_time

await block.set_furnace_burn_time(ticks)

Set remaining fuel burn time.

• Parameters:
• ticks (int) — Burn time in ticks.
• Returns: Awaitable[None]

set_furnace_cook_time

await block.set_furnace_cook_time(ticks)

Set cooking progress.

• Parameters:
• ticks (int) — Cook time in ticks.
• Returns: Awaitable[None]

furnace = world.block_at(10, 64, 20)
if furnace.state_type == "Furnace":
    print(f"Cook progress: {furnace.furnace_cook_time}/{furnace.furnace_cook_time_total}")
    inv = furnace.inventory

set_biome

await block.set_biome(biome)

Change the biome at this block's position.

• Parameters:
• biome (Biome) — The new biome.
• Returns: Awaitable[None]