Inventory tasks

Inventory tasks report progress and keep bot control while the server performs each operation.

Craft, smelt, and brewCopy Anchor Link

Recipe discovery and production use the same bot-scoped API. list returns the recipes known to the bot. craft, smelt, and brew create durable tasks that own inventory, container, movement, and hand resources while they run.

const task = yield* bot.recipes.brew(
  { fingerprint: waterPotionFingerprint },
  { itemIds: ["minecraft:nether_wart"] },
  3,
  {
    expectedResult: { fingerprint: awkwardPotionFingerprint },
    station: brewingStandPosition,
  },
);

const result = yield* task.result();

Craft counts are recipe operations. A recipe that produces four items per operation still reports one completed craft. Smelt and brew counts are input items. Brewing groups compatible bottles into batches of three, so one ingredient can produce up to three outputs. Use an item fingerprint when the potion's data components matter, and use expectedResult or expected_result to reject a mix whose predicted output changed. Recipes that fit the player inventory grid need no station. Production tasks accept an explicit station position and navigate to it. A station is optional when the compatible menu is already open.

Trade with a villagerCopy Anchor Link

Open the villager menu with bot.interactEntity before inspecting or executing trades. SoulFire reads the live merchant offers, including adjusted costs, uses, stock, experience, demand, and price data.

const offers = yield* bot.recipes.listVillagerTrades();
const offer = offers.offers[0]!;

const task = yield* bot.recipes.villagerTrade(offer.offerIndex, 3, {
  expectedResult: { itemIds: [offer.result!.itemId] },
});
const result = yield* task.result();

expectedResult and expected_result protect against a stale offer index. If the merchant changes the offer, the task stops. It runs one trade at a time for an exact count. It also stops when the inventory cannot hold the output.

Stash and withdraw suppliesCopy Anchor Link

The storage tasks walk to a block container, open it, and apply a semantic transfer batch. Applications describe items and counts instead of scripting menu slots:

const supplies = yield* bot.tasks.withdraw(
  storageChest,
  [
    {
      selector: { itemIds: ["minecraft:bread"] },
      count: 16,
    },
    {
      selector: { tags: ["minecraft:coals"] },
      count: 8,
      allowPartial: true,
    },
  ],
);

const result = yield* supplies.result();

Use stash to move items from the player inventory into the container and withdraw for the opposite direction. Selectors support IDs, tags, fingerprints, names, enchantments, stack counts, and remaining durability. Each exact operation must be fully satisfiable. SoulFire preflights the whole batch before sending any menu click, so a later exact operation cannot leave earlier operations applied. Set allowPartial or allow_partial on an operation when best-effort movement is intentional.

The task closes its menu by default and always closes it after failure or cancellation. Results preserve every requested selector and count, report the actual count moved per operation, and identify a partially satisfied batch. The lower-level container handle remains useful when an application already stands beside an open menu and needs interactive transfers.

Maintain a loadoutCopy Anchor Link

Loadout maintenance turns a chest or other block container into a semantic supply source and overflow destination. A requirement has a minimum that triggers restocking, a target to restore, and an optional maximum that triggers an excess deposit.

const loadout = yield* bot.tasks.maintainLoadout(
  storageChest,
  [
    {
      selector: { itemIds: ["minecraft:bread"] },
      minimumCount: 8,
      targetCount: 16,
      maximumCount: 24,
    },
    {
      selector: { tags: ["minecraft:arrows"] },
      minimumCount: 32,
      targetCount: 64,
    },
  ],
  {
    checkIntervalTicks: 100,
    closeContainer: true,
  },
);

loadout = yield from bot.tasks.maintain_loadout(
    storage_chest,
    [
        LoadoutRequirementSpec(
            ItemSelector(item_ids=["minecraft:bread"]),
            minimum_count=8,
            target_count=16,
            maximum_count=24,
        ),
        LoadoutRequirementSpec(
            ItemSelector(tags=["minecraft:arrows"]),
            minimum_count=32,
            target_count=64,
        ),
    ],
    check_interval_ticks=100,
    close_container=True,
)

The unbounded form keeps monitoring until cancellation. Use balanceLoadout or balance_loadout for a one-shot rebalance, or set a finite rebalance limit. SoulFire plans each transfer batch before it moves items. A temporarily empty chest returns a typed container-exhausted result without corrupting menu state. Results report final counts, whether each requirement is satisfied, and cumulative withdrawn and deposited counts.

Manage task handles and reconnects.