SoulFire SDK
Build typed, event-driven Minecraft automation with the official TypeScript and Python SDKs.
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.
The TypeScript SDK supports both Effect and Promises. The Python SDK requires CPython 3.14. It supports asynchronous and synchronous code.
Choose a language
TypeScript
Use the Effect API or the Promise API.
Python
Use AsyncSoulFire for asynchronous programs.
Use SoulFire for synchronous scripts.
Durable tasks
Run pathfinding, combat, following, eating, and respawning beside the Minecraft game loop.
Live events and state
Watch Minecraft events or keep a local copy of the current world state.
Player actions
Mount and drive vehicles, edit signs and books, answer resource packs, toggle flight, and manage creative slots.
Coordinated automation
Give a group of bots one goal and share progress between them.
Bot fleets
Select bots, divide work between them, and monitor their tasks.
Cameras and world maps
Capture camera images, stream bot views, and collect data for maps.
Server administration
Manage settings, users, logs, metrics, scripts, commands, downloads, plugin metrics, and audit history.
Combine behaviors
Run tasks in order or in parallel. Add retries, timeouts, fallback tasks, and cleanup.
Plugin APIs
Call plugin APIs, read plugin event streams, or connect to an unknown plugin.
Raw protocol access
View packet types, watch network traffic, and send native packets.
How the SDK is organized
SoulFire
├── server metadata and negotiated capabilities
├── administrative services and scoped telemetry
├── plugin catalog and reflective RPC
└── 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 tasksAn instance separates permissions and settings. Each Minecraft account is a separate bot. SoulFire saves the requested bot state. It can reconnect the bot after the SDK program stops.
Actions, streams, and tasks
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 extensions
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.
Next steps
- Start with TypeScript
- Start with Python
- Run and supervise durable tasks
- Observe live events and synchronized state
- Control vehicles and player actions
- Coordinate persistent automation
- Select and orchestrate fleets
- Capture cameras and world maps
- Administer a SoulFire server
- Compose application workflows
- Call plugin-defined APIs
- Use raw protocol access
- Read the generated API reference
How is this page?
Last updated on