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

# Logging

> volvox:Logger, per-level helpers, and limited bootstrap fallbacks.

In framework-loaded code, route user-facing output through `volvox:Logger(message, msgType)` or one of the per-level helpers. Bootstrap-only files may fall back to `print` before `volvox` is available. The logger (defined in `Remote/_VolvoxLoader.lua`) renders a colored `[Volvox][TYPE]:` prefix in chat.

## volvox:Logger

```lua theme={null}
---@param message string
---@param msgType string|nil   -- defaults to "text"
function volvox:Logger(message, msgType)
```

Supported `msgType` values:

| Type                          | Color         | Use for            |
| ----------------------------- | ------------- | ------------------ |
| `"text"` (default)            | white         | plain output       |
| `"error"`                     | orange-red    | failures           |
| `"success"`                   | lime green    | completed actions  |
| `"warning"`                   | yellow        | recoverable issues |
| `"info"`                      | yellow        | status             |
| `"debug"`                     | purple        | diagnostics        |
| `"m"` / `"y"` / `"t"` / `"h"` | theme accents | themed output      |

An unknown `msgType` falls back to the default text color.

## Per-level helpers

All are colon methods delegating to `Logger`:

| Helper                       | Equivalent                   | Use for            |
| ---------------------------- | ---------------------------- | ------------------ |
| `volvox:LogError(message)`   | `Logger(message, "error")`   | failures           |
| `volvox:LogWarning(message)` | `Logger(message, "warning")` | recoverable issues |
| `volvox:LogSuccess(message)` | `Logger(message, "success")` | completed actions  |
| `volvox:LogInfo(message)`    | `Logger(message, "info")`    | status             |
| `volvox:LogText(message)`    | `Logger(message, "text")`    | plain              |

<Warning>
  These are methods — call them with the colon (`volvox:LogDebug(...)`), not a dot.
</Warning>

## Debug logging

```lua theme={null}
function volvox:LogDebug(message, key, interval)
```

The single channel for verbose diagnostics. It prints **nothing unless the `gatherer.debug_scan` config is enabled** (check directly with `volvox:IsDebug()`).

* When a `key` is supplied, the log is throttled to once per `interval` seconds (default `1`) per key. **Always pass a stable `key`** for logs that can fire inside tick-rate loops.
* `volvox:ResetLogThrottle()` clears the throttle table — called, for example, when the `debug_scan` setting changes.

```lua theme={null}
-- fires at most once per 2 seconds regardless of tick rate
volvox:LogDebug("scan: " .. count .. " objects", "scan-count", 2)
```

## Rules of thumb

* Pick the level that matches intent: `LogError` for failures, `LogSuccess` for completed actions, `LogWarning` for recoverable issues, `LogInfo`/`LogText` for status, `LogDebug` for diagnostics.
* **Do not spam at tick rate** — use `LogDebug` with a `key`, log only on state change, and keep verbose output behind `gatherer.debug_scan`.
* In files that may load before the framework (for example `_SingleButtonAssistant.lua`), nil-guard the logger:

```lua theme={null}
if type(volvox) == "table" and type(volvox.Logger) == "function" then
  volvox:Logger(msg, msgType)
else
  print(msg)
end
```