soulfire.client.SoulFire¶

class soulfire.client.SoulFire(base_url: str, *, token: soulfire._auth.TokenProvider | None = None, timeout_ms: int | None = None, interceptors: collections.abc.Iterable[ClientInterceptor] = (), required_capabilities: collections.abc.Iterable[str] = (), required_plugins: collections.abc.Iterable[soulfire.connection.RequiredPlugin] = ())[source]¶

A scoped client for a SoulFire server and its bot instances.

Use connect() for an existing server, install() for a managed local server, or create_bot() for a ready bot in one operation. Direct construction creates RPC clients without a handshake or scope cleanup.

SDK operations return lazy Effect values. Compose them with yield from inside an Effect workflow, then run the workflow with run_async. Keep all client and bot work inside scoped. The scope closes transports and any local server that this client manages.

See also

Python tutorial.

bot_service¶

bot_live¶

bot_tasks¶

pathfinder_service¶

chat_service¶

inventory_service¶

recipe_service¶

registry_service¶

world_service¶

protocol_service¶

client_service¶

command_service¶

download_service¶

logs_service¶

metrics_service¶

plugin_stats_service¶

script_service¶

server_service¶

user_service¶

instance_service¶

instance_live¶

login_service¶

mc_auth_service¶

classmethod connect(base_url: str, *, token: soulfire._auth.TokenProvider | None = None, timeout_ms: int | None = None, interceptors: collections.abc.Iterable[ClientInterceptor] = (), required_capabilities: collections.abc.Iterable[str] = (), required_plugins: collections.abc.Iterable[soulfire.connection.RequiredPlugin] = ()) → effect_py.Effect[SoulFire, soulfire.errors.SoulFireOperationError, effect_py.Scope][source]¶

Connect to an existing server and check SDK compatibility.

The handshake checks the API version, required capabilities, and required plugin versions. The scope closes the client’s transports on exit. It does not stop the remote SoulFire server.

Parameters:

base_url – SoulFire gRPC-Web URL, including http:// or https://. This is separate from the Minecraft server address.
token – Bearer token or token provider. Omit it for a public server.
timeout_ms – Default RPC timeout in milliseconds. None uses the transport default. This is separate from bot readiness timeouts.
interceptors – Additional ConnectRPC interceptors.
required_capabilities – Capability identifiers the server must support.
required_plugins – Plugin identifiers and version constraints to check.

Returns:

An Effect that produces a client after the handshake. Requires Scope.

Notes

Transport, authentication, and compatibility errors use the Effect error channel. Use unauthenticated() when login must precede the handshake.

classmethod unauthenticated(base_url: str, *, token: soulfire._auth.TokenProvider | None = None, timeout_ms: int | None = None, interceptors: collections.abc.Iterable[ClientInterceptor] = (), required_capabilities: collections.abc.Iterable[str] = (), required_plugins: collections.abc.Iterable[soulfire.connection.RequiredPlugin] = ()) → effect_py.Effect[SoulFire, soulfire.errors.SoulFireOperationError, effect_py.Scope][source]¶

Create a scoped client without an SDK handshake.

Use this client for the login flow on a server that requires authentication. After login, negotiate compatibility before reading server metadata. The scope closes all transports. This method accepts the same connection options as connect().

Returns:: An Effect that produces a client. Requires Scope.

classmethod install(*, directory: str | os.PathLike[str] | None = None, version: str | None = None, java_args: collections.abc.Iterable[str] = (), port: int | None = None, startup_timeout: float = 120.0, on_log: collections.abc.Callable[[str], None] | None = None, timeout_ms: int | None = None, interceptors: collections.abc.Iterable[ClientInterceptor] = ()) → effect_py.Effect[SoulFire, soulfire.errors.SoulFireOperationError, effect_py.Scope][source]¶

Download and start a local SoulFire server owned by the scope.

The installer downloads Java and SoulFire when needed, starts the process, then connects with its local token and completes the SDK handshake. The scope closes the client and stops the managed process on exit. Downloaded files and server data remain available for later runs.

Parameters:

directory – Installation and data directory. Defaults to .soulfire in the current working directory.
version – Release tag to install. None selects the latest release.
java_args – Extra JVM arguments before the SoulFire JAR.
port – Local gRPC-Web port. None selects an available port.
startup_timeout – Maximum startup wait in seconds. Defaults to 120.
on_log – Callback for server log lines.
timeout_ms – Default RPC timeout in milliseconds after startup.
interceptors – Additional ConnectRPC interceptors.

Returns:

An Effect that produces a connected client. Requires Scope.

Notes

Installation failures use SoulFireInstallError in the Effect error channel. Startup timeout and RPC timeout control different stages.

set_token(token: soulfire._auth.TokenProvider | None) → None[source]¶

Replace the bearer token or token provider for subsequent RPC calls.

This synchronous change does not perform a handshake or restart open streams.

classmethod create_bot(*, server: str, username: str, auth: Literal['offline', 'microsoft'] = 'offline', instance_name: str | None = None, name: str | None = None, ready_timeout: float = 30.0, on_device_code: collections.abc.Callable[[soulfire.mc_auth_pb2.DeviceCode], effect_py.Effect[None, soulfire.errors.SoulFireOperationError]] | None = None, installation: ManagedInstallOptions | None = None) → effect_py.Effect[soulfire.bot.SoulFireBot, soulfire.errors.SoulFireOperationError, effect_py.Scope][source]¶

Install SoulFire and create or reuse a ready bot by name.

The instance name defaults to the Minecraft server address. The bot name and offline username default to username. Repeated calls reuse named resources. Conflicting account or server configuration fails explicitly. The scope owns the managed process, observation, and bot startup.

Parameters:

server – Minecraft address, such as localhost:25565.
username – Minecraft username for a new offline account.
auth – "offline" by default. "microsoft" enables device-code login when no matching account exists.
instance_name – Stable instance name. Defaults to the trimmed address.
name – Stable bot name within the instance. Defaults to username.
ready_timeout – Positive, finite readiness deadline in seconds. Defaults to 30. The bot must receive an initial player snapshot.
on_device_code – Effect callback for the first Microsoft login code. Without a callback, the SDK prints the sign-in URL and code.
installation – Local server options accepted by install().

Returns:

An Effect that produces a ready, observed bot. Requires Scope.