Your first Python program

This program creates a ready bot from a Minecraft server address and username. The SDK downloads SoulFire and Java when needed and manages setup and cleanup.

Prepare the Minecraft serverCopy Anchor Link

Start a Minecraft server that accepts offline accounts at localhost:25565. Change server in the program if your server uses another address. The default authentication is "offline". For a server that requires a Microsoft account, see account authentication.

Install the SDKCopy Anchor Link

Complete the Python installation. Use that virtual environment for every command on this page. The SDK requires CPython 3.14 or newer and installs the pinned effect-py runtime.

Save the complete programCopy Anchor Link

Create first_bot.py:

import asyncio

from effect_py import EffectGen, Scope, gen, run_async, scoped, sync
from soulfire import SoulFire, SoulFireOperationError


@gen
def program() -> EffectGen[None, SoulFireOperationError, Scope]:
    bot = yield from SoulFire.create_bot(
        server="localhost:25565",
        username="DocsBot_1",
        installation={"version": "2.10.2"},
    )
    yield from bot.chat.send("Hello from SoulFire")
    yield from sync(lambda: print(bot.state.player))


asyncio.run(run_async(scoped(program).or_die()))

server is the Minecraft address. The SDK supplies the local SoulFire API URL and token and creates or finds the instance and account.

Run and check the resultCopy Anchor Link

.venv/bin/python first_bot.py

On Windows, run .venv\Scripts\python first_bot.py. The first run downloads a dedicated backend and Java into .soulfire under the working directory. Later runs reuse those files and the saved account. Expect Hello from SoulFire in Minecraft chat and a player snapshot in the terminal. The scope closes subscriptions and the managed backend when the program finishes.

Use installation={"directory": "...", "version": "2.10.2"} to choose the data directory and backend version. Without a version, managed installation selects the latest release.

Read the codeCopy Anchor Link

SoulFire.create_bot installs a local backend and returns a ready, observed bot. It waits for the initial player snapshot, with a default 30-second deadline. Set ready_timeout in seconds to change that deadline. bot.state contains the latest synchronized state.

@gen defines an Effect workflow. yield from runs its operations. scoped owns the connection, subscriptions, and managed process. sync puts the print operation inside the workflow. run_async runs the complete workflow through the async runtime. or_die() converts remaining typed failures into boundary errors.

Use or_die() at the application boundary after handling expected errors. In a larger application, use effect-py recovery operators or run_async_exit to inspect failures. Constructing an effect alone does not send a request.

Next stepCopy Anchor Link

Use named instances and bots to reuse one backend for several accounts or connect to an existing server. Try replying to chat, or read the runtime guide for layers and streams. Read task ownership before submitting durable work.