> ## Documentation Index
> Fetch the complete documentation index at: https://runelite.zip/llms.txt
> Use this file to discover all available pages before exploring further.

# Humanization and safety

> The humanizer SDK, synthetic mouse, input locking, and the break handler lifecycle.

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.

| Value                                    | Range                            |
| ---------------------------------------- | -------------------------------- |
| Speed and acceleration multipliers       | 0.90-1.10                        |
| Curvature and jitter multipliers         | 0.85-1.15                        |
| Overshoot probability                    | 2-8%                             |
| Near-miss probability                    | 0.5-2%                           |
| Preferred camera mode                    | Arrow keys or middle-button drag |
| Camera frequency multiplier              | 0.75-1.25                        |
| Preferred glance tab                     | XP or Equipment                  |
| Micro-break frequency multiplier         | 0.75-1.25                        |
| Reaction-delay mean / standard deviation | 80-160 ms / 15-45 ms             |
| Fatigue rate                             | 0.85-1.15                        |

`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

| Setting                         | Effect                                                                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Use synthetic mouse             | Routes supported SDK actions through cursor movement and a native AWT click instead of the reflection packet path |
| Mouse humanization              | Applies account and session fatigue modifiers to synthetic paths (on by default, independent of the toggle above) |
| Mouse profile                   | Selects Default, Lazy, Fast, Recorded, or Trajectory motion                                                       |
| Show click locations and trails | Renders validated target bounds, landing point, planned path, and traversed trail for 2.5 seconds                 |

### 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.

<Info>
  The input backend reports `AWT_CANVAS_ONLY`: events dispatch to the RuneLite canvas and the operating-system pointer does not move. Agent Server capability output exposes `osPointerSynchronized=false`. The focusability guard prevents synthetic clicks from stealing keyboard focus and never spoofs focus, window, or occlusion state.
</Info>

### 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.

```mermaid theme={null}
flowchart TD
    A[Break handler service] -->|Planned break due| B[Plugin checks shouldBreak]
    B --> C[Release input lock]
    C --> D[Call startBreak and pause automation]
    D --> E{Logout configured?}
    E -->|Yes| F[Logout: Esc, logout tab, logout button]
    E -->|No| G[Stay logged in and idle]
    F & G --> H[Wait for break duration]
    H --> I[Re-login when all active breaks elapse]
    I --> J[Auto bank PIN entry]
    J --> K[Automation resumes]
```

### Consumer API

Inject the `BreakHandler` service and:

| Method                                                | Purpose                                  |
| ----------------------------------------------------- | ---------------------------------------- |
| `registerPlugin(plugin)` / `unregisterPlugin(plugin)` | Appear in the panel                      |
| `startPlugin(plugin)` / `stopPlugin(plugin)`          | Begin or stop runtime and break tracking |
| `isBreakActive(plugin)` / `shouldBreak(plugin)`       | Gate work loops                          |
| `startBreak(plugin)`                                  | Begin a due break                        |
| `setExtraData(plugin, key, value)`                    | Surface live status in the panel         |

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

| Login mode | Re-login behavior                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Manual     | Credentials entered directly in the Accounts tab                                                                                                 |
| Profiles   | Reads the encrypted n3 Profiles store (requires a configured unlock password) and applies legacy or Jagex profiles through `ProfileLoginService` |
| Launcher   | Uses the existing Jagex Launcher session                                                                                                         |

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.