Skip to main content

​
The runtime contract

Every Lua file in the repository is loaded in-game by WGG and starts with: 
local WGG, volvox = ...
  • WGG is the unlocker API (object scanning and properties, position and movement, navigation, protected calls, tracelines, filesystem, HTTP, JSON, encryption).
  • volvox is the shared framework table — the only channel for cross-file shared state that isn’t a plain global.
There is no compiler, test runner, or standalone Lua interpreter. “Running” means loading the addon in-game through WGG.

​
Authoritative references

Use the documentation source that owns each part of the runtime:
  • WGG API: WGG documentation for unlocker calls such as object access, movement, navigation, protected calls, tracelines, files, HTTP, JSON, and encryption.
  • World of Warcraft API: Warcraft Wiki for WoW API functions and events, including exact namespaces, parameters, return values, availability, and restrictions.
  • Game data IDs: Wowhead for numeric item, GameObject, spell, NPC, quest, zone, area, faction, and profession IDs.
Never invent an API signature or numeric game-data ID. If the relevant authoritative source is unreachable or does not cover the requested API or entity, stop and ask for clarification rather than guessing.

​
Load order

loadorder.json at the repository root is the manifest: module names without .lua, in the exact order WGG loads them. Order is load-bearing — a file may only reference volvox.* members and globals defined by files above it.
Adding a .lua file requires adding it to loadorder.json at the correct position, or it never loads.
The layering, from first to last: 
Libs/  →  Util/ + Hooks/ + Module/ + Core/  →  Interface/  →  Gatherer/  →  _SingleButtonAssistant  →  Main
One deliberate exception within the middle layers: Interface/Theme.lua is a foundational cross-cutting dependency that loads between Module/Module and Core/StatusToggles, so volvox.Theme exists before every GUI consumer (including Core/StatusToggles.lua). The remaining interface files load after the core framework. Main.lua loads last and calls volvox:Init() to start the runtime loops.

​
Load-guard pattern

Files guard against double-execution with a flag on volvox: 
if volvox.GathererXxxLoaded then return end
volvox.GathererXxxLoaded = true

​
Framework services

The root files (everything outside Gatherer/) provide the services the bot builds on:
ServiceProvided byReference
Runtime loops (OnTick / OnUpdate)Main.luaRuntime
volvox.Module base classModule/Module.luaModules
volvox.Config persistenceUtil/Config.luaConfiguration
volvox.EventHandler dispatcherHooks/CombatLogReader.luaEvents
volvox.GuiBuilder settings DSLInterface/GuiBuilder.luaGUI builder
Theme, settings window, minimap, toggles, slash commandsInterface/, Core/Interface
Logging (volvox:Logger and helpers)Remote/_VolvoxLoader.lua (reference only)Logging
API resolution and secret unwrappingUtil/Api.lua, Util/Secure.luaUtilities

​
Repository map

PathPurpose
loadorder.jsonLoad manifest — module names (no .lua) in load order
Main.luaBootstraps the runtime via volvox:Init(); loads last
Libs/Vendored third-party libs (load first): LibStub, AceLocale-3.0, StdUi ("volvoxStdUi"), !LibUIDropDownMenu
Util/Api.luavolvox.ResolveApi / volvox.ResolveApiFunction — WGG-first API resolution
Util/Config.luavolvox.Config persistence layer
Util/Secure.luavolvox.UnwrapSecret and friends — unwrap WoW “secret value” protections
Core/Macro.lua/volvox slash commands and volvox.OpenSettings()
Hooks/CombatLogReader.luavolvox.EventHandler — event dispatcher
Module/Module.luavolvox.Module base class
Interface/Theme.luavolvox.Theme — foundational shared palette, font, spacing, size tokens, and color helpers (:Get, :Table, :Hex)
Core/StatusToggles.luaStatus frame + volvox:AddGlobalToggle
Interface/Sidebar.luavolvox.Sidebar — left navigation panel for the settings window
Interface/Default.luavolvox.Interface — main settings window
Interface/GuiBuilder.luavolvox.GuiBuilder — declarative settings-page DSL
Interface/Minimap/Minimap.luaMinimap button + dropdown
Interface/Layout/Built-in “General” and “Modules” settings pages
Remote/_VolvoxLoader.luaProduction remote loader and logger reference; not part of the root manifest
scripts/Local verification helpers (verify.sh, core-concat.sh, changelog-release.sh)
Gatherer/The bot layer — see Gatherer overview

​
WGG call rules

When touching any unlocker call, the codebase follows three rules:
  1. Prefer the documented WGG.* form. If the WGG docs expose a capability as WGG.Foo, call WGG.Foo even though a bare global (e.g. ReadFile, JsonEncode) may also work.
  2. Flag bare globals; don’t silently extend them. Existing code uses some bare globals; new or modified work switches to the documented WGG.* form.
  3. Handle sentinel returns. WGG functions may return 0, false, nil, or empty strings on failure. Check before driving movement, combat, file I/O, HTTP, or route state.
The volvox.ResolveApiFunction helper exists precisely for cases where an API is exposed under multiple candidate names.