Developer docs

Cookbook: overlays and UI

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 PanelStatus and Rows.status.
  • No private palette. Use OverlayTheme, ColorRamp, ModernTheme and the studio tokens.

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.