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

# Events

> volvox.EventHandler — the game and combat-log event dispatcher.

`volvox.EventHandler` (defined in `Hooks/CombatLogReader.lua`) is a singleton dispatcher for normal game events and combat-log sub-events. Handler errors are isolated with `pcall` and reported via `volvox:LogError`, throttled per event name to once per 5 seconds.

## Combat-log sub-events

```lua theme={null}
---@param event string        -- e.g. "SPELL_CAST_SUCCESS"
---@param handler fun(eventData: table)
EventHandler:RegisterEvent(event, handler)
```

The handler receives a formatted `eventData` table:

```lua theme={null}
{
  timestamp  = ...,
  event      = ...,   -- the sub-event name
  hideCaster = ...,
  source = { guid = ..., name = ..., flags = ..., raidFlags = ... },
  dest   = { guid = ..., name = ..., flags = ..., raidFlags = ... },
  params = { ... },   -- CLEU fields 12–30
}
```

Combat-log data is fetched through `volvox.GetCombatLogEventInfo()` (a secret-unwrapping wrapper from [`Util/Secure.lua`](/framework/utilities)).

## Normal game events

```lua theme={null}
---@param event string        -- e.g. "PLAYER_ENTERING_WORLD"
---@param handler fun(...)
EventHandler:RegisterNormalEvent(event, handler)
```

The handler receives the event's payload arguments. The event is registered on the frame at first subscription. `UnregisterNormalEvent(event, handler)` removes the first matching handler and unregisters the frame event when the last handler is gone.

## Raw combat log

```lua theme={null}
---@param handler fun(...)    -- up to 30 raw CLEU return values
EventHandler:RegisterRawCombatLog(handler)
EventHandler:UnregisterRawCombatLog(handler)
```

Raw handlers run **before** formatted per-subevent handlers.

## Lifecycle

| Signature                                   | Behavior                                                                                                                                                                                  |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EventHandler:Enable()`                     | Creates the event frame, registers `COMBAT_LOG_EVENT_UNFILTERED` plus queued normal events, installs the OnEvent script. Idempotent — called at file load and again from `volvox:Init()`. |
| `EventHandler:Disable()`                    | Unregisters all events and clears the OnEvent script. Idempotent.                                                                                                                         |
| `EventHandler:AddFilter(event, filterFunc)` | Stores a filter predicate per event.                                                                                                                                                      |

## Example

```lua theme={null}
volvox.EventHandler:RegisterEvent("SPELL_CAST_SUCCESS", function(eventData)
  if eventData.source.guid == UnitGUID("player") then
    volvox:LogInfo("Cast: " .. tostring(eventData.params[2]))
  end
end)

volvox.EventHandler:RegisterNormalEvent("PLAYER_ENTERING_WORLD", function(isLogin, isReload)
  volvox:LogInfo("Entered world")
end)
```