soulfire.bot_live_connect.BotLiveServiceClient

class soulfire.bot_live_connect.BotLiveServiceClient(address: str, *, codec: connectrpc.codec.Codec | None = _PROTO_BINARY_CODEC, protocol: connectrpc.protocol.ProtocolType = ProtocolType.CONNECT, accept_compression: collections.abc.Iterable[connectrpc.compression.Compression] | None = None, send_compression: connectrpc.compression.Compression | None = _GZIP_COMPRESSION, timeout_ms: int | None = None, read_max_bytes: int | None = None, interceptors: collections.abc.Iterable[connectrpc.interceptor.Interceptor] = (), http_client: pyqwest.Client | None = None)[source]

Bases: connectrpc.client.ConnectClient

Live bot remote-control service. See file header for scope and design notes.

Permissions: - READ_BOT_INFO: required for WatchBotEvents, GetBlock, FindBlocks,

ListNearbyEntities.

  • CONTROL_BOT_ACTIONS: required for chat, interactions, pathfinding, and

    exclusive control leases.

Error handling mirrors BotService: - NOT_FOUND: instance or bot does not exist. - FAILED_PRECONDITION: bot is not online, target not loaded, or the

requested action is not currently valid.

  • OUT_OF_RANGE: target is outside the bot’s reach / observation radius.

  • INTERNAL: unexpected server errors.

watch_bot_events(request: soulfire.bot_live_pb2.WatchBotEventsRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → collections.abc.AsyncIterator[soulfire.bot_live_pb2.BotEvent][source]

Subscribes to a single multiplexed event stream for one bot. The first message is always the current BotStatus. The stream remains open while the bot is stopped and follows the configured bot across reconnects. Live snapshots and filtered events begin whenever a connection becomes ready.

async send_chat(request: soulfire.bot_live_pb2.SendChatRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.SendChatResponse[source]

Sends a chat message (or slash command) from the bot to the connected Minecraft server. Messages prefixed with “/” are routed as commands.

async get_block(request: soulfire.bot_live_pb2.GetBlockRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.GetBlockResponse[source]

Returns the block at a world position, if the chunk is loaded.

async find_blocks(request: soulfire.bot_live_pb2.FindBlocksRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.FindBlocksResponse[source]

Finds blocks of the given ids within a radius of the bot. Results are sorted by ascending distance.

async list_nearby_entities(request: soulfire.bot_live_pb2.ListNearbyEntitiesRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.ListNearbyEntitiesResponse[source]

Lists entities within a radius of the bot, optionally filtered by type.

async dig_block(request: soulfire.bot_live_pb2.DigBlockRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.DigBlockResponse[source]

Starts (or stops, when cancel is set) breaking a block at a specific position. Unlike MouseClick, the target is explicit, with no raytrace from the current look direction is performed.

async place_block(request: soulfire.bot_live_pb2.PlaceBlockRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.PlaceBlockResponse[source]

Places the currently held item as a block, against a specific face of a specific block.

async interact_block(request: soulfire.bot_live_pb2.InteractBlockRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.InteractBlockResponse[source]

Activates a specific block face without assigning placement semantics to the operation. This covers doors, buttons, beds, redstone controls, and modded interactive blocks.

async use_item(request: soulfire.bot_live_pb2.UseItemRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.UseItemResponse[source]

Uses the item in the specified hand (eat, drink, throw, draw bow, etc.).

async release_item(request: soulfire.bot_live_pb2.ReleaseItemRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.ReleaseItemResponse[source]

Releases an item that is currently being used, such as firing a drawn bow or stopping eating.

async attack_entity(request: soulfire.bot_live_pb2.AttackEntityRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.AttackEntityResponse[source]

Attacks a specific entity by network id.

async interact_entity(request: soulfire.bot_live_pb2.InteractEntityRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.InteractEntityResponse[source]

Right-clicks / interacts with a specific entity by network id. Used for trading with villagers, mounting mobs, etc.

async swing_arm(request: soulfire.bot_live_pb2.SwingArmRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.SwingArmResponse[source]

Swings the specified arm without a target (visual animation only).

async respawn(request: soulfire.bot_live_pb2.RespawnRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.RespawnResponse[source]

Respawns a dead bot or dismisses the End credits to finish respawning.

async sleep(request: soulfire.bot_live_pb2.SleepRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.SleepResponse[source]

Uses a reachable bed and completes only after the server confirms that the bot entered the sleeping state.

async wake(request: soulfire.bot_live_pb2.WakeRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.WakeResponse[source]

Leaves the current bed.

async mount_entity(request: soulfire.bot_live_pb2.MountEntityRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.MountEntityResponse[source]
async dismount(request: soulfire.bot_live_pb2.DismountRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.DismountResponse[source]
async set_vehicle_control(request: soulfire.bot_live_pb2.SetVehicleControlRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.SetVehicleControlResponse[source]
async update_sign(request: soulfire.bot_live_pb2.UpdateSignRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.UpdateSignResponse[source]
async write_book(request: soulfire.bot_live_pb2.WriteBookRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.WriteBookResponse[source]
async respond_resource_pack(request: soulfire.bot_live_pb2.RespondResourcePackRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.RespondResourcePackResponse[source]
async set_flying(request: soulfire.bot_live_pb2.SetFlyingRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.SetFlyingResponse[source]
async start_elytra_flight(request: soulfire.bot_live_pb2.StartElytraFlightRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.StartElytraFlightResponse[source]

Requests survival-mode elytra flight. Minecraft validates that the bot is falling and has usable elytra equipment.

async set_creative_slot(request: soulfire.bot_live_pb2.SetCreativeSlotRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.SetCreativeSlotResponse[source]
async wait_for_chunks(request: soulfire.bot_live_pb2.WaitForChunksRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.WaitForChunksResponse[source]

Waits until every chunk in a square radius around the bot is loaded.

go_to(request: soulfire.bot_live_pb2.GoToRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → collections.abc.AsyncIterator[soulfire.bot_live_pb2.PathfindProgress][source]

Requests the bot to pathfind to a goal. Returns a stream of progress events terminating with COMPLETED, FAILED, or CANCELLED. A new GoTo for the same bot supersedes any in-progress pathfinding; the previous stream is closed with CANCELLED.

async stop_pathfinding(request: soulfire.bot_live_pb2.StopPathfindingRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.StopPathfindingResponse[source]

Cancels any in-progress pathfinding session for this bot.

async acquire_bot_control(request: soulfire.bot_live_pb2.AcquireBotControlRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.AcquireBotControlResponse[source]

Acquires exclusive action control for a bot. While the lease is active, action calls must include its token in the X-SoulFire-Control-Token request header.

async renew_bot_control(request: soulfire.bot_live_pb2.RenewBotControlRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.RenewBotControlResponse[source]
async release_bot_control(request: soulfire.bot_live_pb2.ReleaseBotControlRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.bot_live_pb2.ReleaseBotControlResponse[source]