Pathfinding

SoulFire plans and runs paths on the server near the Minecraft game loop. The SDK provides typed goals, planning options, durable task handles, and progress streams.

Build a goalCopy Anchor Link

The goal helpers cover exact blocks, nearby world positions, moving entities, XZ columns, Y levels, block breaking, block placement, retreat, and first-completed composites.

const goal = goals.any([
  goals.near(
    {
      dimension: "minecraft:overworld",
      x: 120,
      y: 68,
      z: -40,
    },
    2,
  ),
  goals.awayFromEntity(hostile.reference, 24),
]);

Add the target's connection epoch to entity goals. After reconnect, SoulFire rejects a stale reference instead of following an entity that reused the network ID.

Preview a pathCopy Anchor Link

Planning does not move the bot and requires only read access:

const plan = yield* bot.pathfinder.plan(goal, {
  path: {
    allowMining: false,
    allowPlacing: true,
    searchTimeoutSeconds: 10,
    placeBlockPenalty: 12,
  },
  includeDescriptions: true,
});

plan = await bot.pathfinder.plan(
    goal,
    options=PathfindOptions(
        allow_mining=False,
        allow_placing=True,
        search_timeout_seconds=10,
        place_block_penalty=12,
    ),
    include_descriptions=True,
)

The plan reports whether the route is complete, partial, unreachable, expired, or cancelled. It includes ordered movement steps, blocks to break, blocks to place, the maximum execution budget, and an explanation for partial plans.

Use preview for user confirmation, cost estimates, build material checks, and debug visualizations. The world can change after planning, so execution still replans when required.

Execute a durable pathCopy Anchor Link

goTo or go_to returns a task handle immediately. run streams the task until it reaches a terminal state.

const task = yield* bot.pathfinder.goTo(goal, {
  path: {
    allowMining: true,
    allowPlacing: true,
    timeoutSeconds: 120,
  },
  idempotencyKey: crypto.randomUUID(),
});

const result = yield* task.result();

The task retains progress, ownership, priority, resource conflicts, deadline, reconnect policy, and cancellation state. It can keep running when the SDK process disconnects if its selected policy allows that.

Follow a moving entityCopy Anchor Link

const task = yield* bot.pathfinder.follow(hostile.reference, 3, {
  targetUnavailableTimeoutSeconds: 10,
});

The server resolves the entity on each replan. Following fails clearly when the connection epoch changes or the target remains unavailable beyond the configured grace period.

Use the task APIs for cancellation, disconnect policy, resource arbitration, and multi-bot coordination.