Workflow builders and plans

The com.n3plugins.sdk.workflow package ships builders for common automation domains. Each builder accepts an immutable plan and returns a configured TypesafeCarouselStateMachine, so you get the domain’s full state machine (opening, reconciliation, verification, teardown) without writing it. See the automation loop guide for how to pulse and observe the machines these builders return.

Bank restocking — `BankWorkflowBuilder`

BankRestockPlan describes the expected inventory and equipment states for a restock run:

BankRestockPlan plan = BankRestockPlan.builder()
    .inventoryLoadout(myInventoryLoadout)
    .equipmentLoadout(myEquipmentLoadout)
    .build();

TypesafeCarouselStateMachine<BankRestockState> bankMachine = BankWorkflowBuilder.create(plan);

The machine walks OPEN_BANK (nearest accessible registered bank), DEPOSIT (unneeded inventory and equipment), WITHDRAW (required loadout items), EQUIP (gear from inventory), and CLOSE_BANK.

Reusing the bank cycle

Caller-owned workflows that need selective deposits or withdrawals can reuse the shared interface cycle without handing item policy to a restock plan:

BankWorkflowBuilder.BankCycle<MyState> bank = BankWorkflowBuilder.cycle(
    runtime::bankOpen,
    runtime::openBank,
    runtime::closeBank,
    runtime::tick);

bank.open(MyState.DEPOSIT, MyState.VERIFY_BANK_OPEN);
bank.verifyOpen(MyState.DEPOSIT, 80);
bank.close(MyState.RETURN, MyState.VERIFY_BANK_CLOSE, "Returning to work");
bank.verifyClose(MyState.RETURN, 8, "Returning to work");

BankCycle records the dispatch tick and requires a later bank-interface observation. Your code keeps deposit, withdrawal, loadout, and return-state policy.

Range-aware fulfillment

Use LoadoutFulfillmentBuilder when requirements have minimum or maximum ranges, item variants, noted withdrawal mode, strict foreign-item handling, or an acquisition policy. Its equipment-first sequence reopens the bank before inventory reconciliation after equipping. Non-standard Withdraw-X and Deposit-X actions enter SUBMIT_BANK_QUANTITY, submit the visible prompt on a later pulse, and return to the requesting phase. States: OPEN_BANK, EQUIPMENT, INVENTORY, SUBMIT_BANK_QUANTITY, VERIFY. Read the terminal FulfillmentResponse with LoadoutFulfillmentBuilder.responseOf(machine).

Combat — `CombatWorkflowBuilder`

CombatPlan configures targeting, thresholds, and looting:

CombatPlan plan = CombatPlan.builder()
    .targetPredicate(npc -> npc.getName().equals("Gargoyle"))
    .eatFoodBelow(50, ItemID.SHARK)
    .toggleSpecAt(50)
    .enablePrayersDuring(Prayer.PROTECT_FROM_MELEE)
    .lootItems(ItemID.GRANITE_MAUL, ItemID.COINS_995)
    .build();

TypesafeCarouselStateMachine<CombatState> combatMachine = CombatWorkflowBuilder.create(plan);

The machine walks FIND_TARGET, ATTACK_TARGET, FIGHTING (eating, potions, special attacks, prayers), WAIT_FOR_DEATH (disables combat prayers), and LOOT_ITEMS.

Production — `ProductionWorkflowBuilder`

ProductionPlan defines product selection, quantity, and restock parameters:

ProductionPlan plan = ProductionPlan.builder()
    .optionName("Willow longbow")
    .quantity(ProductionQuantity.ALL)
    .restockLoadout(fletchingLoadout)
    .build();

TypesafeCarouselStateMachine<ProductionState> productionMachine =
    ProductionWorkflowBuilder.create(plan);

The machine walks WAIT_FOR_PRODUCTION_OPEN, SELECT_OPTION (by name or index), SELECT_QUANTITY, WAIT_FOR_PRODUCTION_COMPLETE (watches animations and inventory), and BANK_RESTOCK.

Rune pouch — `PouchWorkflowBuilder`

PouchPlan declares the rune loadout the pouch must hold:

PouchPlan plan = PouchPlan.builder()
    .requiredRunes(runePouchLoadout)
    .build();

TypesafeCarouselStateMachine<PouchState> pouchMachine = PouchWorkflowBuilder.create(plan);

The machine walks EVALUATE (compare pouch contents), EMPTY (insufficient or incorrect contents), and FILL (fill from inventory).

Spellbook swap — `SpellbookWorkflowBuilder`

SpellbookPlan declares the target spellbook:

SpellbookPlan plan = SpellbookPlan.builder()
    .targetSpellbook(Spellbook.ANCIENT)
    .build();

The machine walks CHECK_CAPE (Magic cape equipped or in inventory), INTERACT (Spellbook swap on cape or altar), and SELECT (finish the dialogue).

Jewellery enchanting — `EnchantingWorkflowBuilder`

EnchantingPlan models a typed spell, the unenchanted input, the exact enchanted output, per-cast rune quantities, and ordered owned-staff candidates. EnchantingWorkflowBuilder validates the Standard spellbook and boosted Magic level, prepares bank supplies, equips the chosen staff, and closes the bank before casting. It counts inventory and rune-pouch quantities and treats an equipped elemental staff as infinite coverage only for the runes its StaffOption declares. The builder snapshots input and output quantities before each cast and reports progress only after the input decreases and the configured output increases. Preserve that confirmation boundary: an accepted interaction does not confirm an enchantment.

Essence pouch planning — `EssencePouchWorkflowBuilder`

A pure planner (no dispatch) shared with the runecrafting workflow. EssencePouchPlan holds the pouches you carry plus the runecrafting level that gates usable capacities:

EssencePouchPlan plan = EssencePouchPlan.builder()
    .runecraftLevel(74)
    .pouchItemIds(Arrays.asList(ItemID.SMALL_POUCH, ItemID.MEDIUM_POUCH, ItemID.LARGE_POUCH))
    .build();

int space = plan.availableSpace();

Helpers on the builder:

availableSpace(itemIds, runecraftLevel) totals free essence space across usable pouches. A non-degraded colossal pouch supersedes smaller degraded pouches.
colossalCapacity(level) returns colossal capacity at the level (25/50/75/85 map to 8/16/27/40).
isDegradedPouch(itemId) identifies degraded variants.
hasDegradationPrevention(equipmentIds) checks for a runecrafting, trimmed, or max cape plus a Redwood lantern.
fillOperations(guardianEssence, pouches) and emptyOperations(inventoryFreeSlots, pouches) return the ordered EnumSet<EssencePouchOperation>. The builder consumes the pouch list in caller order, so pass pouches in the order you want them filled or emptied.

build() throws IllegalStateException when pouchItemIds was never supplied. Repair routing is deliberately excluded because repair NPCs are minigame-specific.

Introduction

Getting Started

Playbooks

Plugin Guides

Developer Tools

Companion

Workflow builders and plans

Bank restocking — `BankWorkflowBuilder`

Reusing the bank cycle

Range-aware fulfillment

Combat — `CombatWorkflowBuilder`

Production — `ProductionWorkflowBuilder`

Rune pouch — `PouchWorkflowBuilder`

Spellbook swap — `SpellbookWorkflowBuilder`

Jewellery enchanting — `EnchantingWorkflowBuilder`

Essence pouch planning — `EssencePouchWorkflowBuilder`

​Bank restocking — BankWorkflowBuilder

​Reusing the bank cycle

​Range-aware fulfillment

​Combat — CombatWorkflowBuilder

​Production — ProductionWorkflowBuilder

​Rune pouch — PouchWorkflowBuilder

​Spellbook swap — SpellbookWorkflowBuilder

​Jewellery enchanting — EnchantingWorkflowBuilder

​Essence pouch planning — EssencePouchWorkflowBuilder

Bank restocking — `BankWorkflowBuilder`

Reusing the bank cycle

Range-aware fulfillment

Combat — `CombatWorkflowBuilder`

Production — `ProductionWorkflowBuilder`

Rune pouch — `PouchWorkflowBuilder`

Spellbook swap — `SpellbookWorkflowBuilder`

Jewellery enchanting — `EnchantingWorkflowBuilder`

Essence pouch planning — `EssencePouchWorkflowBuilder`