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

# Modules

> volvox.Module — the base class every feature registers through.

Features register as modules with `volvox.Module` (defined in `Module/Module.lua`). Enabling a module wires its `OnPulse(elapsed)` into the frame loop and persists the state under `modules.<name>`.

## Creating a module

```lua theme={null}
---@param name string The name of the module
---@param updateType? "tick"|"update"|"none" Whether to use OnTick or OnUpdate frame or none
---@return Module
function Module:New(name, updateType)
```

* `updateType` defaults to `"tick"`. Use `"update"` for per-frame work and `"none"` for modules that drive themselves (like the Gatherer's `C_Timer` loops).
* The persistence key is `configKey = "modules." .. string.lower(name)` (e.g. Gatherer → `modules.gatherer`).
* The module is registered in `Module.Registry`; if a persisted enabled state exists and is truthy, `Enable()` is called immediately.

```lua theme={null}
local MyFeature = volvox.Module:New("MyFeature", "tick")

function MyFeature:OnEnable()
  volvox:LogSuccess("MyFeature enabled")
end

function MyFeature:OnPulse(elapsed)
  -- runs every tick while enabled
end

function MyFeature:OnDisable()
  volvox:LogInfo("MyFeature disabled")
end
```

## Lifecycle hooks

Optional overrides with no base implementations:

| Hook                     | Called                                                          |
| ------------------------ | --------------------------------------------------------------- |
| `OnEnable(self)`         | After `Enable()` sets state and persists it                     |
| `OnDisable(self)`        | After `Disable()` sets state and persists it                    |
| `OnPulse(self, elapsed)` | Every tick (`"tick"`) or every frame (`"update"`) while enabled |

## Enable and disable

```lua theme={null}
function Module:Enable()
```

No-op if already enabled or the framework hasn't finished loading (`volvox.isLoaded`). Sets `enabled = true`, persists `Config:Write(configKey, true)`, calls `OnEnable`, then registers the `OnPulse` driver via `volvox:OnTick` or `volvox:OnUpdate` (unless `updateType == "none"`). If `volvox.OnUpdate` isn't available yet, the callback is queued into `PendingCallbacks` and registered later by the tick loop.

```lua theme={null}
function Module:Disable()
```

No-op if not enabled. Sets `enabled = false`, persists the state, calls `OnDisable`, and removes the registered callback.

<Note>
  There is no `Toggle` or `IsEnabled` method — callers check the `module.enabled` field directly.
</Note>

## Registry and settings

| Signature                                                 | Behavior                                                                                                                          |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Module:GetRegisteredModules()` → `table<string, Module>` | Returns the registry                                                                                                              |
| `Module:GetModule(name)` → `Module\|nil`                  | Registry lookup by name                                                                                                           |
| `Module:EnableAll()` / `Module:DisableAll()`              | Enable/disable every registered module                                                                                            |
| `Module:PrintStatus()`                                    | Logs each module's enabled state and updateType                                                                                   |
| `Module:SetSetting(key, value)`                           | Stores in the instance's in-memory `settings` table (not persisted; the Gatherer overrides this to write through `volvox.Config`) |
| `Module:GetSetting(key, default)`                         | Returns `settings[key]` or `default`                                                                                              |
| `Module:ProcessPendingCallbacks()`                        | Registers deferred OnUpdate callbacks once the runtime exists; called from the tick loop                                          |
| `Module:InitializeAll()`                                  | Restores every registered module to its persisted enabled state; called from `volvox:Init()`                                      |

Modules can be toggled in-game from the built-in **Modules** settings page.