SoulFire SDK

Start with SDK versions and installation. These guides describe the published 2.10.2 SDKs, with Effect v4 for TypeScript and effect-py for Python.

The SoulFire SDK is the official API for Minecraft automation. Your application controls one bot or a fleet. SoulFire manages connections, reconnects, permissions, tasks, and plugins.

Choose a languageCopy Anchor Link

Build something usefulCopy Anchor Link

Start with a Minecraft server address and username. The SDK can install a local backend and return a ready bot. For an existing backend, use named provisioning or attach to saved bot IDs.

• Reply to chat with a bot.
• Collect blocks with a durable task.
• Follow an entity using a connection safe reference.
• Transfer items through a container.

See all recipes.

Find the right guideCopy Anchor Link

• Observe: events and state, world queries, registries, camera and maps.
• Act: player actions, pathfinding, inventory, durable tasks.
• Scale: automation, fleets, behaviors, server administration.
• Extend: plugins, raw protocol, migration from Mineflayer.

How the SDK is organizedCopy Anchor Link

SoulFire
├── server metadata and negotiated capabilities
├── administrative services and scoped telemetry
├── plugin catalog and reflective RPC
├── createBot / getOrCreateInstance (TypeScript)
├── get_or_create_instance (Python)
└── instance(instanceId)
    ├── fleet lifecycle and status streams
    ├── selectors, work distribution, and task groups
    ├── coordinated automation, memory, roles, and claims
    └── bot(botId)
        ├── session and synchronized state
        ├── world, registry, inventory, recipes, and chat
        ├── camera captures, frame streams, and world maps
        ├── typed player actions and path planning
        ├── advanced native protocol access
        └── durable tasks

An instance separates permissions and settings. Each Minecraft account is a separate bot. Named setup reuses saved resources. bot.connect() owns observation and stops bots that its scope starts. The lower-level start API changes saved requested state until an explicit stop. See bot lifecycle for cleanup and task ownership.

Run the examplesCopy Anchor Link

Guide snippets assume an open connection inside a scoped workflow. In TypeScript, compose operations with yield* inside Effect.gen and run the complete workflow with Effect.runPromise. In Python, compose operations with yield from inside @gen or @fn and run the workflow with run_async.

The scope owns connections, sessions, subscriptions, and acquired resources. Keep their consumers inside the same scope. Stream callbacks return effects so cancellation and typed errors stay within the workflow. The recipes include complete runtime setup.

Actions, streams, and tasksCopy Anchor Link

Use an action for one short operation, such as sending chat or clicking a slot. The sleep action finishes after the server reports that the bot entered a bed. The wake action leaves the current bed. Each result has an action ID and a final state. The final state is completed, cancelled, or failed.

Use a stream to receive updates over time. For example, a stream can report chat, inventory, world, task, or plugin updates.

Use a durable task for work that takes time. The server continues the task if the SDK program disconnects. You can read its progress, stop it, or reconnect to it by ID.

Compatibility and extensionsCopy Anchor Link

Each connection starts with a compatibility test. The SDK compares API versions, features, and required plugin versions.

Plugins can add RPC services and durable task types. An application can use a plugin package or discover the plugin API while it runs.

API referenceCopy Anchor Link

The TypeScript API reference and Python API reference document public classes, methods, types, and generated protocol modules. The server RPC reference covers lower level endpoints.