Boss Encounter API

synq.boss is the read-only encounter API for rotations. It normalizes boss-mod events into encounter state and classifies curated spell timers as semantic mechanics such as raid damage, tank busters, movement, adds, interrupts, and dispels.

The current adapter is validated against BigWigs v424.7. Rotation code is provider-independent and does not access BigWigs, the encounter engine, or the mechanic analyzer directly.

No separate SYNQ setting is required. With the current adapter, BigWigs must be installed and enabled for timer data to be available.

Call syntax: Use dot syntax, such as synq.boss.TimeTo(...). These are namespace functions, not colon methods.

Quick Start

local boss = synq.boss
local mechanics = boss.mechanics

if boss.IsIncoming(mechanics.RAID_DAMAGE, 5) then
  -- Prepare a defensive or healing cooldown.
end

if boss.IsIncoming(mechanics.MOVEMENT, 2) then
  -- Avoid starting a long cast.
end

local tankBuster = boss.GetNext(mechanics.TANK_BUSTER)
if tankBuster then
  local remaining = boss.TimeTo(mechanics.TANK_BUSTER)
end

Mechanic Constants

Always use the constants instead of spelling mechanic strings manually.

Encounter State

GetEncounter

Returns a snapshot of the current encounter, or nil outside an encounter.

local encounter = synq.boss.GetEncounter()
if encounter then
  print(encounter.id, encounter.name, encounter.stage)
end

Returned fields:

GetStage

Returns the current encounter stage, or nil when no stage is known.

local stage = synq.boss.GetStage()

Timer Queries

GetTimer

Returns the next timer for a spell ID, including timers without a registered semantic mechanic. Returns nil when no matching timer exists.

local timer = synq.boss.GetTimer(1242515)
if timer then
  local remaining = timer.paused
    and timer.remaining
    or math.max(0, timer.expiresAt - synq.time)

  if remaining <= 5 then
    -- Spell is expected within 5 seconds.
  end
end

GetNext

Returns the next active timer matching a semantic mechanic, or nil.

local timer = synq.boss.GetNext(synq.boss.mechanics.ADDS)

TimeTo

Returns seconds until the next matching mechanic. Returns math.huge when no matching timer exists, so direct comparisons are safe.

if synq.boss.TimeTo(synq.boss.mechanics.TANK_BUSTER) <= 3 then
  -- Prepare mitigation.
end

IsIncoming

Returns whether the next matching mechanic occurs within the supplied number of seconds. Invalid or negative windows return false.

local incoming = synq.boss.IsIncoming(
  synq.boss.mechanics.INTERRUPT,
  2
)

GetUpcoming

Returns analyzed timers occurring within the supplied number of seconds, sorted from soonest to latest. Unknown raw timers are excluded; query those with GetTimer(spellID).

local upcoming = synq.boss.GetUpcoming(10)
for index = 1, #upcoming do
  local timer = upcoming[index]
  local remaining = math.max(0, timer.expiresAt - synq.time)
  print(timer.primaryMechanic, remaining)
end

Timer Object

All timer query functions return a snapshot. Changing it does not change encounter state.

Behavior and Limits

• Encounter state, stages, timer expiry, pause, resume, and reset are owned by the encounter engine.
• Only curated spell rules receive semantic classifications. Unknown timers remain queryable by spell ID.
• Provider selection uses priority and failover. The selected provider remains pinned during an active encounter while available.
• Integration is event-driven. It does not poll BigWigs bars or frames.
• The API does not display alerts, cast spells, move, target, or control BigWigs UI and settings.

Framework-Only Extension API

synq.boss.internal is reserved for framework modules. Rotations must not register providers, mechanics, or subscribers.

RegisterMechanics

Registers curated spell-to-mechanic rules for an encounter. The primary mechanic must also appear in mechanics. Optional stage and count fields can narrow a rule to one occurrence.

synq.boss.internal.RegisterMechanics(3182, {
  {
    spellID = 1242515,
    mechanics = {
      synq.boss.mechanics.RAID_DAMAGE,
    },
    primaryMechanic = synq.boss.mechanics.RAID_DAMAGE,
  },
})

RegisterProvider

Registers a normalized encounter provider. id and Start are required. priority, IsAvailable, and Stop are optional.

local provider = {
  id = "native",
  priority = 50,
}

function provider:IsAvailable()
  return true
end

function provider:Start(emit)
  self.emit = emit
  return true
end

function provider:Stop()
  self.emit = nil
end

synq.boss.internal.RegisterProvider(provider)

Providers send normalized events through the emit callback passed to Start:

self.emit({
  type = "timer_start",
  timerID = "native|example|1242515",
  encounterID = 3182,
  moduleID = "example",
  spellID = 1242515,
  label = "Voidlight Convergence",
  duration = 12,
  timerType = "cooldown",
})

RefreshProviders

Re-evaluates provider availability and priority.

synq.boss.internal.RefreshProviders()

Subscribe

Subscribes a framework callback to normalized encounter changes. Returns an unsubscribe function.

local unsubscribe = synq.boss.internal.Subscribe(function(change)
  print(change.type, change.timer, change.encounter)
end)

unsubscribe()

Possible change types include provider changes, encounter lifecycle changes, stage changes, timer changes, and resets.

Next: Browse Debug Commands for inspecting framework state.