Migrating to result-aware actions

All new automation uses the result-aware API. Read-only state lives under com.n3plugins.sdk.query.* and result-aware writes live under com.n3plugins.Api.actions.*. The legacy *Interaction helper classes and the former sdk.widgets *Api facades (InventoryApi, BankApi, WidgetApi, and related wrappers) are removed, and no source-compatible shims are maintained.

The pattern change

Legacy helpers returned booleans and left you guessing which stage failed:

boolean clicked = InventoryInteraction.useItem("Bones", "Bury");
if (!clicked) {
    return;
}

Current actions return an InteractionResult that preserves readiness, pacing, dispatch, and failure status:

InteractionResult result = InventoryActions.use("Bones", "Bury");
if (result.failed()) {
    log.debug("Inventory action failed: {}", result.getMessage());
    return;
}

Handle result.failed() at the immediate decision point. A PACED status means the pacer is still cooling down, not that the target vanished; re-evaluate on the next tick.

Surface map

Need	Current surface
Result-aware writes	`Api.actions.*`: `InventoryActions`, `BankActions`, `BankInventoryActions`, `NPCActions`, `ObjectActions`, `PlayerActions`, `PrayerActions`, `ShopActions`, `GrandExchangeActions`, `WidgetActions`, and the rest of the action catalog
Read-only state	`sdk.query.*`: `Inventory`, `Bank`, `Widgets`, `Dialogue`, `Equipment`, `Shop`, `GrandExchange`, `NPCs`, `TileObjects`

Rules

Adopt InteractionResult methods in all new workflow code.
Preserve legacy helpers in existing plugins until you actively refactor the call site, then replace each removed call with its result-aware counterpart.
Use com.n3plugins.sdk.* for shared client, widget, query, walker, loadout, and workflow components instead of re-implementing helpers.
Keep public APIs Java 11 compatible.

Other architectural standards

Plugins are native RuneLite entries registered in runelite-plugin.properties.
PacketUtilsPlugin is the single required shared runtime and the only walker tick owner.
Break handlers run active-only: they track time while automation runs and stop while idle.
IdMapRegistry and WidgetCatalog replace ID scraping and external scripts.

Introduction

Getting Started

Playbooks

Plugin Guides

Developer Tools

Companion

Migrating to result-aware actions

The pattern change

Surface map

Rules

Other architectural standards

​The pattern change

​Surface map

​Rules

​Other architectural standards

The pattern change

Surface map

Rules

Other architectural standards