Skip to main content

n3Plugins AI Agent Handbook

Verification boundary

This page documents the committed source. Treat revision-sensitive RuneLite UI, packet, or in-game outcomes as pending live-client verification unless the page records direct evidence.

Use this handbook for quick orientation, review protocol, and critical implementation patterns when building API, SDK, or plugin work.

Core References​

Canonical guides own each stage of development:

TopicCanonical Document
Platform contract & lifecycledocs/agent/RUNELITE_DEVELOPMENT.md
Authority order & behavioral rulesRepository-root AGENTS.md and N3PLUGINS_SOURCE_OF_TRUTH.md
Plugin creation workflowagent-plugin-production-loop.md
Workflow driver selectionsdk-pipeline-guide.md
Testing & failure taxonomyagent-testing-loop.md
Validation suites & manual checklistvalidation.md
Fast-path onboardingRepository file .agents/QUICK_START.md
Decision checklists & task patternsdocs/agent/DECISION_PLAYBOOK.md

Review Flow​

Review diffs in this order before finalizing:

  1. User request & plan: verify changes match the requested scope without hidden refactors.
  2. Source/SOT consistency: verify registered plugins, packages, and architecture match reality.
  3. API & SDK reuse: check Api.actions.* and InteractionResult usage; ensure no duplicate helpers.
  4. Shared ownership: verify PacketUtilsPlugin retains bootstrap, pacer, walker, and client-thread ownership.
  5. Anti-detection & timing: check action pacing, non-deterministic humanized timing, and clean transient state reset on logout/hop.
  6. Tests, docs, and live notes: run focused tests, update docs, and report unverified client behavior as Live client verification: pending.

Use stop-slop on docs. Cut filler, cite real files, and avoid claims lacking source or live client evidence support.

Docs and SOT Sync​

Use Docusaurus-native admonitions for callouts in docs/: :::note, :::tip, :::info, :::warning[Caution], and :::danger. Avoid GitHub callout blockquotes (> [!WARNING]) in repo docs. See documentation-style-guide.md for authoring standards.

Keep the SOT short. Put detailed playbooks in docs and register them in docs-site/sidebars.js.

Key Implementation Patterns​

1. Dialogue Mechanics​

  • OSRS Dialogue is Stateless: Dialogue interfaces lack persistent state. Interact immediately when a target dialogue widget appears on the current tick (once the shared ActionPacer is ready). Avoid complex retry backoffs, lockout mechanisms, or signature tracking.
  • Deduplication: Implement local tick-guards (e.g. lastFiredTick) to prevent duplicate submissions on the same tick, and invoke ActionPacer.recordAction() immediately upon packet dispatch.
  • Widget Visibility: Widgets.search().result() returns hidden widgets. The game destroys OSRS dialogue widgets rather than hiding them when closed.

2. Testing Constraints​

  • JUnit & Mockito: Never use mockStatic, MockedStatic, or mockito-inline. Use dependency seams and injected collaborators.
  • Action Pacer: Always call ActionPacer.reset() in your @Before setup when tests touch action pacing.
  • Widget API: Use Widgets.setClientForTesting(client) in @Before and clean up via resetClientForTesting() in @After.
  • Stubbing Order: Ensure mocks are completely defined before invoking Mockito's when().

3. Task Pipelines: Prefer Event Yielding​

  • Do not poll for UI loads: When a TaskPipeline clicks an object and expects an interface to open (e.g. Bank), avoid polling manually every tick or using StepResult.waitTicks(). Yield the pipeline immediately using StepResult.waitForEvent(WidgetLoaded.class, ...). This provides sub-tick precision and prevents tick spam.