Alerts (alerts)

No permission required

Coordinates on-screen alert playback across addons (donations, subscriptions, and similar overlays). A donation platform addon reports when its alert starts and ends; other addons (for example a music player) can pause themselves while any alert is playing.

This API does not render UI in StreamKit+. It only shares a global “is any alert playing?” flag between addon workers.

Concepts

Term Meaning
Producer Addon that displays an alert — calls alerts.started() / alerts.ended()
Consumer Addon that reacts — calls alerts.isActive() and/or alerts.onChange(...)
Global active true while at least one alert is in progress from any addon

Counts are reference-counted per addon: call ended() once for each started(). Intermediate changes (1→2 or 2→1 active alerts) do not notify subscribers — only the edges 0 → 1+ and → 0 do.

alerts.started()

Marks that this addon began displaying an on-screen alert.

alerts.started();
// … play donation / sub alert …
alerts.ended();

alerts.ended()

Marks that this addon finished one alert. Safe to call when the count is already zero (no-op).

alerts.ended();

alerts.isActive()

Returns whether any addon currently reports an active alert.

const res = await alerts.isActive();
if (res.success && res.active) {
  // pause music, hide HUD, etc.
}

Returns { success: true, active: boolean }.

alerts.onChange(cb)

Subscribes to global alert-display state changes. Returns { Destroy } to unsubscribe.

Payload When
{ active: true } First alert started anywhere (was idle → now playing)
{ active: false } Last alert finished (all addons idle)
const sub = alerts.onChange(({ active }) => {
  if (active) {
    pauseMusic();
  } else {
    resumeMusic();
  }
});

// Optional: sync current state on load
const state = await alerts.isActive();
if (state.success && state.active) {
  pauseMusic();
}

// later
sub.Destroy();

onChange does not fire with the current value at subscribe time — call isActive() if you need the initial state.

Lifecycle cleanup

When an addon is disabled, uninstalled, reloaded (api.restart() / settings restart), or stopped after a crash loop, StreamKit+ clears every active alert attributed to that addon.

If that clearance makes the global flag go from active → inactive, all other running addons receive { active: false } through onChange.

Producers do not need to call ended() during addon:prepare-stop for correctness (the host clears the counts), but calling ended() before stop is still fine.

Full example: donation producer + music consumer

// Donation / alert platform addon
events.On('onDonationAlert', async ({ body }) => {
  alerts.started();
  try {
    await playAlertMedia(body);
  } finally {
    alerts.ended();
  }
});
// Music player addon
let pausedForAlert = false;

alerts.onChange(({ active }) => {
  if (active && !pausedForAlert) {
    pausedForAlert = true;
    pausePlayback();
  } else if (!active && pausedForAlert) {
    pausedForAlert = false;
    resumePlayback();
  }
});