# Система уведомлений

MBSL реализует кастомную систему уведомлений (класс MBSL\_NotificationSystem), не связанную с системой уведомлений игры, отображаемую в правом верхнем углу экрана.

## Встроенные уведомления

Вместе с системой предоставляются два основных класса уведомлений - MBSL\_DefaultNotification и MBSL\_FormattedNotification. Эти классы используют стандартный для MBSL дизайн уведомлений, размер которого подстраивается под размер текста.

Основная разница между ними заключается в том, что DefaultNotification использует указанный текст как ключ локализации (см. [система локализации](/mbsl-docs/ui/sistema-lokalizacii.md)) напрямую для отображения заголовка/содержимого, в то время как FormattedNotification исполняет лямбда-функции (см. [лямбда-функции](broken://pages/FfNI00u9D9cDSzqeqext)), которые в качестве аргумента получают уже локализованную строку, что позволяет форматировать строки перед отображением.

Стандартные уведомления рекомендуется добавлять встроенными в систему уведомлений функциями:

```clike
static void AddDefaultNotification(string header, string content, float lifetime = DefaultNotificationLifetime, bool important = false);
static void AddFormattedNotification(string header, string content, MBSL_LambdaBase1<string, string> headerFormatter, MBSL_LambdaBase1<string, string> contentFormatter, float lifetime = DefaultNotificationLifetime, bool important = false);
```

Данные функции принимают следующие аргументы:

* header - заголовок уведомления. Может быть как текстом, так и ключом локализации.
* content - текст, содержащийся в уведомлении. Может быть как текстом, так и ключом локализации.
* lifetime - время отображения уведомления в секундах.
* important - является ли уведомление важным (см. [свойства уведомлений](#svoistva-uvedomlenii)).&#x20;
* headerFormatter - лямбда-функция для форматирования заголовка. В качестве аргумента получает уже локализованную строку. Может быть равен null, тогда заголовок не будет форматироваться перед отображением.
* contentFormatter - лямбда-функция для форматирования текста уведомления. В качестве аргумента получает уже локализованную строку. Может быть равен null, тогда текст не будет форматироваться перед отображением.

## Кастомные уведомления

***В лейауте уведомления позиция корневого элемента должна задаваться относительно левого верхнего угла, чтобы уведомление отображалось корректно.***

Система уведомлений также позволяет создавать уведомления, использующие другой дизайн, анимацию и т.д. Для этого необходимо реализовать класс уведомления, наследующий класс MBSL\_NotificationBase (наследующий MBSL\_WidgetGroup - см. [группа виджетов](/mbsl-docs/ui/gruppa-vidzhetov.md)), приведённый ниже:

```clike
class MBSL_NotificationBase : MBSL_WidgetGroup
{
	protected bool _Important;
	protected float _Lifetime;
	
	protected void MBSL_NotificationBase( bool important, float lifetime )
	{
		_Important = important;
		_Lifetime = lifetime;
	}
	
	bool IsImportant() { return _Important; }
	float GetLifetime() { return _Lifetime; }
	
	bool UpdateAppear(float timeslice) { return true; }
	bool UpdateDisappear(float timeslice) { return true; }
	void UpdateDisplay(float timeslice) {}
}
```

### Свойства уведомлений

Каждое уведомления обладает двумя основными свойствами, получаемыми системой методами IsImportant и GetLifetime:

* lifetime - время отображения уведомления в секундах.
* important - является ли уведомление важным. Важные уведомления гарантированно остаются на экране, пока не закончится их время отображения. Неважные же уведомления могут быть убраны с экрана до завершения их времени отображения, если на экране не хватает места для новых уведомлений (при этом для неважных уведомлений будут полностью выполнены анимации появления и исчезновения). Важными рекомендуется помечать лишь критически-важные уведомления, информация которых может сильно повлиять на игровой процесс, чтобы не задерживать очередь уведомлений.

### Анимации

***Система уведомлений не анимирует уведомления, ответственность за анимацию лежит на самом уведомлении.***

***В процессе анимации важно сохранять текущую вертикальную позицию (y) уведомления и его высоту, т.к. система уведомлений сама управляет вертикальной позицией, а высоту сохраняет и использует для внутренних вычислений.***

Для реализации анимаций система уведомлений вызывает на уведомлении 3 метода - UpdateAppear, UpdateDisplay, UpdateDisappear. Данные методы в качестве аргумента получают timeslice - время между предыдущим и предпредыдущим кадрами игры (методы вызываются на каждом Update, подробнее об update-loop в игровых движках можно найти в интернете).  Каждый метод отвечает за свою часть анимации, и эти методы не вызываются одновременно:

Метод UpdateAppear отвечает за анимацию появления. Он начинает вызываться, как только уведомление появляется на экране, и будет повторно вызываться в каждом последующем кадре, пока он возвращает true. Как только этот метод вернёт false, система считает, что уведомление завершило свою анимацию появления, и переходит к этапу отображения. Хотя система не имеет строгих ограничений по длительности этапа, рекомендуется не превышать значение константы MBSL\_NotificationSystem.DefaultNotificationAppearTime для времени появления уведомления.

Метод UpdateDisplay отвечает за анимацию во время отображения. Он начинает вызываться, как только уведомление завершает анимацию появления, и повторно вызывается в каждом последующем кадре, пока не пройдёт время отображения уведомления (или система не решит освободить место, досрочно убрав неважное уведомление).

Метод UpdateDisappear отвечает за анимацию исчезновения. Он начинает вызываться, как только проходит время отображения (или система решает досрочно убрать уведомление), и будет повторно вызываться в каждом последующем кадре, пока он возвращает true. Как только этот метод вернёт false, система считает, что уведомление завершило свою анимацию исчезновения, и убирает его с экрана. Хотя система не имеет строгих ограничений по длительности этапа, рекомендуется не превышать значение константы MBSL\_NotificationSystem.DefaultNotificationDisappearTime для времени исчезновения уведомления.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://workshop-guide.magicbyte.ru/mbsl-docs/ui/sistema-uvedomlenii.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.