Skip to main content

Headless Mode

Packet Utils maintains an optional, persistent Enable headless mode setting in the n3packetutils config group. It defaults to disabled. This operates as a RuneLite UI-suppression mode. RuneLite requires AWT and a display, and it rejects JVM java.awt.headless startup.

When activation completes, Packet Utils replaces RuneLite's attached client panel with an interactive status map. The original client panel and normal-sized canvas stay alive for client geometry, but detach from presentation. The canvas ignores focus and gameplay input. The sidebar stays attached and responsive.

The activation-time UI adapter resolves RuneLite's frame, client panel, sidebar, and parent container. It captures component order, visibility, size constraints, canvas input state, and sidebar visibility/selection before making any changes. Disable, Packet Utils shutdown, or partial activation failure restores that captured state. The saved preference persists during restoration.

GPU ownership​

An active RuneLite GPU plugin must stop before the map installs. Packet Utils respects GPU's saved enabled preference. It records the exact running plugin instance it stops and restarts only that instance when headless mode ends. An initially inactive GPU plugin stays inactive. A failed stop aborts activation and restores the normal UI. A failed restart triggers a report but stops Packet Utils from starting a different GPU instance.

Interactive map​

The map receives immutable snapshots on game ticks and performs all component mutation and painting on Swing's event-dispatch thread. It displays:

  • collision tiles from the current shared collision state;
  • player, active Walker route, and requested-destination markers;
  • game state, world position, region, plane, and Walker state;
  • route failure/cancellation status and the explicit Synthetic input blocked state.

Left-click delegates a new request to Walker.walkTo. Right-click offers Walk here, Cancel active walk, and Copy coordinates. Drag pans, the wheel zooms, Ctrl+wheel selects a plane, and middle-click toggles player-follow. No local route planner exists in the map: Shortest Path stays the sole planning authority. Normal Walker replacement, cancellation, transport, banking, pacing, and correlated-result behavior remain active. Terminal routes clear the active destination marker after Walker archives their completed, failed, or cancelled outcome in telemetry.

Interaction boundary and diagnostics​

Entering headless mode cancels active synthetic paths. New synthetic preview, click, and Walker-arrival requests reject without packet fallback using:

synthetic_disabled_in_headless_mode

Packet, native-menu, client-thread, Walker, Agent Server, event, and plugin automation paths remain available. Suite runtime status and Agent Server suite capabilities report the active headless state, synthetic availability, and the stable unavailability reason.

Live acceptance​

Static tests and a successful build fail to constitute live acceptance. An installed RuneLite launcher run must retain logs, Agent Server state, and screenshots of both display modes, then demonstrate:

  1. map replacement with a responsive sidebar and stopped GPU;
  2. zoom, pan, follow, plane selection, and coordinate copy;
  3. click-to-walk, cancellation, unreachable failure, and successful arrival;
  4. Shortest Path route evidence plus the arrival postcondition;
  5. the documented synthetic rejection alongside packet/native event and postcondition evidence;
  6. exact canvas/layout/sidebar restoration and GPU restart only when owned.

Live client verification remains pending until you record that evidence.