# LibCombatPulse-1.0
LibCombatPulse-1.0 is a lightweight WoW Retail library (LibStub-style) that acts as a **shared combat event bus**.
It lets addons publish and consume **normalized combat/progress/utility events** without requiring direct dependencies between addons.
This copy is shipped as a standalone addon (`LibCombatPulse-1.0`), and may also be embedded inside other addons.
## Key Features
- **Multiple consumers**
- Any addon can register one or more consumers via `NewConsumer()`.
- **Event filtering**
- Filter by confidence and by categories/kinds/direction/eventType.
- **Consumer safety**
- Events are shallow-copied per-consumer by default (`copyEvent=true`) to avoid cross-consumer mutation bugs.
- **Schema normalization**
- `Emit()` fills/normalizes basic fields like `kind` and `timestamp`.
## Library Versioning
- **MAJOR:** `LibCombatPulse-1.0`
- **MINOR:** `2`
LibStub will keep the newest MINOR version loaded.
## Loading / Access
```lua
local LibStub = _G.LibStub
local LCP = LibStub and LibStub:GetLibrary("LibCombatPulse-1.0", true)
if not (LCP and LCP.NewConsumer) then
return
end
```
## Registering a Consumer
```lua
local handle = LCP:NewConsumer("MyAddon", {
OnEvent = function(ev)
-- ev is a normalized event table
-- IMPORTANT: treat ev as read-only
end,
}, {
-- Options (all optional)
minConfidence = "LOW", -- LOW | MED | HIGH
enableCombat = true,
enableProgress = true,
enableInterrupts = true,
enableCooldowns = true,
-- Additional opt-in filters
-- kinds = { damage=true, heal=true, miss=true },
-- directions = { incoming=true, outgoing=true },
-- eventTypes = { OUTGOING_DAMAGE_COMBAT=true },
copyEvent = true, -- default true
})
-- Later
-- handle:Disable()
-- handle:Enable()
-- handle:Unregister()
```
## Event Contract (Practical)
LibCombatPulse does not enforce a strict schema, but the following fields are common.
### Required / Normalized
- `kind` *(string)*
- Examples: `damage`, `heal`, `miss`, `aura_gain`, `aura_fade`, `interrupt`, `cast_stop`, `cooldown_ready`, `xp`, `honor`, `reputation`
- `timestamp` *(number)*
- Seconds (from `GetTime()`), filled if missing.
### Common Optional Fields
- `eventType` *(string)*
- Original producer event type (example: `OUTGOING_DAMAGE_COMBAT`, `INCOMING_DAMAGE`, `COMBAT_TEXT_MISS`, `COOLDOWN_READY`).
- `direction` *(string)*
- Usually `incoming` or `outgoing`.
- `spellId` *(number)*
- `spellName` *(string)*
- `targetName` *(string)*
- `amount` *(number)*
- `amountText` *(string)*
- `confidence` *(string)*
- `LOW`, `MED`, `HIGH`.
### Kind-Specific Fields
- For `kind == "miss"`:
- `missType` *(string)* (ex: `DODGE`, `PARRY`, `BLOCK`, `MISS`)
- For `kind == "cooldown_ready"`:
- `method` *(string)* (producer-specific; ex: `BASE_CD`, `ACTIONBAR`, etc.)
- For combat damage/heal:
- `isCrit` *(boolean)*
- `isPeriodic` *(boolean)*
- `amountSource` *(string)* (producer-specific provenance)
## Producer Notes
LibCombatPulse itself is only a dispatcher. Producers (addons) decide what to emit and with what confidence.
If multiple addons emit events, consumers should rely on:
- `eventType`
- `direction`
- `confidence`
- producer-specific fields (like `amountSource`, `method`, etc.)
to select what they trust.
