World tasks

Use world tasks when movement and block changes need to continue beside the game loop.

Excavate a cuboidCopy Anchor Link

Use excavate to clear every diggable block between two inclusive corners. SoulFire selects the nearest block and plans each route near the game loop. The pathfinder selects tools and keeps mining inside the requested cuboid.

const task = yield* bot.tasks.excavate(
  { x: 10, y: 60, z: 10, dimension: "minecraft:overworld" },
  { x: 17, y: 64, z: 17, dimension: "minecraft:overworld" },
  {
    maximumBlocks: 128,
    path: { allowPlacing: true },
  },
);

const result = yield* task.result();

The server rejects cuboids larger than 32,768 blocks. It also rejects areas with unloaded chunks. Use maximumBlocks or maximum_blocks to limit the number of blocks in one task. The result reports whether SoulFire cleared the area, reached the limit, or found no reachable blocks. It also lists skipped and unreachable positions. If you stop or pause the task, SoulFire releases all bot controls that the task used.

Build an inline schematicCopy Anchor Link

build accepts a blueprint that contains block positions relative to an origin. SoulFire rotates or mirrors the blueprint on the server. It places blocks from the bottom up and selects the required materials.

const task = yield* bot.tasks.build(
  origin,
  [
    {
      offset: { x: 0, y: 0, z: 0 },
      blockId: "minecraft:oak_stairs",
      properties: { facing: "north", half: "bottom" },
    },
    {
      offset: { x: 1, y: 0, z: 0 },
      blockId: "minecraft:oak_planks",
    },
  ],
  {
    rotation: BuildRotation.CLOCKWISE_90,
    mirror: BuildMirror.X,
    substitutions: {
      "minecraft:oak_planks": ["minecraft:spruce_planks"],
    },
    path: { allowPlacing: true },
    breakIncorrectBlocks: true,
  },
);

const result = yield* task.result();

Block positions and directions rotate or mirror together. SoulFire uses the first available material from the substitution list. It does not replace a block that already has the correct state. The result gives an outcome for every requested block.

For a coordinated build, start the same blueprint on each bot with the same partitionCount or partition_count and a distinct zero-based partition index. SoulFire applies transforms and ordering before partitioning, which makes every bot agree on ownership without a client-side coordinator. Pathfinding can place navigation scaffolds when allowPlacing or allow_placing is enabled. Task suspension preserves its current placement, and cancellation releases every claimed control resource.

Explore a coordinated frontierCopy Anchor Link

The exploration task divides a circular area into pathfinding waypoints and claims each waypoint before moving. Bots in the same instance that use the same purpose avoid frontier cells already claimed by another bot:

const scouting = yield* bot.tasks.explore({
  origin: basePosition,
  radius: 512,
  waypointSpacing: 64,
  maximumWaypoints: 8,
  returnToOrigin: true,
  purpose: "village-scouting",
});

const result = yield* scouting.result();

Omit origin to center the frontier on the bot's position when the task starts. waypointSpacing or waypoint_spacing controls the distance between frontier cells. A smaller spacing observes the area more densely but requires more pathfinding work. The purpose is a coordination namespace, so use the same value for bots sharing a survey and different values for independent surveys.

explore defaults to one waypoint. Set a finite maximumWaypoints or maximum_waypoints for bounded work. runExplore and run_explore visit every claimable cell in the finite frontier unless cancelled. The optional return policy walks back to the origin after exploration. Results report visited waypoints, failed routes, approximate horizontal distance, and the final position.

Manage task handles and reconnects.