Migrate from Mineflayer

SoulFire and Mineflayer solve many of the same automation problems. SoulFire uses a server-managed SDK and does not copy the Mineflayer API. Map each Mineflayer concept to the native SoulFire object model. This model provides durable tasks, reconnect-safe state, fleets, permissions, and typed plugin APIs.

The parity audit tracks all 306 headings in the official Mineflayer API reference. Each concept maps to a native API, language helper, durable task, plugin, or permission-controlled protocol API.

Parity dashboardCopy Anchor Link

The July 28, 2026 audit covers all 306 API headings in the pinned Mineflayer reference.

The machine-readable parity matrix pins the source heading count and digest. CI fails when Mineflayer adds or changes a heading until the audit is reviewed again.

Start with the object modelCopy Anchor Link

BotSession retains entities, blocks, inventory, player-list entries, weather, boss bars, scoreboards, and stream revision metadata. It discards stale entity references when a bot reconnects.

Replace event listenersCopy Anchor Link

Mineflayer listeners run inside the Minecraft client process. SoulFire streams ordered event envelopes over the SDK and can resume after a transient transport failure.

const session = yield* bot.observe();

yield* session.events().pipe(
  Stream.filter((event) => event.event.case === "chat"),
  Stream.runForEach((event) =>
    Effect.logInfo("chat received", {
      message: event.event.value.plainText,
    })
  ),
);

Use session.waitFor(...), session.once(...), or their Python equivalents for arbitrary one-shot waits. bot.chat.waitFor(...) and Python bot.chat.wait_for(...) provide substring, regular-expression, predicate, capture-group, source-filter, and timeout handling for chat. Keep sounds, particles, and chunk events opt-in when the application does not need their higher event volume.

Replace direct actionsCopy Anchor Link

Actions validate reach, world epoch, dimensions, permissions, and control leases on the server. Expected action rejection is a typed failure, not an ambiguous local state change.

Move workflows into tasksCopy Anchor Link

Operations that span ticks belong near the game loop:

const task = yield* bot.tasks.collectBlocks({
  selector: { blockIds: ["minecraft:oak_log"] },
  count: 16,
});

const result = yield* task.result();

Pathfinding, combat, collection, building, farming, fishing, crafting, smelting, brewing, villager trading, auto-eat, auto-armor, auto-totem, and auto-respawn have durable task forms. A task exposes progress, cancellation, ownership, disconnect policy, and a typed result.

Client-side behaviors compose tasks with sequence, parallel, race, retry, timeout, conditional, fallback, and cleanup operators. Use tasks for time-sensitive execution and behaviors for application-level orchestration.

Replace Mineflayer pluginsCopy Anchor Link

A SoulFire plugin runs on the server and declares its public contract. It can publish:

• Unary and server-streaming RPCs through the stable web transport.
• Durable task kinds with typed inputs, progress, and results.
• Plugin event streams.
• Permission descriptors, limits, docs, OpenAPI metadata, and MCP tools.

The SDK discovers installed plugins during the connection handshake. Generate a typed companion module for normal use, or invoke a descriptor reflectively when building generic tooling.

Use the protocol escape hatch sparinglyCopy Anchor Link

bot.protocol exposes negotiated packet schemas plus audited send and watch operations for version-specific work that does not belong in the stable domain model. It requires a separate dangerous permission and enforces packet size and rate limits.

If a packet-level experiment becomes common application logic, move it into a SoulFire plugin and publish a semantic RPC or task contract. That keeps Minecraft version details close to the server and gives SDK callers a stable, typed API.

Migration checklistCopy Anchor Link

• Replace process-local bot construction with an instance and bot handle.
• Replace mutable reads with world snapshots or a synchronized session.
• Replace EventEmitter listeners with resumable streams.
• Replace multi-tick loops with durable tasks.
• Replace runtime plugin injection with typed server plugin capabilities.
• Acquire a control lease when several callers can command the same bot.
• Use raw packets only when neither the core SDK nor a plugin models the operation.
• Test reconnects, cancellation, permission failures, and stale entity references before production rollout.