Client

Client

Python

Client(username: str, **options: Any)

Minecraft client.

PARAMETER	DESCRIPTION
username	The username to use for the connection. TYPE: str
**options	Configuration options for the client connection. load_chunks: bool Whether to load and store chunk data in memory. Default is True. TYPE: Any DEFAULT: {}

user property

Python

user: Optional[User]

Get the current user.

RETURNS	DESCRIPTION
Optional[User]	The current user object, or None if not connected.

difficulty async property

Python

difficulty: Optional[int]

Get the current world difficulty.

RETURNS	DESCRIPTION
Optional[int]	The difficulty level, or None if not available.

max_players async property

Python

max_players: Optional[int]

Get the maximum number of players allowed on the server.

RETURNS	DESCRIPTION
Optional[int]	The maximum player count, or None if not available.

world_type async property

Python

world_type: Optional[str]

Get the world type.

RETURNS	DESCRIPTION
Optional[str]	The world type string, or None if not available.

world_age async property

Python

world_age: Optional[int]

Get the age of the world in ticks.

RETURNS	DESCRIPTION
Optional[int]	The world age in ticks, or None if not available.

time_of_day async property

Python

time_of_day: Optional[int]

Get the current time of day.

RETURNS	DESCRIPTION
Optional[int]	The time of day in ticks, or None if not available.

entities property

Python

entities: Dict[int, Entity]

Get all currently tracked entities.

RETURNS	DESCRIPTION
Dict[int, Entity]	A dictionary mapping entity IDs to Entity.

world_border property

Python

world_border: Optional[WorldBorder]

Get the world border information.

RETURNS	DESCRIPTION
Optional[WorldBorder]	The world border object, or None if not available.

chunks property

Python

chunks: Dict[Vector2D[int], Chunk]

Get the loaded chunks.

RETURNS	DESCRIPTION
Dict[Vector2D[int], Chunk]	Dictionary mapping chunk coordinates to chunk.

tablist property

Python

tablist: Dict[str, PlayerInfo]

Get the player tab list.

RETURNS	DESCRIPTION
Dict[str, PlayerInfo]	A dictionary mapping player UIDs to PlayerInfo.

windows property

Python

windows: Dict[int, Window]

Get the open windows/inventories.

RETURNS	DESCRIPTION
Dict[int, Window]	Dictionary mapping window IDs to Window.

boss_bars property

Python

boss_bars: Dict[str, BossBar]

Get the active boss bars.

RETURNS	DESCRIPTION
Dict[str, BossBar]	Dictionary mapping boss bar UUIDs to BossBar.

scoreboard property

Python

scoreboard: Dict[str, Scoreboard]

Get the scoreboard objectives.

RETURNS	DESCRIPTION
Dict[str, Scoreboard]	Dictionary mapping objective names to ScoreboardObjective.

action_bar property

Python

action_bar: Title

Get the action bar title.

RETURNS	DESCRIPTION
Title	The current action bar title.

is_ready property

Python

is_ready: bool

Check whether the client's internal cache is ready.

RETURNS	DESCRIPTION
bool	True if the client is fully initialized and ready to be used, False otherwise.

clear

Python

clear() -> None

Clear the internal state of the bot.

Resets the bot to an uninitialized state, clearing all internal caches and connection state.

close async

Python

close() -> None

Close the connection to the Minecraft server.

If a closing task is already running, it waits for it to complete.

If the socket is open, it is closed with proper cleanup. After closing the socket, it clears the connection state and closes the TCP client.

event

Python

event(coro: Callable[..., Any]) -> None

Register a coroutine function as an event handler.

This method assigns the given coroutine function to be used as an event handler with the same name as the coroutine function.

PARAMETER	DESCRIPTION
coro	The coroutine function to register as an event handler. TYPE: Callable[..., Any]

RAISES	DESCRIPTION
TypeError	If the provided function is not a coroutine function.

dispatch

Python

dispatch(event: str, /, *args: Any, **kwargs: Any) -> None

Dispatch a specified event with a coroutine callback.

PARAMETER	DESCRIPTION
event	The name of the event to dispatch. TYPE: str
*args	Positional arguments to pass to the event handler. TYPE: Any DEFAULT: ()
**kwargs	Keyword arguments to pass to the event handler. TYPE: Any DEFAULT: {}

on_error async staticmethod

Python

on_error(
    event_method: str,
    error: Exception,
    /,
    *args: Any,
    **kwargs: Any,
) -> None

Handle errors occurring during event dispatch.

This static method logs an exception that occurred during the processing of an event.

PARAMETER	DESCRIPTION
event_method	The event that caused the error. TYPE: str
error	The exception that was raised. TYPE: Exception
*args	Positional arguments passed to the event. TYPE: Any DEFAULT: ()
**kwargs	Keyword arguments passed to the event. TYPE: Any DEFAULT: {}

setup_hook async

Python

setup_hook() -> None

Perform additional setup before the client is connected.

Warning

Do not use wait_until_ready() within this method as it may cause it to freeze.

You can configure or set up additional extensions or services as required.

wait_until_ready async

Python

wait_until_ready() -> None

Wait until the client's internal cache is ready.

This coroutine blocks until the client's internal state is fully initialized and ready to be used.

RAISES	DESCRIPTION
RuntimeError	If the client has not been initialized. Ensure that you use the asynchronous context manager to initialize the client.

Warnings

Calling this method inside setup_hook() may cause a deadlock.

connect async

Python

connect(host: str, port: int) -> None

Connect to a Minecraft server.

PARAMETER	DESCRIPTION
host	The server hostname or IP address. TYPE: str
port	The server port number. TYPE: int

RAISES	DESCRIPTION
ConnectionClosed	If the connection is interrupted unexpectedly.
ClientException	If the client fails to connect.

Warnings

Repeated calls to this method without delays may trigger server rate limiting. Implement appropriate delays between connection attempts.

Notes

By using this, you agree to Minecraft's EULA:

https://account.mojang.com/documents/minecraft_eula

start async

Python

start(host: str, port: int = 25565) -> None

Start the client and connect to the server.

PARAMETER	DESCRIPTION
host	The server hostname or IP address. TYPE: str
port	The server port number. TYPE: int DEFAULT: 25565

run

Python

run(
    host: str,
    port: int = 25565,
    *,
    log_handler: Optional[logging.Handler] = None,
    log_level: Optional[
        Literal[0, 5, 10, 20, 30, 40, 50]
    ] = None,
    root_logger: bool = False
) -> None

Start the client.

PARAMETER	DESCRIPTION
host	The server hostname or IP address. TYPE: str
port	The server port number. TYPE: int DEFAULT: 25565
log_handler	A logging handler to be used for logging output. TYPE: Optional[logging.Handler] DEFAULT: None
log_level	The logging level to be used (NOTSET=0, TRACE=5, DEBUG=10, INFO=20, WARNING=30, ERROR=40, CRITICAL=50). TYPE: Optional[Literal[0, 5, 10, 20, 30, 40, 50]] DEFAULT: None
root_logger	If True, the logging configuration applies to the root logger; otherwise, it applies to a new logger. TYPE: bool DEFAULT: False

Warning

The client does NOT perform automatic SRV record lookups. To connect to domains using SRV records (e.g., Minecraft hosts), you must resolve the port yourself and provide it explicitly. If omitted, the default port 25565 is used.

get_block

Python

get_block(pos: Vector3D[int]) -> Optional[Block]

Get the block at the specified position.

PARAMETER	DESCRIPTION
pos	The position coordinates of the block. TYPE: Vector3D[int]

RETURNS	DESCRIPTION
Optional[Block]	The block at the specified position, or None if not available.

perform_respawn async

Python

perform_respawn() -> None

Request the server to respawn the player.

request_stats async

Python

request_stats() -> None

Request the player's statistics from the server.

Notes

The server responds by sending the statistics, which are usually processed in the on_statistics handler.

request_tab_complete async

Python

request_tab_complete(
    text: str, assume_command: bool = False
) -> None

Request tab completion suggestions from the server.

PARAMETER	DESCRIPTION
text	All text behind the cursor (e.g. to the left of the cursor in left-to-right languages like English). TYPE: str
assume_command	If true, the server will parse Text as a command even if it doesn't start with a /. Used in the command block GUI. Defaults to False. TYPE: bool DEFAULT: False

Notes

The server responds by sending completion suggestions, which are usually processed in the on_tab_complete handler.

request_tab_complete_with_position async

Python

request_tab_complete_with_position(
    text: str,
    looked_at_block: Vector3D[int],
    assume_command: bool = False,
) -> None

Request tab completion suggestions with block position context.

PARAMETER	DESCRIPTION
text	All text behind the cursor. TYPE: str
looked_at_block	Position of the block being looked at. TYPE: Vector3D[int]
assume_command	If True, parse text as command even without /. TYPE: bool DEFAULT: False

Notes

The server responds by sending completion suggestions, which are usually processed in the on_tab_complete handler.

send_client_settings async

Python

send_client_settings(
    locale: str = "en_US",
    view_distance: int = 10,
    chat_mode: int = 0,
    chat_colors: bool = True,
    cape: bool = True,
    jacket: bool = True,
    left_sleeve: bool = True,
    right_sleeve: bool = True,
    left_pants: bool = True,
    right_pants: bool = True,
    hat: bool = True,
    main_hand: int = 1,
) -> None

Send client settings to the server.

PARAMETER	DESCRIPTION
locale	Client locale (e.g., "en_US"). TYPE: str DEFAULT: 'en_US'
view_distance	Render distance (2-32). TYPE: int DEFAULT: 10
chat_mode	Chat mode (0=enabled, 1=commands only, 2=hidden). TYPE: int DEFAULT: 0
chat_colors	Whether to display chat colors. TYPE: bool DEFAULT: True
cape	Whether to display cape. TYPE: bool DEFAULT: True
jacket	Whether to display jacket overlay. TYPE: bool DEFAULT: True
left_sleeve	Whether to display left sleeve overlay. TYPE: bool DEFAULT: True
right_sleeve	Whether to display right sleeve overlay. TYPE: bool DEFAULT: True
left_pants	Whether to display left pants overlay. TYPE: bool DEFAULT: True
right_pants	Whether to display right pants overlay. TYPE: bool DEFAULT: True
hat	Whether to display hat overlay. TYPE: bool DEFAULT: True
main_hand	Main hand (0=left, 1=right). TYPE: int DEFAULT: 1

send_message async

Python

send_message(message: str) -> None

Send a chat message to the server.

PARAMETER	DESCRIPTION
message	The message to send. TYPE: str

request_advancement_tab async

Python

request_advancement_tab(tab_id: str) -> None

Request to open a specific advancement tab.

PARAMETER	DESCRIPTION
tab_id	The advancement tab identifier, Valid tabs: minecraft:story/root minecraft:nether/root minecraft:end/root minecraft:adventure/root minecraft:husbandry/root TYPE: str

Notes

The server responds by sending the advancement data, which are usually processed in the on_advancements handler.

close_advancement_tab async

Python

close_advancement_tab() -> None

Close the advancement tab.

set_resource_pack_status async

Python

set_resource_pack_status(result: int) -> None

Respond to a resource pack request.

PARAMETER	DESCRIPTION
result	Status code (0=loaded, 1=declined, 2=failed, 3=accepted). TYPE: int

set_displayed_recipe async

Python

set_displayed_recipe(recipe_id: int) -> None

Set the currently displayed recipe in the crafting book.

This method sends a Crafting Book Data packet (type 0) to the server to update which recipe is currently being shown or highlighted in the crafting book interface. The recipe will be visually highlighted for the player.

PARAMETER	DESCRIPTION
recipe_id	The internal ID of the recipe to display. This ID corresponds to the server's recipe registry and must be a valid recipe identifier. TYPE: int

set_crafting_book_status async

Python

set_crafting_book_status(
    crafting_book_open: bool, crafting_filter: bool
) -> None

Update the crafting book's open state and filter settings.

This method sends a Crafting Book Data packet (type 1) to the server to update the player's crafting book interface state. Controls both the visibility of the crafting book and whether the crafting filter is active.

PARAMETER	DESCRIPTION
crafting_book_open	Whether the crafting book is currently opened/active in the UI. When True, the crafting book will be visible to the player. TYPE: bool
crafting_filter	Whether the crafting filter option is currently active. When True, only shows recipes that can be crafted with available materials. TYPE: bool

craft_recipe async

Python

craft_recipe(
    window: Window, recipe_id: int, make_all: bool = False
) -> None

Request to craft a recipe from the recipe book.

Sends a craft recipe request packet to the server to craft items using a known recipe. This is equivalent to clicking on a recipe in the recipe book.

PARAMETER	DESCRIPTION
window	The crafting window object that contains the crafting interface. Must be a valid crafting table or player inventory crafting area. TYPE: Window
recipe_id	The internal ID to craft. Must correspond to a valid recipe in the server's recipe registry. TYPE: int
make_all	Whether to craft as many items as possible (shift-click behavior). When True, crafts the maximum number of items possible with available materials. TYPE: bool DEFAULT: False

enchant_item async

Python

enchant_item(window: Window, enchantment: int) -> None

Request to enchant an item using the enchantment table.

Sends an enchant item packet to apply the selected enchantment to an item in the enchantment table. Requires the player to have sufficient experience and lapis lazuli.

PARAMETER	DESCRIPTION
window	The enchantment table window object. Must be a valid enchantment table interface with an item placed in the enchantment slot. TYPE: Window
enchantment	The position of the enchantment option in the enchantment table interface. Valid values are 0, 1, or 2 (top, middle, bottom enchantment options). TYPE: int

click_window_slot async

Python

click_window_slot(
    window: Window, slot: int, button: int, mode: int
) -> None

Perform a raw click operation on a window slot.

This is the low-level method for all window interactions. Different combinations of button and mode parameters create different click behaviors (left click, right click, shift click, etc.).

PARAMETER	DESCRIPTION
window	The window object containing the slot to click. TYPE: Window
slot	The slot number to click. Slot numbering starts at 0 and varies by window type. TYPE: int
button	The mouse button used for the click. 0=left, 1=right, 2=middle. TYPE: int
mode	The inventory operation mode. Different modes enable different behaviors: 0=normal click, 1=shift click, 2=number key, 3=middle click, 4=drop, 5=drag, 6=double click. TYPE: int

Notes

Most users should prefer the higher-level methods like pickup_item() or place_item() instead of calling this directly.

drop_item async

Python

drop_item(
    window: Window, slot: int, drop_stack: bool = False
) -> None

Drop an item from a window slot onto the ground.

Removes an item from the specified slot and drops it as an item entity in the world near the player. Uses the drop operation mode (4).

PARAMETER	DESCRIPTION
window	The window object containing the slot to drop from. TYPE: Window
slot	The slot number to drop items from. Must contain an item to drop. TYPE: int
drop_stack	Whether to drop the entire stack or just one item. When True, drops all items in the slot. When False, drops only one item. TYPE: bool DEFAULT: False

Warning

Implement appropriate rate limiting between consecutive calls to prevent server-side rejection. Excessive rapid invocations may result in dropped packets and failed item operations.

pickup_item async

Python

pickup_item(window: Window, slot: int) -> None

Pick up an item from a window slot (left click).

Performs a left-click operation on the specified slot to pick up the item. If the cursor already holds an item, this will attempt to merge stacks.

PARAMETER	DESCRIPTION
window	The window object containing the slot to pick up from. TYPE: Window
slot	The slot number to pick up from. Must contain an item to pick up. TYPE: int

place_item async

Python

place_item(
    window: Window, slot: int, single_item: bool = False
) -> None

Place an item in a window slot.

Places the item currently held by the cursor into the specified slot. Can place either a single item or the entire stack.

PARAMETER	DESCRIPTION
window	The window object containing the slot to place into. TYPE: Window
slot	The slot number to place the item in. TYPE: int
single_item	Whether to place only one item (right-click) or the entire stack (left-click). When True, places only one item. When False, places the entire stack. TYPE: bool DEFAULT: False

shift_click_item async

Python

shift_click_item(window: Window, slot: int) -> None

Shift-click an item for quick transfer.

Performs a shift-click operation to quickly move items between inventory sections (e.g., from chest to player inventory or vice versa).

PARAMETER	DESCRIPTION
window	The window object containing the slot to shift-click. TYPE: Window
slot	The slot number to shift-click. Must contain an item to transfer. TYPE: int

hotbar_swap async

Python

hotbar_swap(
    window: Window, slot: int, hotbar_key: int
) -> None

Swap item with hotbar using number keys 1-9.

Swaps the item in the specified slot with the item in the corresponding hotbar slot. This mimics pressing number keys 1-9 while hovering over a slot.

PARAMETER	DESCRIPTION
window	The window object containing the slot to swap with. TYPE: Window
slot	The slot number to swap with the hotbar. TYPE: int
hotbar_key	The hotbar key (0-8, corresponding to keys 1-9). TYPE: int

middle_click_item async

Python

middle_click_item(window: Window, slot: int) -> None

Middle-click an item (creative mode only).

Performs a middle-click operation on the specified slot. This is only functional in creative mode and typically duplicates the item.

PARAMETER	DESCRIPTION
window	The window object containing the slot to middle-click. TYPE: Window
slot	The slot number to middle-click. TYPE: int

Notes

Only works in creative mode and in non-player inventories.

double_click_item async

Python

double_click_item(window: Window, slot: int) -> None

Double-click to collect similar items.

Performs a double-click operation to gather all similar items from the inventory into the clicked slot's stack.

PARAMETER	DESCRIPTION
window	The window object containing the slot to double-click. TYPE: Window
slot	The slot number to double-click. Should contain the item type to collect. TYPE: int

click_outside_window async

Python

click_outside_window(
    window: Window, right_click: bool = False
) -> None

Click outside window to drop held item.

Drops the item currently held by the cursor by clicking outside the window area. The item will be dropped as an entity in the world.

PARAMETER	DESCRIPTION
window	The window object to click outside-of. TYPE: Window
right_click	Whether to perform a right-click or left-click outside the window. TYPE: bool DEFAULT: False

start_drag async

Python

start_drag(window: Window, drag_type: int = 0) -> None

Start a drag operation.

Initiates a drag operation for distributing items across multiple slots. A drag operation allows you to spread items from a stack evenly across multiple slots by clicking and dragging over them. For example, dragging a stack of 64 items over 4 slots will place 16 items in each slot.

Must be followed by add_drag_slot() calls and end_drag().

PARAMETER	DESCRIPTION
window	The window object to start dragging in. TYPE: Window
drag_type	The type of drag operation: - 0: Left drag (distributes entire stack evenly) - 4: Right drag (places one item per slot) - 8: Middle drag (creative mode only, duplicates items) TYPE: int DEFAULT: 0

add_drag_slot async

Python

add_drag_slot(
    window: Window, slot: int, drag_type: int = 1
) -> None

Add slot to drag operation.

Adds a slot to the current drag operation. Must be called between start_drag() and end_drag().

PARAMETER	DESCRIPTION
window	The window object containing the slot to add. TYPE: Window
slot	The slot number to add to the drag operation. TYPE: int
drag_type	The drag operation type. 1=left drag, 5=right drag, 9=middle drag. TYPE: int DEFAULT: 1

end_drag async

Python

end_drag(window: Window, drag_type: int = 2) -> None

End drag operation.

Completes the drag operation and distributes items to all slots that were added with add_drag_slot().

PARAMETER	DESCRIPTION
window	The window object to end dragging in. TYPE: Window
drag_type	The drag operation type. 2=left drag, 6=right drag, 10=middle drag. TYPE: int DEFAULT: 2

drag_distribute_items async

Python

drag_distribute_items(
    window: Window, slots: list[int], drag_type: int = 0
) -> None

Distribute items across multiple slots using drag.

Performs a complete drag operation to distribute the held item stack across the specified slots. This is a convenience method that combines start_drag(), add_drag_slot(), and end_drag().

PARAMETER	DESCRIPTION
window	The window object to perform the drag operation in. TYPE: Window
slots	List of slot numbers to distribute items to. TYPE: list[int]
drag_type	The drag operation type. 0=left drag, 4=right drag, 8=middle drag. TYPE: int DEFAULT: 0

close_window async

Python

close_window(window: Window) -> None

Close a window.

Sends a close window packet to the server to close the specified window. Any items in the window will be handled according to the window type.

PARAMETER	DESCRIPTION
window	The window object to close. TYPE: Window

Notes

Clients send window ID 0 to close their inventory even though there's never an Open Window packet for the inventory.

set_creative_item async

Python

set_creative_item(slot: int, item: Item) -> None

Set an item in creative mode inventory slot.

Places an item directly into the specified creative mode inventory slot. This bypasses normal inventory rules and can create items from nothing.

PARAMETER	DESCRIPTION
slot	The inventory slot number to set the item in. TYPE: int
item	The item object to place in the slot. TYPE: Item

clear_creative_slot async

Python

clear_creative_slot(slot: int) -> None

Clear an item from creative mode inventory slot.

Removes an item from the specified creative mode inventory slot. The item is permanently deleted.

PARAMETER	DESCRIPTION
slot	The inventory slot number to clear. TYPE: int

drop_creative_item async

Python

drop_creative_item(item: Item) -> None

Drop an item from creative inventory into the world.

Spawns an item entity in the world near the player without removing it from any inventory slot. Creates the item from nothing.

PARAMETER	DESCRIPTION
item	The item object to drop/spawn in the world. TYPE: Item

creative_inventory_set async

Python

creative_inventory_set(slot: int, item: Item) -> None

Set an item in creative inventory slot.

Low-level method for placing items directly into creative mode inventory slots. This bypasses normal inventory rules and can create items from nothing.

PARAMETER	DESCRIPTION
slot	The inventory slot number to set the item in. Use -1 to drop an item outside the inventory. TYPE: int
item	The item object to place in the slot. TYPE: Item

creative_inventory_clear async

Python

creative_inventory_clear(slot: int) -> None

Clear an item from creative inventory slot.

Low-level method for removing items from creative mode inventory slots. The item is permanently deleted from the slot.

PARAMETER	DESCRIPTION
slot	The inventory slot number to clear. TYPE: int