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

# Interface

> The settings window, minimap button, global status toggles, and /volvox slash commands.

## Theme

`volvox.Theme` (defined in `Interface/Theme.lua`) is the shared dark-modern palette, font, spacing, and size token set consumed by every GUI file — the settings window, the [sidebar](#settings-window), the [GUI builder](/framework/gui-builder) pages, the status toggle frame, the minimap button, and the Gatherer status bar. It loads between `Module/Module` and `Core/StatusToggles` so it exists before any consumer.

### Palette

Color entries are `{ r, g, b, a }` arrays in 0-1 range:

| Name      | Hex       | Used for                              |
| --------- | --------- | ------------------------------------- |
| `bg0`     | `#0b0f14` | Window backdrop                       |
| `bg1`     | `#131922` | Panels                                |
| `bg2`     | `#1b232e` | Fields, buttons                       |
| `border`  | `#2a3542` | All borders                           |
| `text`    | `#e6edf3` | Normal text                           |
| `muted`   | `#8b98a5` | Secondary text                        |
| `accent`  | `#007aff` | Blue accent — the single accent color |
| `success` | `#6db15f` | Success states                        |
| `warn`    | `#ecad41` | Warnings                              |
| `danger`  | `#e05b63` | Errors, destructive states            |

Alongside the colors:

* `volvox.Theme.font` = `{ family = UNIT_NAME_FONT or STANDARD_TEXT_FONT, size = 12, titleSize = 18, headerSize = 14 }`
* `volvox.Theme.spacing` = `{ gutter = 20, pad = 12, sectionGap = 18, labelGap = 20 }` — column gutter, outer window inset, extra gap above section headers, and headroom reserved above widgets with TOP labels.
* `volvox.Theme.size` = `{ windowWidth = 900, windowHeight = 560, titleHeight = 44, sidebarWidth = 170, sidebarEntryHeight = 28, sidebarSubEntryHeight = 24, sidebarGroupLabelHeight = 24 }` — the settings window and sidebar geometry.

### Helpers

```lua theme={null}
---@param name string           -- palette entry name (e.g. "accent")
---@param alphaOverride number|nil
---@return number r, number g, number b, number a
function volvox.Theme:Get(name, alphaOverride)
```

Returns a named color as four numbers for `SetColorTexture` / `SetTextColor` call sites. Raises an error for an unknown color name.

```lua theme={null}
---@param name string
---@param alphaOverride number|nil
---@return table color          -- { r = , g = , b = , a = }
function volvox.Theme:Table(name, alphaOverride)
```

Returns the color as an `{ r=, g=, b=, a= }` keyed table for StdUi config entries.

```lua theme={null}
---@param name string
---@return string hex           -- e.g. "007aff"
function volvox.Theme:Hex(name)
```

Returns the color as a 6-char lowercase hex string for `|cff...|r` markup (used by the minimap tooltip and dropdown titles).

## Settings window

`volvox.Interface` (defined in `Interface/Default.lua`) is the main settings window, built on the bundled StdUi toolkit with its config derived from `volvox.Theme`. The window is `Theme.size.windowWidth × Theme.size.windowHeight` (900×560) with a teal 24px **LOOTROUTE** header in the title strip.

Navigation is a **left sidebar** (`volvox.Sidebar`, defined in `Interface/Sidebar.lua`): single-page categories get one clickable entry, and multi-page categories (built with the [GUI builder](/framework/gui-builder)) get an uppercase group label plus one indented sub-entry per page. The selected entry is highlighted with an `accent` fill at 0.16 alpha, a 3px accent bar on its left edge, and `text`-colored caption; unselected entries are `muted` and highlight `bg2` on hover.

The content area to the right of the sidebar is a single StdUi scroll frame. Pages are built **lazily on first view** via `StdUi:BuildWindow`, then measured deterministically by re-running their EasyLayout rows — there are no height-probing timers. Each lazy page starts at the scroll viewport height so `fullSize` custom rows (such as the Systems panels) are measured against a usable frame instead of collapsing to a placeholder. `volvox.Interface.UpdateContentHeight()` relayouts the currently shown page and resizes the scroll child, for pages that build content asynchronously.

Settings pages are declared with the [GUI builder](/framework/gui-builder); two pages ship built-in:

* **General** (`Interface/Layout/General.lua`) — tick mode and tick rate.
* **Modules** (`Interface/Layout/Modules.lua`) — enable/disable toggles for every registered [module](/framework/modules).

### Sidebar API

```lua theme={null}
---@param parent table   -- the settings window
---@param width number   -- sidebar width in pixels
---@return table sidebar
function volvox.Sidebar:Create(parent, width)
```

The returned sidebar panel exposes:

| Method                                               | Purpose                                                                                 |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `sidebar:AddEntry({ id, text, indent?, onSelect? })` | Add a clickable navigation entry; `indent = true` renders a smaller, indented sub-entry |
| `sidebar:AddGroupLabel(text)`                        | Add a non-clickable, uppercase, muted group label                                       |
| `sidebar:Select(id)`                                 | Select an entry: restyle and fire its `onSelect(id)` callback                           |
| `sidebar:SetSelected(id)`                            | Mark an entry selected without firing `onSelect`                                        |
| `sidebar:GetSelected()`                              | Return the currently selected entry id                                                  |

The active sidebar instance is stored at `volvox.Interface.settingsSidebar` after `InitializeGUI()`. Page ids are `"<category>"` for single-page categories and `"<category>/<page>"` for GUI-builder pages (for example `"LootRoute/Routes"`).

### Opening it

```lua theme={null}
---@return nil
function volvox.OpenSettings()
```

Opens (or toggles) the settings window. It restores interface categories, forces a full GUI rebuild if the LootRoute category is missing, and — when the frame isn't built yet — sets `volvox.openConfigWhenReady = true` so the window opens as soon as it exists.

## Single Button Assistant

`_SingleButtonAssistant.lua` exposes `volvox.SingleButtonAssistant` and persists its module toggle at `modules.singleButtonAssistant`. The Modules page shows an **Enable SBA** checkbox when the assistant has loaded.

When Gatherer is enabled, SBA only runs while Gatherer's `State` is `FIGHT`; otherwise it still requires `UnitAffectingCombat("player")` before casting. Each tick reads Blizzard's assisted-combat suggestion, validates target/range/usability, then protected-casts the exact spell ID via the global `CastSpellByID`; `CastSpellByName` is used only as a fallback when the exact-ID path is unavailable or the protected ID callback fails. Nil exact-ID returns are reported as unconfirmed instead of immediately falling back, because `CastSpellByID` is command-style and a same-tick name fallback can queue the same suggestion twice.

The standalone slash command is `/wggsba`:

| Command         | Action                          |
| --------------- | ------------------------------- |
| `/wggsba on`    | Enable the repeating SBA ticker |
| `/wggsba off`   | Disable the ticker              |
| `/wggsba stats` | Print tick/cast/skip counters   |
| `/wggsba reset` | Reset counters                  |
| `/wggsba debug` | Toggle SBA debug messages       |

## Slash commands

Registered in `Core/Macro.lua` under `/volvox` (dispatcher exposed as `volvox.Macro`):

| Command            | Action                                           |
| ------------------ | ------------------------------------------------ |
| `/volvox`          | Open the settings window                         |
| `/volvox settings` | Open the settings window                         |
| `/volvox config`   | Open the settings window                         |
| `/volvox minimap`  | Show the minimap button (clears the hidden flag) |

Unknown sub-commands log a warning. New commands register through:

```lua theme={null}
---@param name string                 -- sub-command keyword (stored lowercased)
---@param handler fun(args: string)   -- called with the remaining argument string
---@param description? string
Macro:RegisterCommand(name, handler, description)
```

## Minimap button

`volvox.Minimap` (defined in `Interface/Minimap/Minimap.lua`), created during `volvox:Init()`:

* **Left click** — toggle the settings window (opens it when ready if the frame isn't built yet).
* **Right click** — dropdown menu: **Enable Bot** / **Disable Bot** (calls `volvox.Gatherer:Start()` / `volvox.Gatherer:Stop()`), **Settings**, **Hide Minimap Button** (persisted; restore via `/volvox minimap`), and **Close**.
* **Draggable** — position persists to the `MinimapButtonPosition` config key.

## Global status toggles

`Core/StatusToggles.lua` provides a shared on-screen icon bar with clickable toggles:

```lua theme={null}
---@param options table   -- must include `label` and `var`
---@return table|nil toggle
function volvox:AddGlobalToggle(options)
```

`options` fields:

| Field     | Purpose                                                       |
| --------- | ------------------------------------------------------------- |
| `label`   | Display label (required)                                      |
| `var`     | Unique persistence identifier (required)                      |
| `value`   | Initial state (default `false`)                               |
| `onClick` | Click handler                                                 |
| `tooltip` | Tooltip text                                                  |
| `icon`    | Texture path or spell id (falls back to a question mark icon) |

Behavior:

* Lazily creates the singleton `volvox.GlobalStatusFrame` (icon bar with a trailing settings gear button, drag/lock, hover styling) on first call. The frame is colored from `volvox.Theme`: background `bg0` at 0.85 alpha, enabled icons `accent`, disabled icons `muted` at 0.6, hover `bg2` at 0.9, borders and separators `border` at 0.9, and the lock icon tinted `success` (unlocked) / `danger` (locked).
* Returns `nil` if `label` or `var` is missing; returns the **existing** toggle if one with the same `var` already exists.
* Toggle state persists per-`var` in a **separate** JSON file, `scripts/LootRoute/DemonStatusFrame.json` (independent of [`volvox.Config`](/framework/configuration)), which also stores frame position and lock state and can read legacy `scripts/Gatherer/DemonStatusFrame.json` / `configs/Demon/DemonStatusFrame.json` files.