soulfire.bot_connect.BotServiceSync

class soulfire.bot_connect.BotServiceSync[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)

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.

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.Iterator[soulfire.bot_pb2.WatchBotStatusesResponse][source]

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

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.

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.

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.

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.

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.Iterator[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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.