Every plugin has three surfaces: a sidebar panel, a settings studio, and in-game overlays. All three
come from the shared UI kit in privbot.ui, privbot.ui.fx and privbot.ui.overlay. This
page is the recipe set and the rules a review checks; the types are in the API reference,
https://privbot.dev/javadoc/privbot/ui/package-summary.html.
The contract
| Surface | Use | Never |
|---|---|---|
| Sidebar | PrivBotPanel.builder(name)...build(), attached with PluginUi.attach(...), removed with ui.detach() |
extends PluginPanel, a hand-built NavigationButton, a refresh() call |
| Studio | FxStudioShell.forConfig(...), or FxStudioShell.builder().standardSize().addConfigSections(...).addFxSection(...) |
A second studio stack, a private window class |
| Overlays | PrivBotOverlays.panel(...) / .scene(client) over a Snapshot<S>, installed with PrivBotOverlays.install(...), closed with OverlaySet.close() |
Client hooks or ctx.* in render, RuneLite Perspective, per-plugin *TileUtil projection code |
| Theme | privbot.ui.ModernTheme (Swing), privbot.ui.fx.PrivBotFxStyles + the .root tokens in privbot-studio.css (JavaFX), privbot.ui.overlay.OverlayTheme / ColorRamp (overlays) |
Private palettes, inline colours |
Status always carries a glyph and text, never colour alone. User-chosen overlay colours enter only
through OverlayPalette.of(settings) (settings implements privbot.ui.overlay.PaletteSettings).
Threads for UI code
| Code | Runs on | Reads |
|---|---|---|
Panel suppliers (stat, runtime, startStop running check) |
Swing EDT, every refresh | RunState fields, taskTree.getActiveTaskStatus(), cached values |
| Start / Stop / Settings callbacks | Swing EDT | Must return quickly; never wait on the game |
| Studio pages | JavaFX thread | Config, published state; background work goes to a worker |
Overlay composers (rows, draw) |
Render thread, every frame | The snapshot passed in. Nothing else |
| Snapshot publishing | Game tick, while running | ctx.read(...) once per tick |
Recipe: sidebar panel
public final class MyPanel {
private MyPanel() {}
public static PrivBotPanel create(MyPlugin plugin) {
return PrivBotPanel.builder("My Plugin")
.startStop(plugin::startPlugin, plugin::stopPlugin, plugin::isEnabled) // polled; no refresh()
.settings(plugin::openStudio)
.stat("Task", () -> plugin.getActiveTaskName() != null ? plugin.getActiveTaskName() : "Idle")
.stat("Status", plugin::getStatusMessage)
.stat("Kills", plugin::getKills)
.runtime("Runtime", plugin::getStartedAt) // Supplier<Instant>; null renders "-"
.refreshEvery(600)
.build();
}
}
// Plugin.startUp()
ui = PluginUi.attach(clientToolbar, "My Plugin", () -> MyPanel.create(this),
MyPlugin.class, "/com/example/myplugin/icon.png");
// Plugin.shutDown()
if (ui != null) { ui.detach(); ui = null; }
For a richer state, ui.panel().setStatus(PanelStatus.WARNING, "LOW HP") shows a glyph with the
text (PanelStatus: IDLE, RUNNING, PAUSED, WARNING, ERROR). An extra button goes through
.action(label, accentColor, onClick). Subclassing PrivBotPanel is allowed for custom content
(getButtonRow(), getStatsPanel()); extends PluginPanel is not.
Recipe: settings studio
public void openStudio() {
SwingUtilities.invokeLater(() -> {
FxPlatformUtil.primeEmbeddedFxToolkitOnEdt();
if (studio != null) {
studio.dispose();
}
studio = FxStudioShell.forConfig("My Plugin", "Combat settings", config, configManager)
.runningIndicator(this::isEnabled) // optional; reads published state only
.build();
studio.show();
});
}
// Plugin.shutDown()
if (studio != null) {
FxStudioShell s = studio;
studio = null;
SwingUtilities.invokeLater(s::dispose);
}
forConfig makes one page per @ConfigSection (one "Settings" page when there are none), writes
values live, and uses the standard 960x720 size. For bespoke pages:
studio = FxStudioShell.builder()
.standardSize()
.brand("My Plugin", "Loadouts and settings")
.addConfigSections(config, configManager)
.addFxSection("loadouts", "Loadouts", "Loadouts", "Gear sets per style",
() -> LoadoutPage.build(this), true) // Supplier<javafx.scene.Node>, runs on the FX thread
.build();
The shell draws each page's title and subtitle; the body must not repeat them. Build bodies from
privbot.ui.fx.FxFormKit and the kit style classes. A page that needs game data asks a worker and
applies the result with Platform.runLater, skipped if the window closed. Settings a running plugin
reads are applied as one immutable object swapped into a volatile field, so a run never sees half
a change. Disk writes from a page go to a worker, never the FX thread.
Recipe: HUD panel from a per-tick snapshot
public final class MyOverlays {
private final Snapshot<View> view = Snapshot.empty();
private OverlaySet installed;
public void install(OverlayManager manager, BooleanSupplier running) {
installed = PrivBotOverlays.install(manager,
PrivBotOverlays.panel("My Plugin")
.visibleWhen(running)
.rows(view, (r, s) -> { // render thread: s only
r.status("Task", s.task, OverlayTheme.INFO);
r.fraction("HP", s.hp, s.maxHp, ColorRamp.percentBelow(50));
r.progress("Kills", s.kills, s.killTarget);
r.rowIf(s.deaths > 0, "Deaths", s.deaths, OverlayTheme.BAD);
r.runtime("Runtime", s.startedAt);
}));
}
/** Game tick, only while running. One read scope; the render never reads the client. */
public void publish(MyTaskContext ctx, String task, Instant startedAt) {
View v = ctx.read(() -> new View(task, ctx.user.getHitpoints(), ctx.user.getMaxHitpoints(),
ctx.runState.kills, ctx.config.killTarget(), ctx.runState.deathsThisSession, startedAt));
if (v != null) {
view.publish(v);
}
}
public void close() {
if (installed != null) {
installed.close();
installed = null;
}
view.clear();
}
/** Immutable display data. */
static final class View {
final String task;
final int hp, maxHp, kills, killTarget, deaths;
final Instant startedAt;
// constructor omitted
}
}
Rows gives title, row, status, fraction, progress, runtime, rowIf, text and
divider. ColorRamp gives percentBelow(threshold), ticks(urgentAt, warnAt) and fixed(color).
OverlayTheme colours: TITLE, LABEL, VALUE, MUTED, GOOD, WARN, BAD, INFO,
HIGHLIGHT.
Recipe: scene overlay for tiles and countdowns
private final Snapshot<SceneView> scene = Snapshot.empty();
// install, next to the HUD panel
PrivBotOverlays.scene(client)
.visibleWhen(this::isEnabled)
.draw(scene, (c, s) -> { // render thread: s only
for (Hazard h : s.hazards) {
c.countdown(h.tile, h.ticksLeft, ColorRamp.ticks(1, 2));
}
if (s.safeTile != null) {
c.tile(s.safeTile, OverlayTheme.GOOD);
}
if (s.bossTile != null) {
c.label(s.bossTile, "Boss", OverlayTheme.TITLE, 200);
}
});
// game tick, while running: copy WorldPoints into the snapshot
scene.publish(new SceneView(hazardsFrom(ctx.view), safeTileFrom(ctx.view), bossTileFrom(ctx.view)));
SceneCanvas gives tile, tiles, area, label, countdown, line, path, labelBox,
progressBar and shadowText on WorldPoints, plus outline(actor, color) and
tileOf(actor, color). The actor forms read the live actor at render time; prefer a WorldPoint
copied into the snapshot. Projection goes through SceneProjection, which works on every server;
RuneLite Perspective silently draws nothing on Impact and Elorin.
Pitfalls for UI code
- Render reads the snapshot and nothing else. On some servers the render thread cannot call client hooks; a facade call there fails or stalls every frame (rule 14).
- Publish only while running. A stopped plugin builds no HUD and reads nothing (rule 5). Clear the snapshot on Stop so a stale HUD never shows on the next Start.
- Panel suppliers run on the EDT every refresh. Return cached values; a client read there blocks the UI.
- Close everything in
shutDown():overlays.close(),ui.detach(),studio.dispose()on the EDT. A plugin reloads without restarting the client. - No colour without a glyph or text for status. Use
PanelStatusandRows.status. - No private palette. Use
OverlayTheme,ColorRamp,ModernThemeand the studio tokens.
Read next
The starter project wires all three surfaces: the sidebar panel (ui/MyPanel), the settings studio
(MyPlugin.openStudio()) and a HUD overlay (ui/MyOverlays, which publishes a Snapshot on the game tick and
draws it with PrivBotOverlays.panel). Start from those.
Unit-test this with the testkit, see Testing plugins.
