Skip to main content

Migration Guide

All new automation must utilize the result-aware API to handle failure conditions properly via InteractionResult. Read-only state lives under com.n3plugins.sdk.query.*; result-aware writes live under com.n3plugins.Api.actions.*.

Architectural Standards:

  • Plugins function as native RuneLite entries.
  • PacketUtilsPlugin acts as the sole required shared infrastructure and owns walker ticking.
  • We completely removed Account bootstrap flows.
  • Break Handlers run strictly active-only.
  • IdMapRegistry replaces wiki scraping and external scripts.
  • Shared SDK code resides under com.n3plugins.sdk.*.

API Modernization​

Legacy Pattern​

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

Result-Aware Pattern​

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

Migration Rules​

  1. Preserve legacy helpers in existing plugins unless actively refactoring the call site.
  2. Adopt InteractionResult methods exclusively in new workflow code.
  3. Utilize com.n3plugins.sdk.* for shared client, widget, query, walker, loadout, and workflow components.
  4. Maintain Java 11 compatibility across public APIs.

Removed Compatibility Layers​

The legacy *Interaction helper classes and the former com.n3plugins.sdk.widgets *Api facades (InventoryApi, BankApi, WidgetApi, and related wrappers) have been removed. Source-compatible shims are not maintained; migrate call sites directly to the two current surfaces.

NeedCurrent Surface
Result-aware writescom.n3plugins.Api.actions.*: InventoryActions, BankActions, BankInventoryActions, NPCActions, ObjectActions, PlayerActions, PrayerActions, ShopActions, GrandExchangeActions, WidgetActions, ...
Read-only statecom.n3plugins.sdk.query.*: Inventory, Bank, Widgets, Dialogue, Equipment, Shop, GrandExchange, NPCs, TileObjects, ...

Run migrations incrementally: replace each removed call with its result-aware counterpart and handle the InteractionResult.failed() case at the immediate decision point.

N3BuilderF2P Port​

The focused reports below define API mapping details. The full development plan owns product scope, module disposition, phases, and acceptance gates.

Focused Migration Reports​