Suite runtime

PacketUtilsPlugin is the shared runtime every n3 plugin depends on. It stays enabled by default and owns the suite-wide services that feature plugins consume instead of rebuilding.

What the runtime owns

Service	Responsibility
Revision validation	Validates the active client against bundled evidence and fails closed on a mismatch
Menu dispatch	Resolves and caches the native menu dispatcher from client bytecode
Walker ticking	Advances the active `WalkerPath` once per logged-in tick
Action pacing	Two-layer timing variance for every dispatched action
Input locking	Blocks dispatch while a lock is held, refreshes locks each tick
Idle-logout prevention	Optional client-wide idle prevention up to the game’s forced six-hour logout
Synthetic input	Opt-in canvas mouse planning and playback
Proxy routing	Optional SOCKS proxy routing for the whole client
Telemetry	Optional companion metrics posting, off until you enable it
Shared UI	The n3 sidebar, branding, and the Developer Tools runtime

The suite has no loader entrypoint and no external API plugin dependency. Feature plugins never tick the walker or the pacer themselves.

The suite tick hook

// PacketUtilsPlugin.java
@Subscribe
public void onGameTick(GameTick e) {
    ActionPacer.onTick(System.currentTimeMillis());
    Walker.tick();
}

RuneLite fires all onGameTick handlers synchronously on the client thread in one dispatch cycle. Packet Utils subscribes first, so the pacer’s tick and the walker’s tick run before any feature plugin sees the same tick.

Action pacing in depth

ActionPacer uses two layers of variance:

Tick gate: a random 1-3 tick gap between recorded actions, configurable.
Millisecond jitter: a bounded, humanized reaction-time sample within the configured tick window.

The jitter activates on the tick after the gate first opens. Same-tick isReady() calls see a future jitter target, and by the next game tick (600 ms later) the jitter has elapsed. When the gate transitions from closed to open, the pacer sets the jitter target once and does not move it forward on subsequent open ticks, so repeated isReady() checks inside one dispatch never lock out the action. Configuration API:

ActionPacerConfig.defaults();               // 1-3 ticks, 0-200 ms jitter
ActionPacerConfig.of(minTicks, maxTicks, minMs, maxMs);
ActionPacer.configure(config);              // swap the active configuration
ActionPacer.reset();                        // restore defaults, clear cooldowns

Keep pacing configuration suite-level. A feature plugin must not change the pacer profile for its own actions unless the whole suite adopts that timing model. The pacer is a bounded timing policy, not a guarantee.

Shared randomness comes from sdk.random.N3Random, which never sleeps or blocks. Optional SessionFatigue scaling is disabled by default; a runtime that opts in must pause and resume it on the same monotonic time base used for pacing so logout, idle, and break time are not counted.

SDK initialization

PacketUtilsPlugin.startUp() calls N3Client.initialize(), which registers the SDK query and listener helpers with the RuneLite event bus for: inventory, bank, bank inventory, equipment, deposit box, NPCs, players, tile objects, and shops. The SDK ships inside the same plugin jar under com.n3plugins.sdk.*. It is not a RuneLite plugin and never appears in the plugin list.

Idle-logout prevention

With preventIdleLogout enabled, the runtime holds the client’s idle timeout at the maximum the client accepts (90,000 client ticks) and dispatches a harmless Shift press and release shortly before the input-idle counters reach the threshold. The setting is independent of plugin activity and leaves only the game’s forced six-hour logout. Disabling the toggle or shutting down Packet Utils restores the timeout captured when the toggle was applied.

Headless mode

Headless mode is an optional, disabled-by-default setting in the n3packetutils group that replaces the client panel with an interactive status map. RuneLite still requires a display; this is UI suppression, not JVM headless operation. When active:

The original client panel detaches from presentation but stays alive for client geometry. The canvas ignores gameplay input. The sidebar stays responsive.
The GPU plugin stops before the map installs and only the exact stopped instance restarts when headless mode ends.
The map renders collision tiles, the player, the active walker route, position and region data, and route outcomes. Left-click delegates to Walker.walkTo, right-click offers walk, cancel, and copy-coordinates actions, drag pans, the wheel zooms, Ctrl+wheel selects a plane, and middle-click toggles player follow.
Entering headless mode cancels active synthetic paths. New synthetic requests reject with synthetic_disabled_in_headless_mode. Packet, native-menu, client-thread, walker, and plugin automation paths keep working.

Disable, shutdown, or a partial activation failure restores the captured UI state.

Proxy routing

Packet Utils config owns the Proxy Settings fields (proxyEnabled, proxyHost, proxyPort, proxyUsername, proxyPassword). Disabling the proxy restores the JVM proxy selector and authenticator that existed before Packet Utils enabled its SOCKS selector. Per-profile proxies are managed in Profiles.

Diagnostics

Api.debug.SuiteRuntimeStatus.snapshot() returns a read-only snapshot containing:

the RevisionHealthCheck log, expected bundled revision, and live client revision
the mapping revision label
walker tick ownership plus active and walking walker state
the current ActionPacerStatus

It is observational. Use it to explain blocked or unhealthy states. The shared sidebar’s Suite status tab presents the same information.

Walker resources

The suite does not package the walker’s pinned shortest-path resources in the jar. On startup, the resource downloader fetches the SHA-backed archive into .runelite/n3Plugins/shortestpath/, stages it, validates it, and installs it. Feature plugins must not download, embed, or independently tick shortest-path data. See Navigation for the walker itself.

Introduction

Getting Started

Playbooks

Plugin Guides

Developer Tools

Companion

What the runtime owns

The suite tick hook

Action pacing in depth

SDK initialization

Idle-logout prevention

Headless mode

Proxy routing

Diagnostics

Walker resources

​What the runtime owns

​The suite tick hook

​Action pacing in depth

​SDK initialization

​Idle-logout prevention

​Headless mode

​Proxy routing

​Diagnostics

​Walker resources

What the runtime owns

The suite tick hook

Action pacing in depth

SDK initialization

Idle-logout prevention

Headless mode

Proxy routing

Diagnostics

Walker resources