Сповіщення (alerts)

Додатковий дозвіл не потрібен

Координація показу екранних сповіщень між аддонами (донати, підписки та подібні оверлеї). Аддон донатної платформи повідомляє, коли його сповіщення почалося і закінчилося; інші аддони (наприклад, музичний плеєр) можуть тимчасово призупиняти себе, поки грає хоча б одне сповіщення.

Цей API не малює UI у StreamKit+. Він лише передає між worker’ами глобальний прапорець «зараз десь іде сповіщення?».

Поняття

Термін Значення
Продюсер Аддон, який показує сповіщення — викликає alerts.started() / alerts.ended()
Конс’юмер Аддон, який реагує — викликає alerts.isActive() та/або alerts.onChange(...)
Глобально активно true, поки іде хоча б одне сповіщення від будь-якого аддона

Лічильники за посиланнями на аддон: на кожен started() потрібен один ended(). Проміжні зміни (1→2 або 2→1 активних сповіщень) не сповіщають підписників — лише переходи 0 → 1+ і → 0.

alerts.started()

Позначає, що цей аддон почав показувати екранне сповіщення.

alerts.started();
// … відтворення сповіщення про донат / підписку …
alerts.ended();

alerts.ended()

Позначає, що цей аддон закінчив одне сповіщення. Якщо активних сповіщень у аддона вже немає — виклик нічого не робить.

alerts.ended();

alerts.isActive()

Повертає, чи повідомляє зараз якийсь аддон про активне сповіщення.

const res = await alerts.isActive();
if (res.success && res.active) {
  // пауза музики, приховування HUD тощо
}

Повертає { success: true, active: boolean }.

alerts.onChange(cb)

Підписка на зміни глобального стану показу сповіщень. Повертає { Destroy } для відписки.

Payload Коли
{ active: true } Десь почалося перше сповіщення (було тихо → зараз грає)
{ active: false } Закінчилося останнє сповіщення (усі аддони вільні)
const sub = alerts.onChange(({ active }) => {
  if (active) {
    pauseMusic();
  } else {
    resumeMusic();
  }
});

// Опційно: синхронізувати поточний стан під час завантаження
const state = await alerts.isActive();
if (state.success && state.active) {
  pauseMusic();
}

// пізніше
sub.Destroy();

onChange не викликає колбек з поточним значенням у момент підписки — для початкового стану використовуйте isActive().

Очищення під час життєвого циклу

Коли аддон вимикають, видаляють, перезавантажують (api.restart() / перезапуск у налаштуваннях) або зупиняють після циклу падінь, StreamKit+ скидає всі активні сповіщення, приписані цьому аддону.

Якщо через це глобальний прапорець переходить з активного в неактивний, усі інші запущені аддони отримують { active: false } через onChange.

Продюсеру не обов’язково викликати ended() у addon:prepare-stop для коректності (хост сам очищає лічильники), але виклик ended() перед зупинкою допустимий.

Повний приклад: донатний продюсер + музичний конс’юмер

// Аддон донатної / алерт-платформи
events.On('onDonationAlert', async ({ body }) => {
  alerts.started();
  try {
    await playAlertMedia(body);
  } finally {
    alerts.ended();
  }
});
// Аддон музичного плеєра
let pausedForAlert = false;

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