n3Plugins Source Of Truth

Current as of 2026-09-12. Live source wins when it differs from this document.

For per-plugin behavior, package ownership, action catalogs, SDK inventories, revision evidence, and focused test commands, read the repository-only docs/_internal/N3_DEVELOPMENT_REFERENCE.md reference.

Project Identity

n3Plugins is a single-module Java 11 external RuneLite plugin suite under com.n3plugins.*. RuneLite loads the suite through runelite-plugin.properties. Shared automation APIs live under com.n3plugins.Api.* and com.n3plugins.sdk.*.

PacketUtilsPlugin owns suite-wide runtime infrastructure: revision validation, packet and native-menu dispatch, walker ticking, action pacing, input locking, optional synthetic input, idle-logout prevention, proxy routing, optional companion dashboard telemetry posting, shared UI, and branding. Feature plugins consume those shared services instead of creating parallel runtime owners.

Build And Runtime Metadata

Item	Value
Group / version	com.n3plugins / 5.5
RuneLite	1.12.38
Game revision	240
Java	11
Build	Repository Gradle wrapper, Gradle 8.5
Source / resources	src/main/java / src/main/resources
Plugin manifest	runelite-plugin.properties
Canonical agent skills	.agents/skills/

Registered Plugins

runelite-plugin.properties is the implementation authority for registration.

Plugin	Entrypoint
Packet Utils	com.n3plugins.PacketUtils.PacketUtilsPlugin
Mule Orchestrator	com.n3plugins.muleplugin.MulePlugin
Walk Assistant	com.n3plugins.walkassistant.WalkAssistantPlugin
Dialogue Helper	com.n3plugins.dialoguehelper.DialogueHelperPlugin
Questing Assistant	com.n3plugins.questingassistant.QuestingAssistantPlugin
Quest Script Manager	com.n3plugins.questscript.QuestScriptManagerPlugin
Combat Awareness	com.n3plugins.combatawareness.CombatAwarenessPlugin
Code Console	com.n3plugins.codeconsole.CodeConsolePlugin
Java Shell	com.n3plugins.javashell.JavaShellPlugin
Market Alcher	com.n3plugins.marketalcher.MarketAlcherPlugin
Jewellery Enchanter	com.n3plugins.jewelleryenchanter.JewelleryEnchanterPlugin
Power Skiller	com.n3plugins.powerskiller.PowerSkillerPlugin
Tutorial Island	com.n3plugins.tutorialisland.TutorialIslandPlugin
Guardians of the Rift	com.n3plugins.guardiansrift.GuardiansRiftPlugin
Agent Server	com.n3plugins.agentserver.AgentServerPlugin
API Tester	com.n3plugins.apitester.ApiTesterPlugin
Bank Stander	com.n3plugins.bankstander.BankStanderPlugin
Bank Stander Plus	com.n3plugins.bankstanderplus.BankStanderPlusPlugin
GE Buyer	com.n3plugins.gebuyer.GeBuyerPlugin
GE Flipper	com.n3plugins.geflipper.FlipperPlugin
AIO Fighter	com.n3plugins.fighter.FighterPlugin
Inventory Setups	com.n3plugins.inventorysetups.InventorySetupsPlugin
Auto Looter	com.n3plugins.autolooter.AutoLooterPlugin
Auto Cooker	com.n3plugins.autocooker.AutoCookerPlugin
AIO Builder	com.n3plugins.aiobuilder.AioBuilderPlugin
Companion Uplink	com.n3plugins.telemetry.CompanionUplinkPlugin
N3 Test Runner	com.n3plugins.testharness.TestRunnerPlugin
Tutorial Island Test	com.n3plugins.tutorialisland.TutorialIslandTestPlugin
Upkeep	com.n3plugins.upkeep.UpkeepPlugin
Gemstone Crab Killer	com.n3plugins.crabkiller.CrabKillerPlugin
Varrock Cleaner	com.n3plugins.varrockcleaner.VarrockCleanerPlugin
Ontology	com.n3plugins.ontology.OntologyPlugin

Architecture Summary

• Feature plugins use RuneLite lifecycle events and request one meaningful action at a time through Api.actions.*.
• AIO Builder is registered but stopped by default. Its package-local scheduler owns the fixed 18-module registry, exact PREFLIGHT through BLOCKED state sequence, deterministic selection seam, immutable status snapshots, and active-only Break Handler lifecycle. Woodcutting, Mining, Fishing, Firemaking, Cooking, Smithing, and Prayer have live-capable child workflows; they retain only the AIO's exact Walker handle and verify gathering, burning, production, burial, storage, recovery, and return postconditions. RuneLiteAioBuilderRuntime owns current-session loadout observation and module-specific reconciliation. Ordinary-bank child workflows reuse BankWorkflowBuilder.BankCycle for open and close dispatch plus later interface observation. Mining keeps Port Sarim deposit-box handling module-local. Firemaking, Smithing, and Cooking reuse current pure lane, recipe, facility, batch, and target policies without importing another feature lifecycle owner. Missing acquisition and the other 11 modules remain fail-closed. The porting parity ledger owns acceptance status.
• AIO Builder's sidebar panel owns live controls and status: start/stop, pause/resume at a safe task boundary, sticky-block skip of the active module, ±10-minute task-duration adjustment, stop-after-task arming, session statistics (XP gained and rate from start-time baselines, observed coins, task and session clocks), and candidate-selection reasons from the snapshot. The controller exposes those operations; snapshots carry paused/stop-after-task flags plus an AioSessionSnapshot. AioBuilderProfileStore persists named whole-n3aiobuilder-group profiles (active marker included) in one profiles config key; the profiles key is exempt from mid-run scene invalidation alongside showOverlay and toggleHotkey. AioBuilderConfigWindow edits live config through the AioConfigBinding reflection bridge with tabs Modules, Locations, General, and Profiles, plus visibly disabled Task Queue, Gearing, Bonding & Muling, and Anti-Ban placeholder tabs reserving the planned layout.
• BankActions.openNearestAccessible() resolves bank objects through the active Shortest Path bank.tsv destination catalog, requires an exact Bank action and a reachable interaction tile, then selects by path distance. BankActions.openNearestAccessible() preserves the result-aware action contract; direct openNearest() remains a compatibility delegate.
• Shared navigation delegates global and multi-plane routing to Shortest Path; local collision previews do not gate Walker admission, and radius-aware walking retains exact path-handle ownership. Vessel transports require destination-side arrival when a gangplank crossing remains, and an exhausted land step can make one bounded nearby disembarkation attempt before normal replanning. Walker archives one correlated terminal telemetry event before clearing or replacing an active path, so Agent Server can report completed, failed, and cancelled outcomes while its active state remains truthfully idle.
• InteractionResult preserves readiness, pacing, dispatch, and failure status. Dispatch alone never proves the requested game-state transition completed.
• Ontology (com.n3plugins.ontology) is the behavior-cloning antiban port of the ccscripts ontology module: training mode records mouse paths (50ms watcher), camera gestures (250ms watcher), menu interactions, walks, typed key presses only (upstream parity; modifiers are never recorded), and behavior-graph state changes into the polymorphic Gson action log at n3/ontology/actionLog.json; replay mode compiles expected transitions under node constraints into typed reproducers and executes them tick-driven (no blocking sleeps) through Api.actions dispatch, CanvasInput gesture playback, KeyboardHelper, and shared-walker routing. Recording context snapshots are best-effort reads executed on the calling thread: game-thread recorders run inline while the key listener and capture watchers fall back to neutral context on transient read failure instead of blocking event dispatch on a client-thread hop. The behavior package owns the Node/ScriptNode/QuickNode graph with continuity-chained replay selection plus the UntrainedNode contract for scripted, never-trained fallback states (upstream GetToEdgeville ships as the reference implementation, unwired); the demo tree is the Blast Furnace iron-bar graph. The OntologyPanel sidebar panel owns the train/replay toggle and session status; OntologyOverlay is rendering-only.
• Shared workflow support includes AutomationLoop, TaskPipeline, typed state machines, workflow builders, event snapshots, fixtures, and deterministic scenarios.
• Shared combat support includes an onGameTick-owned TickDecisionList for ordered once-per-tick leaf evaluation, plus configurable eat and potion decisions. Action APIs retain pacing and dispatch ownership; tick decisions do not run inside TaskPipeline.
• EnchantingPlan and EnchantingWorkflowBuilder own shared jewellery-enchanting execution. They model typed spells, rune quantities, owned-staff coverage, bank preparation, and input/output cast confirmation; feature plugins supply plans instead of duplicating that state machine.
• Mule Orchestrator uses RuneLite Party as its outbound relay transport. Mule messages use a versioned envelope with master-only RSA signatures, HMAC-authenticated slave status, relay-member targeting, bounded replay protection, and readiness-gated queue activation; the existing mule state machines remain responsible for trade verification and completion.
• GameVarsRegistry owns revision-pinned varbit identifiers and immutable identifier-to-name metadata; DevTools and shared rune-pouch consumers use it instead of a DevTools-owned constants class.
• WidgetCatalog owns revision-pinned widget discovery and safe address resolution. It loads generated RuneLite gameval, WidgetID, and WidgetInfo declarations from the bundled widget-mapping TSV instead of maintaining a local monolithic widget-index class.
• Revision-sensitive behavior stays in Packet Utils and fails closed when the active client, bundled evidence, reflection shape, or cached evidence disagree.
• Packet Utils owns synthetic AWT canvas planning and playback. The TRAJECTORY profile retrieves profile-isolated local physical gestures, while RuneLite remains the movement-packet sampling and transmission authority. Planner fallback never permits transport fallback after synthetic input was requested.
• Packet Utils collects n3 Companion metrics through its own com.n3plugins.PacketUtils.companion transport with two independent paths. Primary: anonymous HTTP ingest (POST /v1/ingest/telemetry and /v1/ingest/account-event, no pairing) enabled by default (companionIngestEnabled, opt-out in config), keyed by a persisted per-install UUID and a client-computed stable 64-hex accountHash (Jagex Launcher account-id claim via n3 Profiles, legacy stored login+password per the contract formula, or a RuneLite in-game account-hash fallback; display-name changes never split history). Optional: the paired gateway (POST /v1/client/pair + outbound-only WSS /v1/client/gateway) for remote control sends hello, 30-second heartbeats, the same protocol-v1 frames, and account events; posting runs only while the Packet Utils runtime is up, the posting toggle stops frames with one collection_paused frame while heartbeats continue, and full shutdown closes the socket. Discord linking (dashboard /link?install= page plus status polling, consent version 2026-09-12.1) unlocks credential import to the user's Accounts page: manual with explicit confirmation, opt-in automatic per login (autoImportSessionData, default off, deduped by a hidden imported-hash set), and server-pushed credentials.deliver over the paired gateway; all credential payloads use the UID-keyed PBKDF2/AES-256-GCM envelope bound to install and account, and secret material is never logged. Opt-in behavior-trace upload (companionTraceUpload, default off) posts saved Ontology action logs gzip-compressed verbatim to POST /v1/ingest/traces when the install is Discord-linked; the companion stores the recording in the producer's format and never interprets action rows. The Companion Uplink plugin (com.n3plugins.telemetry) remains an optional legacy sender of the gateway protocol; both senders may run simultaneously and the server resolves duplicate accounting.
• Agent Server exposes authenticated loopback REST and direct MCP transports. Generated bearer-token authentication is enabled by default.
• Docusaurus publishes docs/; docs/_internal/ remains a tracked agent and development reference but is not public product documentation.
• Both distributed fat JARs bundle flatlaf-extras non-transitively for the Developer Tools Swing Inspector and UI Defaults Inspector. RuneLite continues to provide FlatLaf core; the suite must not package com.formdev.flatlaf.FlatLaf, and its manifest has no dependency Class-Path.
• The desktop installer uses EthanVann's official installer artifact (Ethan-Vann/Installer) for RuneLite launcher sideloading; external dependency injection and deps.json manifests are omitted.
• Quest Helper integration reflects against the player's externally installed official RuneLite Quest Helper plugin via QuestHelperSnapshotReader without bundled vendor copies.

Agent Entry Points

• Read AGENTS.md before substantive repository work.
• Use .agents/skills/n3-repo-workflow/SKILL.md to locate ownership.
• Use .agents/skills/n3-validation/SKILL.md to select proportionate validation.
• Start with llms.txt when graph tools are unavailable; use llms-optimized.txt for a compact digest and targeted sections of llms-full.txt for the complete generated corpus.

The generated LLM files remain tracked. Regenerate them after changes to repository authority, docs, or canonical skills:

python scripts/generate_llm_docs.py
python scripts/generate_llm_docs.py --check