> ## Documentation Index
> Fetch the complete documentation index at: https://runelite.zip/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to result-aware actions

> Move from boolean helper calls to InteractionResult actions and the two current API surfaces.

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:

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

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

```java theme={null}
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](/guides/interactions) |
| Read-only state     | `sdk.query.*`: `Inventory`, `Bank`, `Widgets`, `Dialogue`, `Equipment`, `Shop`, `GrandExchange`, `NPCs`, `TileObjects`                                                                                                                                          |

## Rules

1. Adopt `InteractionResult` methods in all new workflow code.
2. Preserve legacy helpers in existing plugins until you actively refactor the call site, then replace each removed call with its result-aware counterpart.
3. Use `com.n3plugins.sdk.*` for shared client, widget, query, walker, loadout, and workflow components instead of re-implementing helpers.
4. 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.