soulfire

The SoulFire SDK automates Minecraft bots with lazy Effect operations.

Start with the Python tutorial. Keep bot operations inside a scope and run the complete workflow at its boundary.

Methods decorated with @fn return lazy Effect operations when called. Their source signatures use EffectGen to describe the generator implementation.

Submodules

• soulfire.actions
• soulfire.admin
• soulfire.api_docs_pb2
• soulfire.behaviors
• soulfire.bot
• soulfire.bot_connect
• soulfire.bot_live_connect
• soulfire.bot_live_pb2
• soulfire.bot_pb2
• soulfire.camera
• soulfire.chat_connect
• soulfire.chat_pb2
• soulfire.client
• soulfire.client_connect
• soulfire.client_pb2
• soulfire.command_connect
• soulfire.command_pb2
• soulfire.common_pb2
• soulfire.concurrency
• soulfire.connection
• soulfire.domain_pb2
• soulfire.download_connect
• soulfire.download_pb2
• soulfire.errors
• soulfire.example_plugin
• soulfire.fleet
• soulfire.instance_connect
• soulfire.instance_live_connect
• soulfire.instance_live_pb2
• soulfire.instance_pb2
• soulfire.inventory_connect
• soulfire.inventory_pb2
• soulfire.login_connect
• soulfire.login_pb2
• soulfire.logs_connect
• soulfire.logs_pb2
• soulfire.mc_auth_connect
• soulfire.mc_auth_pb2
• soulfire.metrics_connect
• soulfire.metrics_pb2
• soulfire.pathfinding
• soulfire.pathfinding_connect
• soulfire.pathfinding_pb2
• soulfire.plugin
• soulfire.plugin_api_connect
• soulfire.plugin_api_pb2
• soulfire.plugin_stats_connect
• soulfire.plugin_stats_pb2
• soulfire.plugins
• soulfire.pov_connect
• soulfire.pov_pb2
• soulfire.protocol
• soulfire.protocol_connect
• soulfire.protocol_pb2
• soulfire.proxy_check_connect
• soulfire.proxy_check_pb2
• soulfire.recipe_connect
• soulfire.recipe_pb2
• soulfire.registry_connect
• soulfire.registry_pb2
• soulfire.resources
• soulfire.script_connect
• soulfire.script_pb2
• soulfire.sdk_connect
• soulfire.sdk_pb2
• soulfire.selectors
• soulfire.semantic
• soulfire.server_connect
• soulfire.server_pb2
• soulfire.session
• soulfire.streams
• soulfire.task_connect
• soulfire.task_pb2
• soulfire.tasks
• soulfire.transport
• soulfire.user_connect
• soulfire.user_pb2
• soulfire.world_connect
• soulfire.world_pb2

Attributes

SDK_API_VERSION
SDK_VERSION
SoulFireOperationError
example_plugin
goals
PACKET_DIRECTION_CLIENTBOUND
PACKET_DIRECTION_SERVERBOUND
ChatMatcher

Exceptions

SoulFireActionError	A bot action returned an unsuccessful result.
SoulFireBehaviorError	Base error for bot behavior operations.
SoulFireBehaviorTimeoutError	A bot behavior exceeded its allowed duration.
SoulFireCapabilityError	The server does not provide a required SDK capability.
SoulFireCompatibilityError	The server and SDK cannot safely communicate.
SoulFireInstallError	The SDK could not install or start a managed SoulFire server.
SoulFireRpcError	An RPC request failed with server status and retry context.
SoulFireStateError	An SDK operation cannot proceed in the current state.
SoulFireTimeoutError	An SDK operation exceeded its allowed duration.
SoulFireValidationError	An SDK operation received an invalid value or argument type.
FleetTaskGroupError	A fleet task failed. The report contains each task's outcome.
SoulFirePluginCompatibilityError	An installed plugin is incompatible with the SDK requirements.
SoulFirePluginDescriptorError	The SDK could not use a plugin's API descriptor.
SoulFirePluginNotFoundError	A required plugin is not installed on the server.
SoulFireContainerClosedError	An inventory operation attempted to use a closed container.
SoulFireTaskError	A bot task ended with a failure or an unsuccessful status.

Classes

LocalSoulFireServer
SoulFireAdmin	Async high-level access to SoulFire's administrative control plane.
AttackNearest
AutoArmor
AutoEat
AutoRespawn
AutoTotem
BotBehavior
Build
BuildPlacement
CollectBlocks
FollowEntity
FunctionBehavior
SoulFireBot	One bot's lifecycle, actions, live state, and server tasks.
SoulFireBotControlLease	Exclusive action control with explicit renewal and scoped release.
BotChunkEvent	Abstract base class for protocol messages.
BotEvent	Abstract base class for protocol messages.
BotEventFilter	Abstract base class for protocol messages.
BotResourcePackEvent	Abstract base class for protocol messages.
BotTitleEvent	Abstract base class for protocol messages.
ChunkEventKind	int([x]) -> integer
CreativeItemStack	Abstract base class for protocol messages.
ResourcePackEventKind	int([x]) -> integer
ResourcePackResponse	int([x]) -> integer
TitleEventKind	int([x]) -> integer
WaitForChunksResponse	Abstract base class for protocol messages.
CameraRenderOptions
SoulFireCamera	Async camera, frame-stream, and map-view access for one bot.
WorldMapOptions
ManagedInstallOptions	Options for a local SoulFire server managed by the SDK.
SoulFire	A scoped client for a SoulFire server and its bot instances.
SoulFireInstance	An instance handle that groups bot accounts and configuration.
SoulFireService	Base class for protocol classes.
BlockPosition	Abstract base class for protocol messages.
WorldPosition	Abstract base class for protocol messages.
CapabilitySet
RequiredPlugin
ServerMetadata
BlockSnapshot	Abstract base class for protocol messages.
EntityReference	Abstract base class for protocol messages.
EntitySnapshot	Abstract base class for protocol messages.
ItemStackSnapshot	Abstract base class for protocol messages.
PlayerSnapshot	Abstract base class for protocol messages.
TextComponent	Abstract base class for protocol messages.
Vec3	Abstract base class for protocol messages.
RpcFailureContext
ExamplePluginClient
FleetAssignment
FleetBot
FleetMetadataSelector
FleetOperationOutcome
FleetOperationReport
FleetPoint
FleetRadius
FleetSelector
FleetTaskMember
FleetTaskOutcome
FleetTaskReport
FleetTaskStartFailure
FleetTaskStartOptions
FleetTaskStreamEvent
SoulFireFleet
SoulFireFleetTaskGroup
InstanceEvent	Abstract base class for protocol messages.
InstanceEventFilter	Abstract base class for protocol messages.
BlockTarget
EntityTarget
Goals
SoulFirePathfinder
WorldTarget
PluginPermissionDefault	int([x]) -> integer
PluginPermissionDescriptor	Abstract base class for protocol messages.
PluginPermissionRisk	int([x]) -> integer
PluginPermissionScope	int([x]) -> integer
PluginCatalog
ReflectiveMessage
ReflectivePlugin
ReflectivePluginEvent
SoulFirePluginModule	Base class for protocol classes.
TypedPluginEvent
SoulFireProtocol	Advanced access to SoulFire's native Minecraft packet codec.
BotProtocolInfo	Abstract base class for protocol messages.
PacketDirection	int([x]) -> integer
PacketSchema	Abstract base class for protocol messages.
RawPacketEvent	Abstract base class for protocol messages.
ChatMatch
InventoryRankingOptions	Filters and preferences for inventory item recommendations.
SoulFireChat
SoulFireContainer
SoulFireInventory
SoulFireRecipes
SoulFireRegistry
SoulFireWorld
BotBossBarState
BotEnvironmentState
BotScoreboardObjective
BotScoreboardScore
BotScoreboardState
BotScoreboardTeam
BotSession
BotSessionOptions
BotSessionState
Stream	A lazy stream. Each subscription acquires its own scoped cursor.
ContainerTransferSpec
LoadoutRequirementSpec
SchematicBlock
SoulFireTask	A handle for a server task with a typed result.
SoulFireTasks	Start and observe durable jobs for one bot.
UserPluginPermissionGrant	Abstract base class for protocol messages.
BlockSelector	Abstract base class for protocol messages.
BoxRegion	Abstract base class for protocol messages.
CanSeeBlockResponse	Abstract base class for protocol messages.
EntitySelector	Abstract base class for protocol messages.
EstimateDigTimeResponse	Abstract base class for protocol messages.
EstimateExplosionDamageResponse	Abstract base class for protocol messages.
GetWorldBlockResponse	Abstract base class for protocol messages.
GetWorldEntityResponse	Abstract base class for protocol messages.
QueryBlocksResponse	Abstract base class for protocol messages.
QueryEntitiesResponse	Abstract base class for protocol messages.
QueryRegion	Abstract base class for protocol messages.
QuerySort	int([x]) -> integer
RaycastResponse	Abstract base class for protocol messages.
SphereRegion	Abstract base class for protocol messages.

Functions

cleanup(→ BotBehavior[A2, E2, R2])
conditional(→ BotBehavior[A2 | None, E2 | EP, R2 | RP])
define_behavior(→ FunctionBehavior[A2, E2, R2])
fallback(→ BotBehavior[A2, E2, R2])
parallel(→ BotBehavior[tuple[object, ...], E2, R2])
race(→ BotBehavior[A2, E2, R2])
repeat(→ BotBehavior[tuple[A2, ...], ...)
retry(→ BotBehavior[A2, ...)
run_behaviors(→ effect_py.EffectGen[None, E2, R2])
scoped_lease(→ BotBehavior[A2, ...)
sequence(→ BotBehavior[tuple[object, ...], E2, R2])
timeout(→ BotBehavior[A2, ...)
until(→ BotBehavior[A2, ...)
decode_camera_image(→ bytes)	Decode a camera image payload into its original bytes.
connection_layer(, required_plugins, ...)
item_selector(→ soulfire.inventory_pb2.ItemSelector)
match_chat(→ ChatMatch | None)
empty_bot_session_state(→ BotSessionState)
reduce_bot_session_state(→ BotSessionState)
is_terminal_task_status(→ bool)

Package Contents

soulfire.cleanup[A2, E2, R2](behavior: BotBehavior[A2, E2, R2], finalizer: BotBehavior[object, object]) → BotBehavior[A2, E2, R2]

soulfire.conditional[A2, E2, R2, EP, RP](predicate: collections.abc.Callable[[soulfire.bot.SoulFireBot], bool | effect_py.Effect[bool, EP, RP]], when_true: BotBehavior[A2, E2, R2], when_false: BotBehavior[A2, E2, R2] | None = None) → BotBehavior[A2 | None, E2 | EP, R2 | RP]

soulfire.define_behavior[A2, E2, R2](function: collections.abc.Callable[[soulfire.bot.SoulFireBot], effect_py.Effect[A2, E2, R2]]) → FunctionBehavior[A2, E2, R2]

soulfire.fallback[A2, E2, R2](primary: BotBehavior[A2, E2, R2], *alternatives: BotBehavior[A2, E2, R2]) → BotBehavior[A2, E2, R2]

soulfire.parallel[E2, R2](*behaviors: BotBehavior[object, E2, R2]) → BotBehavior[tuple[object, ...], E2, R2]

soulfire.race[A2, E2, R2](first: BotBehavior[A2, E2, R2], *others: BotBehavior[A2, E2, R2]) → BotBehavior[A2, E2, R2]

soulfire.repeat[A2, E2, R2](behavior: BotBehavior[A2, E2, R2], *, times: int) → BotBehavior[tuple[A2, ...], E2 | soulfire.errors.SoulFireOperationError, R2]

soulfire.retry[A2, E2, R2](behavior: BotBehavior[A2, E2, R2], *, attempts: int = 3, delay: float = 0, backoff: float = 1, maximum_delay: float | None = None, while_: collections.abc.Callable[[E2], bool] = lambda _: ...) → BotBehavior[A2, E2 | soulfire.errors.SoulFireOperationError, R2]

soulfire.run_behaviors[E2, R2](bot: soulfire.bot.SoulFireBot, behaviors: collections.abc.Iterable[BotBehavior[object, E2, R2]]) → effect_py.Effect[None, E2, R2]

soulfire.scoped_lease[A2, E2, R2](behavior: BotBehavior[A2, E2, R2], *, ttl_seconds: int = 30) → BotBehavior[A2, E2 | soulfire.errors.SoulFireOperationError, R2]

soulfire.sequence[E2, R2](*behaviors: BotBehavior[object, E2, R2]) → BotBehavior[tuple[object, ...], E2, R2]

soulfire.timeout[A2, E2, R2](behavior: BotBehavior[A2, E2, R2], seconds: float) → BotBehavior[A2, E2 | soulfire.errors.SoulFireOperationError | SoulFireBehaviorTimeoutError, R2]

soulfire.until[A2, E2, R2, EP, RP](behavior: BotBehavior[A2, E2, R2], predicate: collections.abc.Callable[[A2], bool | effect_py.Effect[bool, EP, RP]], *, maximum_iterations: int | None = None) → BotBehavior[A2, E2 | EP | soulfire.errors.SoulFireOperationError | SoulFireBehaviorError, R2 | RP]

soulfire.decode_camera_image(image: soulfire.bot_pb2.BotRenderPovResponse) → bytes

Decode a camera image payload into its original bytes.

soulfire.connection_layer(base_url: str, *, token: soulfire._auth.TokenProvider | None = None, timeout_ms: int | None = None, required_capabilities: collections.abc.Iterable[str] = (), required_plugins: collections.abc.Iterable[soulfire.connection.RequiredPlugin] = ()) → effect_py.layer.Layer[SoulFireService, soulfire.errors.SoulFireOperationError]

soulfire.SDK_API_VERSION: Final

soulfire.SDK_VERSION: Final = '2.10.3'

type soulfire.SoulFireOperationError = SoulFireRpcError | SoulFireValidationError | SoulFireStateError | SoulFireInstallError | SoulFireTimeoutError | SoulFireActionError | SoulFireTaskError | SoulFireCompatibilityError | SoulFireCapabilityError | SoulFirePluginNotFoundError | SoulFirePluginCompatibilityError | SoulFirePluginDescriptorError | SoulFireContainerClosedError

soulfire.example_plugin

soulfire.goals

soulfire.PACKET_DIRECTION_CLIENTBOUND: PacketDirection

soulfire.PACKET_DIRECTION_SERVERBOUND: PacketDirection

soulfire.item_selector(value: str | soulfire.inventory_pb2.ItemSelector) → soulfire.inventory_pb2.ItemSelector

type soulfire.ChatMatcher = str | re.Pattern[str] | Callable[[BotChatEvent], bool]

soulfire.match_chat(event: soulfire.bot_live_pb2.BotChatEvent, matcher: ChatMatcher) → ChatMatch | None

soulfire.empty_bot_session_state() → BotSessionState

soulfire.reduce_bot_session_state(state: BotSessionState, event: soulfire.bot_live_pb2.BotEvent) → BotSessionState

soulfire.is_terminal_task_status(status: soulfire.task_pb2.BotTaskStatus) → bool