Notification System README

Зачем нужна эта система

Система уведомлений нужна для того, чтобы разные скрипты могли показывать единые, аккуратные и управляемые уведомления через один общий менеджер, а не рисовать каждый свое окно или спамить чат.

Она решает сразу несколько задач:

• дает единый внешний вид уведомлений для всех скриптов;
• позволяет отправлять уведомления из разных скриптов в одно место;
• хранит историю уведомлений в рамках текущей сессии;
• поддерживает action-кнопки, которые возвращают событие обратно в нужный скрипт;
• избавляет рабочие скрипты от своей собственной UI-логики для toast-уведомлений.

Проще говоря: скрипт-источник только сообщает "покажи уведомление", а всем отображением, временем жизни, историей и интерактивными кнопками занимается NotificationManager.lua.

Из чего состоит система

• NotificationManager.lua
  Основной менеджер уведомлений. Показывает toast-уведомления, хранит историю текущей сессии, следит за временем жизни уведомлений и обрабатывает очередь.

• lib/session_notifications.lua
  Общая библиотека, через которую обычные скрипты работают с системой: проверяют состояние, запускают менеджер, отправляют уведомления и принимают action-callback.

• NotificationProducerExample.lua
  Минимальный пример скрипта-отправителя.

• NOTIFICATION_SYSTEM_USAGE.md
  Практическая инструкция по API и интеграции.

Как это работает

1. Менеджер поднимает сессию

Когда запускается NotificationManager.lua, он:

• создает новую сессию уведомлений;
• записывает данные о текущем runtime;
• начинает регулярно обновлять heartbeat;
• начинает читать очередь уведомлений из файла;
• показывает активные уведомления и ведет историю.

Это значит, что менеджер является центром текущей сессии.

2. Обычный скрипт подключает библиотеку

Обычный скрипт использует require('session_notifications') или require('lib.session_notifications').

Через библиотеку он может:

• узнать, установлена ли система;
• проверить, запущен ли менеджер;
• проверить совместимость по версии;
• отправить уведомление безопасным способом;
• зарегистрировать action-кнопку;
• принимать нажатия на action обратно в свой скрипт.

3. Скрипт вызывает notify.send(...)

Это основной и рекомендуемый способ отправки.

notify.send(...):

• проверяет наличие библиотеки;
• проверяет наличие менеджера;
• проверяет минимально требуемую версию;
• при необходимости пытается загрузить менеджер локально;
• если все в порядке, пишет уведомление в общую очередь.

Если система не готова, скрипт получает ошибку.

4. Менеджер читает очередь и показывает toast

Менеджер регулярно опрашивает очередь уведомлений и забирает только те записи, которые относятся к текущей сессии.

После этого он:

• добавляет уведомление в активный список;
• отображает его на экране;
• закрывает по таймеру или вручную;
• переносит запись в историю текущей сессии.

5. Если у уведомления есть кнопка

Если в уведомлении задан action, менеджер рисует кнопку внутри toast.

При нажатии:

• менеджер пишет событие в отдельную action-очередь;
• целевой скрипт читает эту очередь через notify.process_actions();
• вызывается callback, который скрипт зарегистрировал через notify.register_action(...).

Важно: callback выполняется не в менеджере, а в том скрипте, который зарегистрировал действие.

Архитектура обмена

Система не использует сеть и не общается с внешним сервером. Это локальная файловая шина обмена между скриптами внутри одной игровой сессии.

Основные файлы лежат в config/session_notifications:

• state.json
  Данные активной сессии уведомлений.

• runtime.json
  Состояние запущенного менеджера, включая heartbeat и версию.

• queue.jsonl
  Очередь входящих уведомлений.

• actions.jsonl
  Очередь action-событий от нажатий на кнопки.

• cursors/
  Индивидуальные курсоры чтения action-очереди для скриптов.

Формат .jsonl выбран потому, что это простой append-only журнал: скрипты могут быстро дописывать новые события строками без сложной синхронизации.

Что умеет система

• обычные уведомления с авто-закрытием;
• sticky-уведомления;
• история уведомлений за текущую сессию;
• разные встроенные темы;
• частичное переопределение палитры;
• картинка в уведомлении;
• action-кнопка с callback в исходный скрипт;
• проверка статуса системы и версии.

Чем send отличается от push

notify.send(...):

• безопасный публичный вход;
• сначала проверяет готовность системы;
• подходит для обычных скриптов.

notify.push(...):

• пишет уведомление напрямую в очередь;
• не проверяет, запущен ли менеджер;
• полезен только там, где система уже точно готова.

Практическое правило простое: для обычного скрипта почти всегда нужен notify.send(...).

Как работает история

Менеджер хранит историю только в рамках текущей сессии.

В историю попадают уведомления со статусами:

• active;
• expired;
• dismissed;
• overflow.

overflow означает, что активных toast-уведомлений стало больше лимита, и самые старые были вытеснены из активного списка.

Ограничения системы

• Система не скачивает файлы автоматически.
• Система не обновляет библиотеку автоматически.
• Система не обновляет менеджер автоматически.
• Если библиотека или менеджер отсутствуют, их нужно установить вручную.
• Если версии несовместимы, файлы нужно обновить вручную.
• Для action-кнопок целевой скрипт обязан регулярно вызывать notify.process_actions().

Это сознательная архитектура: система максимально локальная, прозрачная и без скрытых сетевых действий.

Когда система особенно полезна

• когда в сборке несколько скриптов и всем нужны уведомления;
• когда не хочется засорять игровой чат служебными сообщениями;
• когда нужно показывать важные события заметно, но аккуратно;
• когда нужно дать пользователю кнопку действия прямо в уведомлении;
• когда хочется единый UX для всех вспомогательных скриптов.