soulfire.bot_connect.BotService

class soulfire.bot_connect.BotService[source]

Bases: Protocol

Service for managing and controlling Minecraft bots. Provides comprehensive APIs for bot monitoring, movement control, inventory management, and interaction with server dialogs.

Permissions: - READ_BOT_INFO: Required for GetBotList, GetBotInfo, GetInventoryState,

RenderBotPov, GetDialog

  • CONTROL_BOTS: Required to start, stop, or restart bots

  • UPDATE_BOT_CONFIG: Required for persistent per-bot setting changes

  • CONTROL_BOT_ACTIONS: Required for live movement, inventory, and dialog actions

Error Handling: - NOT_FOUND: Instance or bot does not exist - FAILED_PRECONDITION: Bot is not online or required game state is unavailable - INTERNAL: Unexpected server errors (check server logs for details)

async set_bots_desired_state(request: soulfire.bot_pb2.SetBotsDesiredStateRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.SetBotsDesiredStateRequest, soulfire.bot_pb2.SetBotsDesiredStateResponse], /) → soulfire.bot_pb2.SetBotsDesiredStateResponse[source]

Persists whether the selected bots should be running or stopped. The request returns after the desired state is durable. Connections are reconciled asynchronously and can be observed through WatchBotStatuses.

async restart_bots(request: soulfire.bot_pb2.RestartBotsRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.RestartBotsRequest, soulfire.bot_pb2.RestartBotsResponse], /) → soulfire.bot_pb2.RestartBotsResponse[source]

Forces the selected bots to establish fresh connections.

watch_bot_statuses(request: soulfire.bot_pb2.WatchBotStatusesRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.WatchBotStatusesRequest, soulfire.bot_pb2.WatchBotStatusesResponse], /) → collections.abc.AsyncIterator[soulfire.bot_pb2.WatchBotStatusesResponse][source]

Streams an initial snapshot followed by desired and runtime state changes.

async get_bot_list(request: soulfire.bot_pb2.BotListRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotListRequest, soulfire.bot_pb2.BotListResponse], /) → soulfire.bot_pb2.BotListResponse[source]

Returns a list of all bots configured in the specified instance. Includes both online and offline bots with their current status. For online bots, includes live state (position, health, etc.) but NOT full inventory data. Requires READ_BOT_INFO permission.

async get_bot_info(request: soulfire.bot_pb2.BotInfoRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotInfoRequest, soulfire.bot_pb2.BotInfoResponse], /) → soulfire.bot_pb2.BotInfoResponse[source]

Returns detailed information about a specific bot. Includes full live state with complete inventory data when the bot is online. Requires READ_BOT_INFO permission.

async update_bot_config_entry(request: soulfire.bot_pb2.BotUpdateConfigEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotUpdateConfigEntryRequest, soulfire.bot_pb2.BotUpdateConfigEntryResponse], /) → soulfire.bot_pb2.BotUpdateConfigEntryResponse[source]

Updates a single configuration entry for a specific bot. The configuration is persisted to the database immediately. Requires UPDATE_BOT_CONFIG permission.

async delete_bot_config_entry(request: soulfire.bot_pb2.BotDeleteConfigEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotDeleteConfigEntryRequest, soulfire.bot_pb2.BotDeleteConfigEntryResponse], /) → soulfire.bot_pb2.BotDeleteConfigEntryResponse[source]

Removes one bot override without replacing account settings or metadata. Repeated requests succeed when the override is already absent.

async render_bot_pov(request: soulfire.bot_pb2.BotRenderPovRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotRenderPovRequest, soulfire.bot_pb2.BotRenderPovResponse], /) → soulfire.bot_pb2.BotRenderPovResponse[source]

Renders the bot’s point-of-view as a PNG image using headless Vulkan. The bot must be online with a valid player and level. Uses the bot’s current render distance setting. Requires READ_BOT_INFO permission.

watch_bot_pov(request: soulfire.bot_pb2.BotWatchPovRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotWatchPovRequest, soulfire.bot_pb2.BotPovFrame], /) → collections.abc.AsyncIterator[soulfire.bot_pb2.BotPovFrame][source]

Streams rendered POV frames. Slow consumers receive the newest available frame and an explicit dropped-frame count instead of an unbounded backlog.

async get_bot_world_map(request: soulfire.bot_pb2.BotWorldMapRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotWorldMapRequest, soulfire.bot_pb2.BotWorldMapResponse], /) → soulfire.bot_pb2.BotWorldMapResponse[source]

Samples loaded terrain and optional entity overlays for top-down viewers.

async click_inventory_slot(request: soulfire.bot_pb2.BotInventoryClickRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotInventoryClickRequest, soulfire.bot_pb2.BotInventoryClickResponse], /) → soulfire.bot_pb2.BotInventoryClickResponse[source]

Performs a click action on an inventory/container slot. Supports various click types (left, right, shift, drop, swap, middle). The bot must be online with a valid player and gameMode. Requires CONTROL_BOT_ACTIONS permission.

async get_inventory_state(request: soulfire.bot_pb2.BotInventoryStateRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotInventoryStateRequest, soulfire.bot_pb2.BotInventoryStateResponse], /) → soulfire.bot_pb2.BotInventoryStateResponse[source]

Returns the current state of the bot’s open container/inventory. Includes layout information, slot contents, and carried item. The bot must be online with a valid player. Requires READ_BOT_INFO permission.

async close_container(request: soulfire.bot_pb2.BotCloseContainerRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotCloseContainerRequest, soulfire.bot_pb2.BotCloseContainerResponse], /) → soulfire.bot_pb2.BotCloseContainerResponse[source]

Closes the currently open container (chest, crafting table, etc.). Returns to the player inventory view. The bot must be online with a valid player. Requires CONTROL_BOT_ACTIONS permission.

async open_inventory(request: soulfire.bot_pb2.BotOpenInventoryRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotOpenInventoryRequest, soulfire.bot_pb2.BotOpenInventoryResponse], /) → soulfire.bot_pb2.BotOpenInventoryResponse[source]

Opens the player’s inventory screen. Sends a packet to the server to display the inventory UI. The bot must be online with a valid player. Requires CONTROL_BOT_ACTIONS permission.

async mouse_click(request: soulfire.bot_pb2.BotMouseClickRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotMouseClickRequest, soulfire.bot_pb2.BotMouseClickResponse], /) → soulfire.bot_pb2.BotMouseClickResponse[source]

Simulates a mouse click in the game world. Left click: attack entity or start breaking block. Right click: use item or interact with entity/block. The bot must be online with valid player, level, and gameMode. Requires CONTROL_BOT_ACTIONS permission.

async click_container_button(request: soulfire.bot_pb2.BotContainerButtonClickRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotContainerButtonClickRequest, soulfire.bot_pb2.BotContainerButtonClickResponse], /) → soulfire.bot_pb2.BotContainerButtonClickResponse[source]

Clicks a container-specific action button. Used for: stonecutter recipes, enchanting, loom patterns, villager trades, beacon effects, crafter slot toggles, lectern page navigation. The action is queued and executed on the next game tick. Requires CONTROL_BOT_ACTIONS permission.

async set_container_text(request: soulfire.bot_pb2.BotSetContainerTextRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotSetContainerTextRequest, soulfire.bot_pb2.BotSetContainerTextResponse], /) → soulfire.bot_pb2.BotSetContainerTextResponse[source]

Sets text in a container’s text input field. Supports “item_name” for anvil names and “search” for creative inventory. The action is queued and executed on the next game tick. Requires CONTROL_BOT_ACTIONS permission.

async set_hotbar_slot(request: soulfire.bot_pb2.BotSetHotbarSlotRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotSetHotbarSlotRequest, soulfire.bot_pb2.BotSetHotbarSlotResponse], /) → soulfire.bot_pb2.BotSetHotbarSlotResponse[source]

Changes the selected hotbar slot. Valid slot range: 0-8 (corresponding to slots 1-9 in the UI). The action is queued and executed on the next game tick. Requires CONTROL_BOT_ACTIONS permission.

async set_movement_state(request: soulfire.bot_pb2.BotSetMovementStateRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotSetMovementStateRequest, soulfire.bot_pb2.BotSetMovementStateResponse], /) → soulfire.bot_pb2.BotSetMovementStateResponse[source]

Updates the bot’s movement state (WASD, jump, sneak, sprint). Only specified fields are changed; omitted fields retain their current value. Movement persists until explicitly changed or reset. The action is queued and executed on the next game tick. Requires CONTROL_BOT_ACTIONS permission.

async reset_movement(request: soulfire.bot_pb2.BotResetMovementRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotResetMovementRequest, soulfire.bot_pb2.BotResetMovementResponse], /) → soulfire.bot_pb2.BotResetMovementResponse[source]

Resets all movement to stopped state. Equivalent to releasing all movement keys. The action is queued and executed on the next game tick. Requires CONTROL_BOT_ACTIONS permission.

async set_rotation(request: soulfire.bot_pb2.BotSetRotationRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotSetRotationRequest, soulfire.bot_pb2.BotSetRotationResponse], /) → soulfire.bot_pb2.BotSetRotationResponse[source]

Sets the bot’s view rotation (look direction). Yaw is normalized to -180 to 180, pitch is clamped to -90 to 90. The action is queued and executed on the next game tick. Requires CONTROL_BOT_ACTIONS permission.

async get_dialog(request: soulfire.bot_pb2.BotGetDialogRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotGetDialogRequest, soulfire.bot_pb2.BotGetDialogResponse], /) → soulfire.bot_pb2.BotGetDialogResponse[source]

Returns the currently displayed server dialog (Minecraft 1.21.6+). Dialogs are server-sent UI screens for custom interactions. Returns empty response if no dialog is being shown. Does not require the bot to be online (but dialog will be absent). Requires READ_BOT_INFO permission.

async submit_dialog(request: soulfire.bot_pb2.BotSubmitDialogRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotSubmitDialogRequest, soulfire.bot_pb2.BotSubmitDialogResponse], /) → soulfire.bot_pb2.BotSubmitDialogResponse[source]

Submits a dialog with input values. Used for dialogs containing text fields, checkboxes, dropdowns, or sliders. The dialog is closed after submission. Note: Full dialog response packets are not yet implemented; this clears local state. Requires CONTROL_BOT_ACTIONS permission.

async click_dialog_button(request: soulfire.bot_pb2.BotClickDialogButtonRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotClickDialogButtonRequest, soulfire.bot_pb2.BotClickDialogButtonResponse], /) → soulfire.bot_pb2.BotClickDialogButtonResponse[source]

Clicks a button in the current dialog. Button index depends on dialog type (see BotClickDialogButtonRequest). The dialog is typically closed after the button click. Note: Full dialog button packets are not yet implemented; this clears local state. Requires CONTROL_BOT_ACTIONS permission.

async close_dialog(request: soulfire.bot_pb2.BotCloseDialogRequest, ctx: connectrpc.request.RequestContext[soulfire.bot_pb2.BotCloseDialogRequest, soulfire.bot_pb2.BotCloseDialogResponse], /) → soulfire.bot_pb2.BotCloseDialogResponse[source]

Closes/dismisses the current dialog. Clears the local dialog state. Requires CONTROL_BOT_ACTIONS permission.