Equipment and loadouts

Loadouts declare a target state; plans assert current state; actions change state. This page covers all three plus the tab-switching contract that gates them.

Equipment actions

EquipmentActions provides result-aware wear and remove dispatches. All writes return InteractionResult and route through the pacer.

Method	Behavior
`equip(String name)`	Wears or wields the first inventory item matching the name; the wear action (`Wear`, `Wield`, `Equip`) is resolved dynamically
`unequip(EquipmentInventorySlot slot)`	Removes the item in a slot
`unequip(String name)`	Removes the equipped item with the exact name
`isEquipped(String name)`	Query: whether an item with the name is equipped
`getEquipped(slot)`	`Optional<EquippedItem>` for the slot

EquipmentInventorySlot (RuneLite API) defines the slots: HEAD, CAPE, AMULET, WEAPON, BODY, SHIELD, ARMS, LEGS, HAIR, GLOVES, BOOTS, JAW, RING, and AMMO. Granular reads use com.n3plugins.sdk.query.Equipment and EquipmentItemQuery.

equip requires the Inventory tab to be visible. Both unequip overloads require the Equipment tab. A closed prerequisite returns WIDGET_HIDDEN targeting the required tab; these actions never open a tab for you.

if (!EquipmentActions.isEquipped("Dragon scimitar")) {
    InteractionResult result = EquipmentActions.equip("Dragon scimitar");
    if (result.getStatus() == InteractionStatus.PACED) {
        return; // retry next tick
    }
}

Check isEquipped(...) before calling equip(...) to avoid redundant widget interactions.

Loadouts

com.n3plugins.sdk.loadouts defines the desired state for inventory and equipment. A loadout is a target, not an action: bank and production workflow builders reconcile live game state against it.

Type	Purpose
`LoadoutItem`	Immutable item requirement: ID, amount, slot, flags
`InventoryLoadout`	The 28-slot inventory target
`EquipmentLoadout`	The worn-equipment target
`ItemDepletionListener`	Callback when a required item exhausts

InventoryPlan asserts current state (“do I have this right now?”). InventoryLoadout and EquipmentLoadout declare target state (“what should I hold or wear after restocking?”).

Build items fluently:

LoadoutItem logs = LoadoutItem.builder(ItemID.YEW_LOGS)
    .amount(27)
    .build();

LoadoutItem natures = LoadoutItem.builder(ItemID.NATURE_RUNE)
    .amount(100)
    .stackable(true)
    .build();

LoadoutItem staff = LoadoutItem.builder(ItemID.STAFF_OF_FIRE)
    .slot(EquipmentInventorySlot.WEAPON)
    .build();

Builder options: amount(int) (default 1), optional(boolean), noted(boolean), stackable(boolean), and slot(EquipmentInventorySlot) (required for equipment loadouts).

InventoryLoadout inv = new InventoryLoadout();
inv.add(LoadoutItem.builder(ItemID.YEW_LOGS).amount(27).build());
inv.add(LoadoutItem.builder(ItemID.KNIFE).amount(1).build());

boolean done = inv.isFulfilled();

EquipmentLoadout eq = new EquipmentLoadout();
eq.add(LoadoutItem.builder(ItemID.STAFF_OF_FIRE)
        .slot(EquipmentInventorySlot.WEAPON).build());

List<LoadoutItem> missing = eq.getMissingItems();
List<LoadoutItem> toEquip = eq.getUnequippedItems();

InventoryLoadout.add throws IllegalArgumentException when items exceed the 28-slot capacity. Both loadout types expose isFulfilled(), getRequiredItems(), getExcessItems(), getForeignItemIds(), and setItemDepletionListener(...). Builders use getForeignItemIds(), getMissingItems(), and getUnequippedItems() to plan deposits, withdrawals, and equips. ItemMetadataResolver derives stackability from client metadata. In tests without a client, set stackable(...) explicitly or inject a resolver with ItemMetadataResolver.setResolverForTesting(...). BankActions.withdraw(loadout, maxActions) withdraws missing loadout items with a depletion listener and an action cap:

loadout.setItemDepletionListener(item -> replan(item.getItemId()));
InteractionResult result = BankActions.withdraw(loadout, 10);

Tab actions

TabActions separates deliberate tab changes from check-only prerequisites.

Method	Behavior
`open(Tab)`	Finds the first visible widget across the tab’s three packed IDs (fixed, resizable, bottom-line) and clicks it with `Switch`, `Open`, or `Select`. Returns `TAB_NOT_FOUND` when none are visible
`requireOpen(Tab)`	Returns `CONFIRMED` when visible; otherwise `WIDGET_HIDDEN` targeting `tab/<TAB_NAME>` without clicking
`isOpen(Tab)`	Idempotency guard

if (!TabActions.isOpen(Tab.PRAYER)) {
    TabActions.open(Tab.PRAYER);
}

The Tab enum covers COMBAT, SKILLS, QUESTS, INVENTORY, EQUIPMENT, PRAYER, MAGIC, FRIENDS_CHAT, FRIENDS, LOGOUT, SETTINGS, EMOTES, and MUSIC. Each constant holds three packed widget IDs; a zero value means the slot is absent in that layout.

open is the only shared tab API that changes the selected tab, and a dispatched click is not proof of convergence. Interface states such as an open bank hide sidebar tabs entirely, which surfaces as TAB_NOT_FOUND. Observe isOpen(...) after dispatch instead of relying on the result alone.

Requested inventory, equipment, prayer, magic, combat, and minigame actions never select a side tab for their caller. Open the tab explicitly first.

Introduction

Getting Started

Playbooks

Plugin Guides

Developer Tools

Companion

Equipment and loadouts

Equipment actions

Loadouts

Tab actions

​Equipment actions

​Loadouts

​Tab actions

Equipment actions

Loadouts

Tab actions