Java Shell

Verification boundary

This page describes the committed source guideline. It skips certifying revision-sensitive RuneLite UI, packet, or in-game outcomes; treat those as live-client verification pending unless the page records direct evidence.

JavaShellPlugin operates as a disabled-by-default, hidden developer tool. It provides a lazily-created Groovy evaluator window with pre-bound RuneLite client, n3 Api.actions.*, and SDK query bindings.

• Entrypoint: com.n3plugins.javashell.JavaShellPlugin
• Descriptor: [n3] Java Shell (hidden = true, session/developer console)
• Config group: none (no persistent configuration)
• Enabled by default: no
• Break Handler: none (developer tool, not an automation plugin)

---

Architecture

The plugin registers a sidebar NavigationButton on startup. Clicking it lazily creates and toggles a standalone JavaShellFrame window. The plugin creates the frame and its Groovy executor on demand and disposes them on shutdown. The editor is a dependency-free Swing JTextArea.

---

Groovy Evaluator

GroovyExecutor evaluates session-only Groovy snippets using Groovy 3.0.17. Each execution:

1. Creates a fresh GroovyShell with the plugin's classloader.
2. Binds client (RuneLite Client) and clientThread (ClientThread) as instance variables.
3. Binds n3 Api.actions.* and sdk.query.* types as static API facades.
4. Redirects System.out / System.err to the output pane for the duration of the snippet.
5. Captures and displays the evaluation result or any caught exception.

Execution happens on the RuneLite client thread via clientThread.invokeLater(...). Snippets read live game state directly. Only one script runs at a time; a running flag prevents concurrent dispatch.

Caution

Snippets execute with full access to the RuneLite client and n3 SDK. Arbitrary code can mutate game state, dispatch packets, and interfere with running automation. Use only for developer debugging and inspection.

Tab-dependent requested actions propagate WIDGET_HIDDEN and do not select a side tab. Use tabActions.open(...), wait until tabActions.isOpen(...) is true, and only then call the inventory, equipment, prayer, magic, or combat action.

Pre-Bound Variables

Variable	Type	Kind
client	Client	Instance, the RuneLite client
clientThread	ClientThread	Instance, RuneLite client thread scheduler
bankActions	BankActions	Static facade
dialogActions	DialogActions	Static facade
inventoryActions	InventoryActions	Static facade
magicActions	MagicActions	Static facade
npcActions	NPCActions	Static facade
navigationActions	NavigationActions	Static facade
objectActions	ObjectActions	Static facade
playerActions	PlayerActions	Static facade
prayerActions	PrayerActions	Static facade
tileItemActions	TileItemActions	Static facade
widgetActions	WidgetActions	Static facade
bank	Bank	Static query builder
inventory	Inventory	Static query builder
npcs	NPCs	Static query builder
objects	TileObjects	Static query builder
players	Players	Static query builder
tileItems	TileItems	Static query builder
interactionApi	Map<String, Class<?>>	All API type bindings

Static bindings expose only static methods in autocompletion. Instance bindings (client, clientThread) expose all public methods.

---

Editor

The editor window currently uses a plain JTextArea without syntax highlighting or completions. The execution bindings remain available; richer editor integration is deferred until it can be supplied without the removed FifeSoft runtime jars.

Controls

Control	Action
Ctrl+Enter	Execute the current editor content
Run Code button	Same as Ctrl+Enter
Clear Output button	Clears the output pane

Output Pane

The output area displays captured System.out/System.err text, evaluation results prefixed with => , and errors prefixed with Error: . The pane caps output at 40,000 characters and trims excess from the beginning.

---

Plugin-Manifest Dependencies

The Java Shell does not require external editor or JShell jars. FlatLaf Extras is bundled non-transitively in the distributed suite for Developer Tools Swing inspection and is unrelated to Java Shell execution. RuneLite supplies FlatLaf core.

The fat jar packages Groovy 3.0.17 as a runtime dependency.

---

Example Snippets

// Read current game state
client.getGameState()

// Query inventory for rune essence
inventory.search().withName("Rune essence").result()

// Check if bank is open
bankActions.isOpen()

// Walk to a location
import net.runelite.api.coords.WorldPoint
navigationActions.walkTo(new WorldPoint(3164, 3486, 0))

// List nearby NPCs
npcs.search().result().each { println it.getName() }

---

Testing

.\gradlew.bat test --tests com.n3plugins.javashell.* --console plain

Break Handlers run active-only.