Scripting patterns

This page teaches the event-driven shape of n3Plugins automation. The examples show the decision loop and real API signatures. A production plugin additionally needs registration, configuration, break handler lifecycle, and shutdown cleanup; the plugin development playbook covers the surrounding skeleton.

Design process

Work through the same five questions every time:

Walkthrough: bone buryer

A minimal skiller loop: find bones in the inventory, bury one per tick, and wait out the animation.

package com.n3plugins.boneburyer;

import com.n3plugins.Api.actions.InventoryActions;
import com.n3plugins.Api.common.InteractionResult;
import com.n3plugins.sdk.query.Inventory;
import net.runelite.api.Client;
import net.runelite.api.events.GameTick;
import net.runelite.client.eventbus.Subscribe;
import net.runelite.client.plugins.Plugin;
import javax.inject.Inject;

public class BoneBuryerPlugin extends Plugin {
    @Inject private Client client;
    private int lastFiredTick = -1;

    @Subscribe
    public void onGameTick(GameTick event) {
        int currentTick = client.getTickCount();
        if (currentTick == lastFiredTick) return;   // run once per server tick

        if (client.getLocalPlayer().getAnimation() != -1) {
            return;                                  // wait out the bury animation
        }

        Inventory.search()
            .withName("Bones")
            .first()
            .ifPresent(bone -> {
                InteractionResult result = InventoryActions.use(bone, "Bury");
                if (result.succeeded()) {
                    lastFiredTick = currentTick;
                }
            });
    }
}

Walkthrough: bank runner with a state machine

A full inventory of willow logs triggers a bank restock through BankWorkflowBuilder, which manages opening, depositing, withdrawing, and closing:

@Subscribe
public void onGameTick(GameTick event) {
    boolean needsBanking = Inventory.search().withName("Willow logs").count() >= 27;

    if (needsBanking && bankMachine == null) {
        bankMachine = BankWorkflowBuilder.create(
            BankRestockPlan.builder()
                .inventoryLoadout(loadout)
                .build());
    }

    if (bankMachine != null) {
        CarouselResult<BankRestockState> result = bankMachine.pulse(client.getTickCount());

        if (result.getSnapshot().getStatus() == WorkflowStatus.COMPLETED
                || result.getSnapshot().getStatus() == WorkflowStatus.FAILED) {
            bankMachine = null;
        }
    }
}

Walkthrough: stateless dialogue helper

Dialogue widgets exist only while the server presents them. React within the tick and keep no memory across ticks:

@Subscribe
public void onGameTick(GameTick event) {
    int currentTick = client.getTickCount();
    if (currentTick == lastFiredTick) return;   // one dialogue click per tick

    if (Dialogue.isPresent()) {
        // Prefer a Quest Helper marked option when one is present
        if (DialogActions.chooseQuestHelperMarkedOption().succeeded()) {
            lastFiredTick = currentTick;
            return;
        }
        DialogActions.continueDialogue();
        lastFiredTick = currentTick;
    }
}

Pattern: pacing

ActionPacer is suite-wide and driven by Packet Utils. The action APIs check it internally, so never gate your own tick loop on ActionPacer.isReady(...). Packet Utils increments the tick count and applies jitter before your handler runs, so a same-tick isReady() check returns false at the wrong moment and starves your automation.

// Avoid: pacer check in your own loop
if (!ActionPacer.isReady(System.currentTimeMillis())) return;
NPCActions.interact("Banker", "Bank");

// Prefer: let the action API pace, react to the result
InteractionResult result = NPCActions.interact("Banker", "Bank");
if (result.getStatus() == InteractionStatus.PACED) {
    // re-evaluate next tick
}

Pattern: spatial selection

Entity lists are not sorted by distance. first() grabs whatever the raw scan returned and produces unstable target choice. Select by path reachability or by a stable anchor:

// Avoid: raw memory order
TileObject tree = TileObjects.search().withName("Yew").first().orElse(null);

// Prefer: nearest path-reachable target
TileObject tree = TileObjects.search()
    .withName("Yew")
    .nearestByPath()
    .orElse(null);

// Prefer: stable work area anchored to a landmark
TileObject workAreaTree = TileObjects.search()
    .withName("Yew")
    .walkable()
    .nearestToPoint(workAreaAnchor)
    .orElse(null);

QueryResults.nearestTo(...) and sortedByDistanceTo(...) use straight-line tile distance. When reachability decides the action target, use nearestByPath().

Pattern: spell resolution

Spell widgets are revision-backed addresses. Resolve names through the shared resolver backed by the Api.actions.Spell catalog, and treat an empty result as a configuration error:

Optional<Integer> spellId = MagicActions.resolveSpellInfo("High Level Alchemy");
if (!spellId.isPresent()) {
    return; // unsupported or misspelled name; retry after configuration changes
}

// Cast by enum; the resolver derives the packed widget ID (High Alchemy is
// InterfaceID.MagicSpellbook.HIGH_ALCHEMY).
MagicActions.cast(Spell.HIGH_LEVEL_ALCHEMY, target);

Never copy a packed spell widget ID into a plugin or depend on removed widget-constant wrappers. Use resolveSpellWidget(...) when the workflow needs the live widget; it stays empty when the spell is not visible in the active spellbook.

Pattern: query freshness

Query builders scan and cache per tick. Caching a builder across ticks reads stale state:

// Avoid: a cached query builder
private ItemQuery inventoryQuery;

// Prefer: build the query every tick
int foodCount = Inventory.search().withName("Lobster").count();

Pattern: ordered tick decisions

When several combat policies must run in a fixed order once per tick, use TickDecisionList instead of duplicating lastFiredTick guards. See tick decisions for the full contract.

Loop ergonomics

AutomationLoop wraps the observe-decide-act cycle when a plugin wants loop-style ergonomics while keeping ownership in its own onGameTick:

AutomationLoop loop = new AutomationLoop(
        AutomationLoopConfig.builder(this)
                .tickSupplier(client::getTickCount)
                .requireBootstrap(true)
                .breakGate(() -> breakHandler.shouldBreak(this),
                        () -> breakHandler.isBreakActive(this),
                        () -> breakHandler.startBreak(this))
                .build(),
        context -> {
            InteractionResult result = NPCActions.interact("Banker", "Bank");
            return result.succeeded()
                    ? LoopPulseResult.active(result.getMessage())
                    : LoopPulseResult.waiting(result.getMessage());
        });

@Subscribe
public void onGameTick(GameTick event) {
    loop.pulse();
}

AutomationLoop.fromPipeline(...) and AutomationLoop.fromStateMachine(...) adapt existing workflows without creating another pacer, walker, or global tick owner.

Read, then act

Pair a read surface with its result-aware write:

Production.findProduct("Shortbow")
        .ifPresent(product -> log.debug("Make-X option {}", product.getIndex()));

InteractionResult result = ProductionActions.chooseOption("Shortbow");

Quest and diary progress reads mirror requirement helpers:

QuestProgressApi.isComplete(Quest.COOKS_ASSISTANT);

DiaryProgressApi.progress(DiaryRegion.LUMBRIDGE, DiaryTier.EASY)
        .filter(DiaryProgress::isComplete)
        .ifPresent(progress -> log.debug("Lumbridge easy complete"));

DiaryProgressApi exposes only explicitly mapped varbit and varplayer-backed tasks. Unknown diary coverage is absent rather than guessed.

The rules reviewers enforce

Do not sleep. Let the tick dispatcher drive progression.
Keep dialogue handlers stateless: click what is visible, otherwise do nothing.
Use an intentional spatial selector: nearestByPath() for reachable targets, walkable().nearestToPoint(anchor) for a work area. Never first() as a nearest-target policy.
Gate full automation on the break handler; pause actions during planned or active breaks.
Inspect InteractionResult at the decision point. Do not compare messages and do not treat dispatch as completion.
Resolve IDs from gameval.ItemID, IdMapRegistry, and WidgetCatalog. Never hardcode identifiers.
Route every write through Api.actions.*. Do not call raw packet queues directly.

Introduction

Getting Started

Playbooks

Plugin Guides

Developer Tools

Companion

Scripting patterns

Design process

Walkthrough: bone buryer

Walkthrough: bank runner with a state machine

Walkthrough: stateless dialogue helper

Pattern: pacing

Pattern: spatial selection

Pattern: spell resolution

Pattern: query freshness

Pattern: ordered tick decisions

Loop ergonomics

Read, then act

The rules reviewers enforce

​Design process

​Walkthrough: bone buryer

​Walkthrough: bank runner with a state machine

​Walkthrough: stateless dialogue helper

​Pattern: pacing

​Pattern: spatial selection

​Pattern: spell resolution

​Pattern: query freshness

​Pattern: ordered tick decisions

​Loop ergonomics

​Read, then act

​The rules reviewers enforce

Design process

Walkthrough: bone buryer

Walkthrough: bank runner with a state machine

Walkthrough: stateless dialogue helper

Pattern: pacing

Pattern: spatial selection

Pattern: spell resolution

Pattern: query freshness

Pattern: ordered tick decisions

Loop ergonomics

Read, then act

The rules reviewers enforce