Skip to content

Block Operations

Jump to bottom
addavriance edited this page Jan 19, 2026 · 2 revisions

Block Operations

The Block class provides methods for interacting with blocks and their inventories in the Minecraft world.

Getting Started

# Get block API for a specific level
block = api.Block(minecraft:overworld)

Methods

getBlock

Get information about a block at specific coordinates.

block_info = await block.getBlock(x=10, y=64, z=20)
print(f"Block type: {block_info.type}")

Parameters:

  • x (int): X coordinate
  • y (int): Y coordinate
  • z (int): Z coordinate

Returns: BlockInfo object

setBlock

Place a block at specific coordinates.

await block.setBlock(x=10, y=64, z=20, block_id="minecraft:diamond_block")

Parameters:

  • x (int): X coordinate
  • y (int): Y coordinate
  • z (int): Z coordinate
  • block_id (str): Namespaced ID of the block

Common Block IDs:

  • minecraft:diamond_block - Diamond block
  • minecraft:gold_block - Gold block
  • minecraft:stone - Stone
  • minecraft:grass_block - Grass block
  • minecraft:oak_log - Oak log
  • minecraft:chest - Chest
  • minecraft:furnace - Furnace

Returns: bool - True if successful

breakBlock

Break a block at specific coordinates.

# Break and drop items
await block.breakBlock(x=10, y=64, z=20)

# Break without dropping items
await block.breakBlock(x=10, y=64, z=20, drop_items=False)

Parameters:

  • x (int): X coordinate
  • y (int): Y coordinate
  • z (int): Z coordinate
  • drop_items (bool): Whether to drop items (default: True)

Returns: bool - True if successful

getInventory

Get the inventory of a block entity (chest, furnace, etc.).

inventory = await block.getInventory(x=10, y=64, z=20)
for item in inventory.items:
    print(f"Slot {item.slot}: {item.type} x{item.count}")

Parameters:

  • x (int): X coordinate of the block entity
  • y (int): Y coordinate of the block entity
  • z (int): Z coordinate of the block entity

Supported Block Entities:

  • Chests (minecraft:chest)
  • Furnaces (minecraft:furnace)
  • Hoppers (minecraft:hopper)
  • Dispensers (minecraft:dispenser)
  • Droppers (minecraft:dropper)
  • Barrels (minecraft:barrel)
  • Shulker boxes (minecraft:shulker_box)

Returns: BlockInventory object

setInventorySlot

Set a specific slot in a block entity's inventory.

# Put 64 diamonds in slot 0 of a chest
await block.setInventorySlot(
    x=10, y=64, z=20,
    slot=0,
    item_id="minecraft:diamond",
    count=64
)

Parameters:

  • x (int): X coordinate
  • y (int): Y coordinate
  • z (int): Z coordinate
  • slot (int): Slot index (0-26 for chests, 0-8 for furnaces)
  • item_id (str): Namespaced ID of the item
  • count (int): Number of items (1-64 for most items)

Common Item IDs:

  • minecraft:diamond - Diamond
  • minecraft:gold_ingot - Gold ingot
  • minecraft:iron_ingot - Iron ingot
  • minecraft:emerald - Emerald
  • minecraft:golden_apple - Golden apple
  • minecraft:ender_pearl - Ender pearl

Returns: bool - True if successful

clearInventory

Remove all items from a block entity's inventory.

await block.clearInventory(x=10, y=64, z=20)

Parameters:

  • x (int): X coordinate
  • y (int): Y coordinate
  • z (int): Z coordinate

Returns: bool - True if successful

getFurnaceInfo

Get detailed information about a furnace's state.

furnace_info = await block.getFurnaceInfo(x=10, y=64, z=20)
print(f"Burn time: {furnace_info.burn_time}")
print(f"Cook time: {furnace_info.cook_time}")

Parameters:

  • x (int): X coordinate of the furnace
  • y (int): Y coordinate of the furnace
  • z (int): Z coordinate of the furnace

Returns: FurnaceInfo object with:

  • burn_time: Remaining fuel burn time in ticks
  • cook_time: Current cooking progress in ticks
  • cook_time_total: Total time needed for cooking

Examples

Building a Structure

# Build a 5x5 platform of diamond blocks
for x in range(-2, 3):
    for z in range(-2, 3):
        await block.setBlock(x=x, y=64, z=z, block_id="minecraft:diamond_block")

Setting up a Chest with Items

# Place a chest
await block.setBlock(x=10, y=64, z=20, block_id="minecraft:chest")

# Fill it with items
items = [
    ("minecraft:diamond", 64),
    ("minecraft:gold_ingot", 32),
    ("minecraft:iron_ingot", 64),
    ("minecraft:emerald", 16),
]

for slot, (item_id, count) in enumerate(items):
    await block.setInventorySlot(
        x=10, y=64, z=20,
        slot=slot,
        item_id=item_id,
        count=count
    )

Checking Furnace Progress

furnace_info = await block.getFurnaceInfo(x=10, y=64, z=20)
if furnace_info.cook_time > 0:
    progress = (furnace_info.cook_time / furnace_info.cook_time_total) * 100
    print(f"Smelting progress: {progress:.1f}%")

See Also

Clone this wiki locally