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

# Runtime

> volvox:Init(), the OnTick/OnUpdate loops, tick modes, and callback registration.

`Main.lua` loads last and drives the runtime. It builds two `OnUpdate` frames: **`UpdateFrame`** (per-frame) and **`OnTickFrame`** (throttled).

## volvox:Init()

```lua theme={null}
function volvox:Init()
```

Bootstraps the framework, called once at the bottom of `Main.lua`:

1. Initializes the minimap button (`volvox.Minimap:Initialize()`).
2. Creates the update/tick callback registries and seeds the 5-sample rolling tick-time window.
3. Creates the two driver frames via `volvox:InitializeFrames()` (this sets `volvox.isLoaded = true`).
4. Restores persisted module state with `volvox.Module:InitializeAll()` and enables `volvox.EventHandler`.

## Tick modes

The tick loop's throttle is controlled by two config keys:

| Key                | Default     | Behavior                                                                                                                                                                  |
| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `general.tickmode` | `"Dynamic"` | `"Dynamic"`: a tick fires when the elapsed time reaches `volvox.minimumTickTime` (`math.max(0.1, 1 / GetFramerate())`). Any other value (Fixed): uses `general.tickrate`. |
| `general.tickrate` | `0.1`       | Fixed tick interval in seconds                                                                                                                                            |

Both are editable on the built-in **General** settings page. Each tick also processes deferred module callbacks (`volvox.Module:ProcessPendingCallbacks()`).

## Registering callbacks

```lua theme={null}
---@param callback fun(elapsed: number)
---@param enabled? boolean
---@return number id
function volvox:OnTick(callback, enabled)
function volvox:OnUpdate(callback, enabled)
```

* `OnUpdate` callbacks run **every frame**; `OnTick` callbacks run at the throttled tick rate.
* Both return a numeric id for later removal. Passing `enabled = false` registers the callback in a disabled state.

<Note>
  Tick callbacks receive the **rolling average tick delta** (a 5-sample average), not the raw elapsed time.
</Note>

```lua theme={null}
---@param id number
---@param isUpdate? boolean
---@return boolean success
function volvox:RemoveCallback(id, isUpdate)
```

Removes a callback by id. Pass `isUpdate = true` for callbacks registered with `OnUpdate`; `false`/`nil` searches the tick list.

### Example

```lua theme={null}
local id = volvox:OnTick(function(elapsed)
  -- throttled work
end)

-- later
volvox:RemoveCallback(id)
```

## Other members defined in Main.lua

| Member                                                                            | Purpose                                                                             |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `volvox.FRAMEWORK_BUILD`                                                          | Build identifier string, logged at startup                                          |
| `volvox:IsGathererEnabled()`                                                      | `true` when the Gatherer module is enabled and global `State` is not `PAUSE`/`DEAD` |
| `volvox:ExecuteUpdateCallbacks(elapsed)` / `volvox:ExecuteTickCallbacks(elapsed)` | Internal loop plumbing                                                              |
| `volvox:CalculateAverageTickTime()` / `volvox:UpdateTickTime()`                   | Maintain the 5-sample rolling tick average                                          |

`Main.lua` also schedules a deferred GUI bring-up (\~0.5 s after load) that restores the LootRoute settings category and initializes the settings window.