Humanization and safety

Four subsystems work together to keep automation bounded and recoverable: the humanizer SDK schedules passive gestures, synthetic mouse routes supported actions through canvas movement, the input lock keeps manual input from colliding with automation, and the break handler schedules and executes breaks.

​

Humanizer SDK

The humanizer has two separate responsibilities with no cross-plugin arbitration:

• HumanizerService schedules optional passive gestures for the plugin that owns it.
• Packet Utils applies deterministic account and session modifiers to synthetic mouse paths.

​

Gesture scheduling

HumanizerService.onTick(active, now, tickCount) advances a scheduler on the client thread. The owning plugin passes active = true only during a safe passive or waiting state, and a pending gesture completes before a new one is considered so held input releases on its scheduled tick. AntiBanProfile controls whether the scheduler runs, its activity and intensity, the minimum and maximum scheduling windows, and the allowed gesture kinds. Current categories: right-click item, camera nudge, tab glance, right-click actor, and offscreen mouse rest. The owning plugin’s GestureExecutor implements the concrete effects and cleanup. Call reset() when the plugin stops or its runtime state becomes invalid. Do not enable passive gestures during timing-sensitive combat, prayer, inventory, trade, or recovery states.

​

Account-derived mouse behavior

BehaviorProfile.forAccount(client.getAccountHash()) derives stable per-account values with independent salted derivations. The raw account hash and any profile file are not retained; diagnostics expose only a short derived fingerprint. Invalid or unavailable account hashes use neutral values. SessionFatigue counts wall-clock time while a logged-in account is bound, pauses on logout or shutdown, resets on account change, and reaches its bounded factor over a six-hour session. Synthetic mouse planning uses the factor to reduce effective speed and increase jitter. The Mouse humanization setting is enabled by default and independent of Use synthetic mouse: it changes path planning only when a caller already selected synthetic transport, and it does not reroute packet actions or schedule gestures. Packet Utils’ Mouse Behavior panel displays the full account profile and offers seven manual checks: arrow camera, middle-drag camera, XP glance, Equipment glance, predictive hover, mouse nudge, and offscreen rest. Manual actions fail closed while logged out, in headless mode, while the input lock is held, while another manual action runs, or while gameplay owns a synthetic path.

​

Synthetic mouse

Packet Utils owns the synthetic mouse planner, recorder, lifecycle, and action bridge. The feature is disabled by default under Synthetic Mouse in the Packet Utils configuration.

​

Configuration

​

Supported actions

The runtime bridge covers NPCActions.interact(...), ObjectActions.interact(...), paced WidgetActions operations without a composite resume-count step, UseItemActions.dragAndDrop(...) (a held-button AWT drag), and walker land movement. Other action classes keep their existing dispatch; enabling the toggle does not reroute every interaction suite-wide. For supported actions the dispatcher validates the request, selects a landing point inside the live clickbox, and starts the shared EDT timer. Only one path owner exists at a time, and the pacer records the action as soon as the request is accepted so callers yield while movement is in progress. On arrival, the client thread installs the retained target as the forced left-click entry, issues the native click, and restores the preceding menu. NPC and object action resolution indexes the entity’s raw composition action slot directly, preserving exact menu entries for entities with non-contiguous action arrays.

​

Fail-closed boundary

Synthetic dispatch never falls back to reflection packets after the caller requested synthetic input. Busy mice, missing clickboxes, canvas changes, manual input, or failed movement fail closed; UseItemActions.dragAndDrop(...) never falls back to its widget-drag packet, and the walker retries unprojectable ground movement through its bounded stall and replan policy rather than sending a direct movement packet. Manual canvas input, logout, shutdown, canvas-size changes, and view-mode changes cancel the current path, and request-correlated arrivals are invalidated so a stale callback cannot click later. Headless mode rejects every synthetic request with synthetic_disabled_in_headless_mode. When synthetic dispatch is disabled, direct packet actions still resolve a center-biased Gaussian landing point inside the target’s live canvas shape before sending the click event. An unprojectable shape fails closed and suppresses the action packet rather than falling back to a default coordinate.

​

Capture and trajectories

MouseRecorder captures physical AWT canvas events while recording is enabled; synthetic events are marked and excluded. The extractor segments movement into gestures (press/drag/release sequences become DRAG gestures), interpolates a 50 ms cadence, and rejects invalid timestamps, off-canvas samples, out-of-range durations, and degenerate paths. Raw schema-2 JSONL sessions store under .runelite/n3/mouse/recordings/<profile>/, and the versioned trajectory snapshot stores under .runelite/n3/mouse/trajectories/<profile>/trajectory-store-v1.json. The store keeps at most 10,000 trajectories across seven endpoint-distance buckets with per-bucket reservoir sampling, and stable content-derived IDs keep indexing idempotent. The TRAJECTORY profile builds paths from recorded gestures: it ranks candidates by endpoint distance, direction, and velocity, aligns them with endpoint-affine warping, and blends two or three candidates while preserving the top candidate’s acceleration shape. Start and landing coordinates stay exact; noise affects interior points only. An underqualified dataset does not reject an otherwise valid click: the planner falls back to the Recorded statistical profile and then the standard planner, all inside the AWT transport.

​

Input lock

InputLockService blocks game-canvas keyboard, mouse, wheel, and menu-click input while active automation plugins request the lock. The Packet Utils setting Block user input during automation defaults to on; turning it off changes nothing about automation behavior but lets manual input reach the game. The lock uses RuneLite’s KeyManager and MouseManager, an AWT listener filtered to the client canvas, VarClientInt.BLOCK_KEYPRESS, and MenuOptionClicked.consume(). It skips OS-level actions, RuneLite side panels, plugin config edits, and client closure, so you can still use the RuneLite UI outside the game canvas. Automation plugins request the lock only while managing active work and must re-request from their active tick path; Packet Utils refreshes the lock each game tick and expires stale owners after a short window. Always-on helper plugins (Dialogue Helper, Upkeep) hold no input lock by design. Suite-dispatched input wraps in InputLockBypass.withSyntheticInput(...), so automation can still type, click, move the camera, and dismiss menus while the lock blocks manual input.

​

Break handler

Packet Utils owns the break handler runtime and its shared-sidebar tab (n3breakhandler config group). Break handling is disabled by default and stays neutral until you select Enable Break Handler. Enabling it mid-run begins break scheduling without restarting automation.

​

Consumer API

Inject the BreakHandler service and: The plugin schedules breaks from per-plugin threshold spinners. A consumer registers, starts, and pauses its work while a break remains active.

​

The active-only contract

Full automation plugins must integrate as an active-only runtime requirement:

1. Register on startup and unregister on shutdown.
2. Call startPlugin(this) only while automation runs actively, and stopPlugin(this) when idle, disabled, completed, halted, or shut down.
3. Check shouldBreak(this) and isBreakActive(this) before gameplay actions. When a planned break triggers, call startBreak(this), release any input lock, and skip the action tick.
4. Pause task-duration timers while breaking or paused so breaks do not consume active runtime.

The suite’s automation break handler registration test enforces this contract. Required integrations include Market Alcher, Power Skiller, GE Buyer, GE Flipper, AIO Fighter, Auto Looter, Tutorial Island, Guardians of the Rift, Mule Orchestrator, and Bank Stander. Quality-of-life plugins (Dialogue Helper, Walk Assistant, Questing Assistant, Combat Awareness, Inventory Setups) hold intentional exemptions, and support plugins without automation loops are classified separately.

​

State machine and re-login

The state machine walks NULL, INVENTORY (active gameplay), LOGOUT, LOGIN_SCREEN, RECONNECTING, and RESUME states. Logout runs the ESC, logout-tab, logout-button chain; the login screen resolves the visible welcome-screen target without hardcoded child IDs. Re-login starts only when every active break has elapsed and the client rests on the login screen, with a five-second initial idle followed by jittered backoff of 15 seconds, 60 seconds, and five minutes. Backoff resets only after a stable logged-in state with the welcome screen closed. Auto bank pin entry types one digit per tick and blocks key presses through BLOCK_KEYPRESS.

​

Login sources

Break anti-idle mouse events select a center-biased point within the live canvas and never fall back to a default corner coordinate.

​

Options

The Options tab controls stopAfterBreaks, autoBankPin, autoLoginOnDisconnect, world-avoidance filters (player count and world numbers), and hop-after-break with region preferences. Per-plugin settings cover thresholds, break duration, enablement, and logout behavior.