Inventory and containers
Read inventories and move items safely between containers.
Use bot.inventory to query or move items.
Use a container handle for several operations on the same menu.
The handle includes the latest revision and rejects a stale or replaced menu.
Open, transfer, and close
yield* Effect.scoped(
Effect.gen(function* () {
const chest = yield* bot.inventory.openScoped(chestPosition);
yield* chest.deposit(
{ itemIds: ["minecraft:cobblestone"] },
64,
);
yield* chest.withdraw(
{ tags: ["minecraft:foods"] },
16,
);
}),
);deposit moves an exact item count from the inventory or hotbar into the container.
withdraw moves items in the other direction.
Both methods plan the full transfer before they click any slots.
They stop if the source has too few items or the destination has too little space.
Inspect current state
Read container.snapshot without another RPC. It contains:
- Container and state IDs
- A stable content revision
- Container type and semantic layout
- Every slot and its inventory area
- Cursor contents
- Selected hotbar slot
Call refresh after another actor changes the menu.
If a different menu is open, the handle closes and raises SoulFireContainerClosedError.
Choose the best item
SoulFire can rank the bot's tools, melee weapons, armor, food, and safe scaffold blocks. Every recommendation includes its slot, item snapshot, total score, and the factors that produced that score.
const tool = yield* bot.inventory.bestTool(blockPosition, {
preferHotbar: true,
preferHighDurability: true,
preferredEnchantmentIds: ["minecraft:fortune"],
excludedEnchantmentIds: ["minecraft:vanishing_curse"],
});
if (tool !== undefined) {
yield* Effect.logInfo(tool.factors);
}Tool rankings use the loaded target block and the bot's real mining calculation. Weapon rankings consider attack damage and speed. Armor rankings consider defense, toughness, and knockback resistance. Food rankings reject harmful consumables and compare nutrition with saturation. Scaffold rankings only include safe, non-falling block items.
Use rank when you want several candidates. Enchantment preferences add a
visible score factor, while exclusions remove a candidate entirely. The
response carries the inventory revision so a later mutation can reject stale
input.
Retry safely
Supply an idempotency key when retrying an operation after an uncertain network result:
yield* chest.deposit(selector, 64, {
idempotencyKey: crypto.randomUUID(),
});The server binds the key to the authenticated user, bot, operation, and request fingerprint. Reusing it with different input is rejected.
The SDK also exposes snapshot, count, find, move, transfer, toss,
rank, selectHotbar, equip, and unequip for one-off inventory
operations. unequip moves a main-hand, offhand, or armor item into the
first compatible empty player slot.
Generated protocol clients remain available for unusual container fields.
Continue with durable production tasks for crafting, smelting, brewing, and exact-count villager trading.
How is this page?
Last updated on