Оповещения (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();
}
});