Справочник тегов Suika3
====================

## Содержание

| Имя тега                    | Описание                                                          |
|-----------------------------|--------------------------------------------------------------------|
| [anime](#anime)             | Загружает и запускает файл анимации.                               |
| [bg](#bg)                   | Меняет фоновое изображение с эффектом плавного затухания.          |
| [bgm](#bgm)                 | Воспроизводит файл фоновой музыки (формат Ogg Vorbis).             |
| [callmacro](#callmacro)     | Вызывает определенный макрос.                                      |
| [ch](#ch)                   | Показывает или скрывает персонажей с детальными параметрами слоев. |
| [chapter](#chapter)         | Устанавливает имя главы.                                           |
| [choose](#choose)           | Показывает варианты и сохраняет выбор или переходит к метке.       |
| [click](#click)             | Ожидает щелчка пользователя.                                       |
| [config](#config)           | Устанавливает значение конфигурации для игровой системы.           |
| [defmacro](#defmacro)       | Начинает определение макроса.                                      |
| [else](#else)               | Часть ветки if/elseif для случая, когда условия не выполнены.      |
| [elseif](#elseif)           | Указывает дополнительное условие в ветке.                          |
| [endif](#endif)             | Завершает условную ветку.                                          |
| [endmacro](#endmacro)       | Завершает определение макроса.                                     |
| [goto](#goto)               | Переходит к указанному тегу-метке.                                 |
| [gui](#gui)                 | Показывает GUI из указанного файла.                                |
| [if](#if)                   | Разветвляет выполнение на основе указанного условия.               |
| [label](#label)             | Определяет метку для целей перехода.                               |
| [layer](#layer)             | Загружает/выгружает изображения или задает параметры для слоев.    |
| [load](#load)               | Загружает файл NovelML и может перейти к указанной метке.          |
| [move](#move)               | Анимирует слои персонажей в течение указанного времени.            |
| [pencil](#pencil)           | Рисует текст на слое.                                              |
| [returnmacro](#returnmacro) | Возвращается из выполнения макроса.                                |
| [se](#se)                   | Воспроизводит файл звукового эффекта (формат Ogg Vorbis).          |
| [set](#set)                 | Устанавливает значение переменной (все переменные считаются текстом). |
| [skip](#skip)               | Включает или отключает состояние пропуска.                         |
| [text](#text)               | Показывает текст в окне сообщения, при необходимости с именем.     |
| [video](#video)             | Воспроизводит видеофайл (поддерживаются настраиваемые параметры пропуска). |
| [volume](#volume)           | Устанавливает громкость звука для дорожек BGM, SE или Voice.       |
| [wait](#wait)               | Ждет указанное число секунд.                                       |

---

## `anime`

Запуск анимации

Тег `anime` загружает и выполняет определение анимации из файла.
Он позволяет создавать сложные визуальные эффекты, движения персонажей или циклические анимации окружения, выходящие за рамки простых переходов.

### Базовое использование

```
# Запуск синхронной анимации (ждет завершения)
[anime file="opening_effect.txt"]

# Запуск асинхронной циклической анимации
[anime file="sparkle.txt" async="true" register="my_loop"]

# Остановка зарегистрированной асинхронной анимации
[anime stop="true" register="my_loop"]
```

### Аргументы

| Аргумент      | Можно опустить | Описание                                              | Примечания                                                      |
|---------------|----------------|-------------------------------------------------------|-----------------------------------------------------------------|
| `file`        | Да             | Имя файла с определением анимации.                    | *Обязательно, если не используется `stop="true"`.              |
| `async`       | Да (`false`)   | Выполнять ли анимацию асинхронно.                     | Если `false`, сценарий ждет окончания анимации.                |
| `register`    | Да             | Уникальное имя для идентификации экземпляра анимации. | Требуется для управления или остановки асинхронных анимаций позже. |
| `stop`        | Да (`false`)   | Останавливает зарегистрированную анимацию, если `true`. | Требует аргумент `register`.                                    |
| `showsysbtn`  | Да (`true`)    | Показывать ли системные кнопки во время воспроизведения. | Действительно только для синхронных анимаций.                   |
| `showmsgbox`  | Да (`true`)    | Показывать ли окно сообщения во время воспроизведения.  | Действительно только для синхронных анимаций.                   |
| `shownamebox` | Да (`true`)    | Показывать ли окно имени во время воспроизведения.     | Действительно только для синхронных анимаций.                   |

### Советы

**Синхронно или асинхронно**:
* **Синхронно (`async="false"`)**: отлично подходит для кат-сцен, где вы хотите, чтобы игрок посмотрел анимацию до появления текста или выбора.
* **Асинхронно (`async="true"`)**: идеально для фоновых эффектов, таких как падающий снег или мерцающий свет, которые должны продолжаться по мере развития сюжета.

**Управление экземплярами**:
* Используя аргумент `register`, можно присвоить имя конкретной анимации.
* Так вы сообщаете движку, какую именно анимацию остановить при использовании `stop="true"`.

**Управление интерфейсом**:
* Используйте `showmsgbox="false"`, если анимация должна занимать весь экран, а диалоговое окно нужно временно скрыть для более чистого вида.

---

## `bg`

Изменение фона

Тег `bg` меняет фоновое изображение с плавным эффектом затухания.
Это основной способ задавать сцену в вашей визуальной новелле.

### Базовое использование

```
# Переход к background.png за 1.0 секунду
[bg file="background.png" time="1.0"]

# Плавный переход к черному экрану (удаляет фон)
[bg file="none" time="1.0"]
```

### Аргументы

| Аргумент   | Можно опустить | Описание                                      | Примечания                                                                 |
|------------|----------------|-----------------------------------------------|----------------------------------------------------------------------------|
| `file`     | Нет            | Имя файла нового фонового изображения.        | Установите `none`, чтобы удалить фон.                                      |
| `time`     | Да (`0`)       | Продолжительность эффекта затухания в секундах. | Значение по умолчанию `0.0` (мгновенное изменение).                        |
| `method`   | Да (`normal`)  | Метод/стиль затухания.                        | Выберите `normal`, `rule` или `melt`.                                      |
| `rule`     | Да             | Файл изображения rule для специальных переходов. | Требуется, когда `method` установлен в `rule` или `melt`.                  |
| `x`        | Да (`0`)       | Смещение изображения фона по оси X.           | Поддерживаются абсолютные значения (например, `100`) и относительные (например, `r100`). |
| `y`        | Да (`0`)       | Смещение изображения фона по оси Y.           | Поддерживаются абсолютные значения (например, `100`) и относительные (например, `r-100`). |
| `alpha`    | Да (`255`)     | Альфа-значение фонового изображения.          | `0` до `255`.                                                              |
| `clear`    | Да (`false`)   | Нужно ли скрывать персонажей.                 | Если `true`, все персонажи будут скрыты.                                   |

### Методы перехода (`method`)

Вы можете создавать разную атмосферу, выбирая подходящий стиль перехода:

| Тип      | Описание                                                                                                                          |
|----------|-----------------------------------------------------------------------------------------------------------------------------------|
| `normal` | Альфа-смешивание. Метод по умолчанию. Выполняет плавное перекрестное затухание между старым и новым изображением.                |
| `rule`   | 1-битный универсальный переход. Использует полутоновое изображение "rule" для определения порядка смены.                         |
| `melt`   | 8-битный универсальный переход. Похож на `rule`, но с мягкими размытыми краями на границе перехода, создавая эффект "таяния".   |

Для `rule` и `melt` изображение переключается пиксель за пикселем от самых темных областей карты rule к самым светлым.

### Советы

**Относительное позиционирование**:
* Если нужно немного сместить фон от текущей позиции, используйте префикс `r`.
* Например, `x="r50"` сдвигает изображение на 50 пикселей вправо от текущей координаты X.

**Что такое rule-изображение?**:
* Это полутоновое изображение, где черные области переключаются первыми, а белые - последними.
* Создавая собственные rule-изображения, можно получать эффекты вроде горизонтальных вытеснений, круговых раскрытий или даже более художественных узоров!

---

## `bgm`

Воспроизведение фоновой музыки

Тег `bgm` воспроизводит фоновый музыкальный трек.
Музыка - важный инструмент для создания настроения сцены, и она будет автоматически зацикливаться, пока не будет остановлена или заменена.

### Базовое использование

```
# Начать воспроизведение трека BGM
[bgm file="field_theme.ogg"]

# Остановить текущую BGM (используйте "none")
[bgm file="none"]
```

### Аргументы

| Аргумент | Можно опустить | Описание                        | Примечания                               |
|----------|----------------|---------------------------------|------------------------------------------|
| `file`   | Нет            | Имя файла музыки для воспроизведения. | Установите `none`, чтобы остановить текущую BGM. |
| `once`   | Да (`false`)   | Не зацикливать.                 |                                          |

### Советы

**Требуемый формат**:
* Для совместимости и производительности Suika3 требует, чтобы файлы BGM были в формате **Ogg Vorbis**.
* Частота дискретизации ДОЛЖНА быть **44 100 Гц**.

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

**Плавные переходы**:
* Если вы вызываете `[bgm]`, когда уже играет другой трек, движок обычно обрабатывает переход автоматически.
* Чтобы регулировать громкость музыки, используйте тег `[volume]`.

**Остановка музыки**:
* Когда сцена заканчивается или настроение меняется на тишину, не забудьте использовать `[bgm file="none"]`, чтобы дать ушам игрока передышку!

---

## `callmacro`

Вызов макроса

Тег `callmacro` выполняет ранее определенный макрос.
Он позволяет запускать определенную последовательность команд, например выходы персонажей или анимации интерфейса, много раз по всему сценарию без повторной записи исходного кода.

### Базовое использование

```
# Вызов макроса с именем "kaito_entrance"
[callmacro name="kaito_entrance"]

# Вызов макроса для конкретного перехода сцены
[callmacro name="fade_to_white"]
```

### Аргументы

| Аргумент | Можно опустить | Описание                               | Примечания                                              |
|----------|----------------|----------------------------------------|---------------------------------------------------------|
| `name`   | Нет            | Имя макроса, который нужно выполнить.  | Должно совпадать с именем, определенным тегом `[defmacro]`. |
| `file`   | Да             | Имя файла, где определен макрос.       | Опустите это, чтобы вызвать макрос внутри текущего файла. |

### Советы

**Эффективность**:
* Используя `[callmacro]`, можно сделать основной сценарий более сфокусированным и читаемым.
* Вместо 10 строк кода анимации вы увидите всего одну понятную команду.

**Порядок выполнения**:
* Когда движок доходит до `[callmacro]`, он немедленно переходит к определенному макросу, выполняет все теги внутри него, а затем автоматически возвращается к следующей строке после тега `[callmacro]`.

**Модульный дизайн**:
* Думайте о макросах как о "пользовательских тегах" для вашей игры.
* Если вы решите изменить, как персонаж входит в сцену, вам нужно будет обновить код только один раз в блоке `[defmacro]`, и каждый `[callmacro]` отразит это изменение!

---

## `ch`

Отображение персонажей

Тег `ch` показывает, скрывает или обновляет изображения персонажей на различных слоях.
Он позволяет детально управлять позиционированием, масштабированием и вращением нескольких персонажей и фона одновременно.

### Базовое использование

```
# Показать персонажа в центре
[ch center="chara001.png" time="1.0"]

# Показать нескольких персонажей с заданными позициями
[ch left="chara002.png" right="chara003.png" time="0.5"]

# Скрыть конкретного персонажа
[ch center="none" time="1.0"]
```

### Аргументы

| Аргумент  | Можно опустить | Описание                              | Примечания                                                 |
|-----------|----------------|---------------------------------------|------------------------------------------------------------|
| `time`    | Да (`0`)       | Продолжительность перехода в секундах. | Влияет на все изменения слоев внутри этого тега.          |
| `method`  | Да (`normal`)  | Метод/стиль затухания.                | `normal`, `rule` или `melt`.                              |
| `rule`    | Да             | Файл изображения rule для переходов.  | Требуется, когда `method` равен `rule` или `melt`.        |

#### Аргументы файлов слоев

Укажите имя файла, чтобы загрузить изображение в слой. Установите `none`, чтобы выгрузить (скрыть) изображение.

| Аргумент       | Описание                               |
|----------------|----------------------------------------|
| `bg`           | Фоновый слой.                           |
| `back`         | Персонаж заднего центра.               |
| `left`         | Левый персонаж.                        |
| `right`        | Правый персонаж.                       |
| `center`       | Центральный персонаж.                 |
| `left-center`  | Левый центральный персонаж.           |
| `right-center` | Промежуточный персонаж.               |
| `face`         | Лицевой персонаж.                      |

#### Аргументы параметров слоя

Каждый из слоев выше (например, `center`) можно настраивать с помощью следующих суффиксов (например, `center-x`, `center-rotate`).

| Суффикс     | Можно опустить | Описание               | Примечания                                                         |
|-------------|----------------|------------------------|--------------------------------------------------------------------|
| `-x`        | Да (`0`)       | Позиция по X.          | Поддерживаются абсолютные значения (например, `100`) и относительные (например, `r50`). |
| `-y`        | Да (`0`)       | Позиция по Y.          | Поддерживаются абсолютные значения (например, `100`) и относительные (например, `r-50`). |
| `-a`        | Да (`255`)     | Значение alpha (непрозрачность). | `0` (прозрачный) до `255` (непрозрачный).                          |
| `-scale-x`  | Да (`1.0`)     | Коэффициент масштабирования по X. | `1.0` - исходный размер. Поддерживает префикс `r`.              |
| `-scale-y`  | Да (`1.0`)     | Коэффициент масштабирования по Y. | `1.0` - исходный размер. Поддерживает префикс `r`.              |
| `-center-x` | Да (`0`)       | X-центр для вращения.  | Точка опоры для эффекта вращения.                                  |
| `-center-y` | Да (`0`)       | Y-центр для вращения.  | Точка опоры для эффекта вращения.                                  |
| `-rotate`   | Да (`0`)       | Вращение в градусах.   | Положительные значения - по часовой стрелке. Поддерживает префикс `r`. |
| `-dim`      | Да (`false`)   | Состояние затемнения.  | Если `true`, слой отображается на 50% темнее.                       |

### Советы

**Пакетные обновления**:
* Можно обновлять несколько персонажей и фон одновременно в одном теге `[ch]`, чтобы они анимировались идеально синхронно.

**Относительные преобразования**:
* Как и тег `bg`, все числовые параметры поддерживают префикс `r`.
* Например, `center-y="r-50"` поднимет центрального персонажа на 50 пикселей относительно его текущего положения.

---

## `chapter`

Установка имени главы

Тег `chapter` задает имя текущей главы.
Обычно это имя используется игровой системой для отображения прогресса в меню сохранения/загрузки или на игровом экране, помогая игрокам отслеживать ход истории.

### Базовое использование

```
# Задать имя главы в начале сюжетного фрагмента
[chapter name="Chapter 01: The Beginning"]

# Обновить имя главы по мере развития сюжета
[chapter name="Intermission: A Quiet Night"]
```

### Аргументы

| Аргумент | Можно опустить | Описание                         | Примечания                                                      |
|----------|----------------|----------------------------------|-----------------------------------------------------------------|
| `name`   | Нет            | Имя главы, которое нужно задать. | Эта строка будет сохранена в системных переменных игры.         |

### Советы

**Видимость данных сохранения**:
* Во многих конфигурациях Suika3 строка, которую вы задаете здесь, - это то, что отображается в слотах "Save" и "Load".
* Выберите имя, которое поможет игроку точно помнить, где он находится в сюжете!

**Последовательность**:
* Хорошая практика - вызывать тег `[chapter]` сразу после `[label]`, который начинает новую крупную сцену или главу.

**Обновление имен**:
* Вы можете вызывать `[chapter]` столько раз, сколько захотите.
* Каждый раз старое имя главы перезаписывается новым.

---

## `choose`

Показ вариантов выбора

Тег `choose` отображает до 8 интерактивных кнопок для игрока.
Он сохраняет текст выбранного варианта в переменной.

### Базовое использование

```
# Сохраняем выбор в переменную
[choose
    text1="Красная таблетка"
    text2="Зеленая таблетка"
    text3="Синяя таблетка"
    name="user_choice"
    value1="red"
    value2="green"
    value3="blue"
]
```

### Аргументы

| ????????         | ????? ???????? | ????????                                    | ??????????                                              |
|------------------|-----------|------------------------------------------------|--------------------------------------------------- |
| `text1`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text2`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text3`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text4`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text5`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text6`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text7`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text8`          | Yes       | Текст, отображаемый на каждой кнопке.          | Обычно требуется как минимум один вариант.        |
| `text<N>-locale` | Yes       | Текст, отображаемый на каждой кнопке. (localized) | Обычно требуется как минимум один вариант.        |
| `name`           | No        | Имя переменной, в которую сохраняется результат. | Сохраняет текст выбранного варианта.               |
| `value1`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `value2`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `value3`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `value4`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `value5`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `value6`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `value7`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `value8`         | Yes       | Значение, присваиваемое переменной результата.  | Обычно требуется как минимум один вариант.        |
| `time`           | Yes (`0`) | Таймер в секундах.                             | Если `0`, таймер не активируется.                 |

### Локализация

Например, если в ОС пользователя выбран японский язык, предпочтительнее `text1-ja`, а не `text1`.

| ???????      | ????                                 |
|-------------|------------------------------------------|
| -en         | Английский (резервный вариант)           |
| -en-us      | Английский (США)                          |
| -en-gb      | Английский (Великобритания)              |
| -en-au      | Английский (Австралия)                    |
| -en-nz      | Английский (Новая Зеландия)              |
| -fr         | Французский (резервный вариант)          |
| -fr-fr      | Французский (Франция)                    |
| -fr-ca      | Французский (Канада)                     |
| -es         | Испанский (Испания, резервный вариант)   |
| -es-la      | Испанский (Латинская Америка)            |
| -de         | Немецкий                                  |
| -it         | Итальянский                               |
| -ru         | Русский                                   |
| -el         | Греческий                                 |
| -zh         | Китайский (упрощенный)                    |
| -zh-tw      | Китайский (традиционный, Тайвань)        |
| -ja         | Японский                                  |
| (no suffix) | Резервный вариант (решение разработчика) |

Для всех английских локалей ОС, включая все регионы, в качестве
стандартного резервного варианта используется `-en`. Если в теге
указан более конкретный вариант, например `-en-gb`, и он лучше всего
соответствует региону пользователя, будет выбран именно он. То же
самое правило применяется к испанскому и французскому. Обратите
внимание, что для традиционного китайского нет резервного перехода к
упрощенному китайскому.

Например, если локаль пользователя `en-AU`, применяется следующий приоритет:
* 1. text1-en-au
* 2. text1-en
* 3. text1

Следующие варианты сейчас не поддерживаются, но планируется их поддержать.

| ???????      | ????                                 |
|-------------|------------------------------------------|
| -ko         | Корейский                                |
| -vi         | Вьетнамский                              |
| -id         | Индонезийский                            |
| -zh-hk      | Традиционный китайский (Гонконг)        |
| -pt         | Португальский (резервный вариант)        |
| -pt-br      | Португальский (Бразилия)                |
| -pl         | Польский                                 |
| -tr         | Турецкий                                 |
| -ta         | Тамильский                               |
| -te         | Телугу                                   |
| -kn         | Каннада                                  |
| -si         | Сингальский                              |
| -ar         | Арабский (RTL)                           |
| -fa         | Персидский (RTL)                         |

### Советы

**Логика ветвления**:
* Вы можете использовать тег `[if]`, чтобы проверять сохраненное значение и создавать сложные ветвления.

```
[choose
  name="var1"
  text1="Пойти в школу"
  text2="Пойти в больницу"
  value1="1"
  value2="2"]

[if lhs="${var1}" op="=" rhs="1"]
  # Школа.
[else]
  # Больница.
[endif]
```

**Сохранение переменных**:
* Поскольку все хранится как строка, помните, что даже числа вроде "100" внутренне сохраняются как текст.
* Логические теги Suika3, такие как `if`, умеют сравнивать такие строки.

---

## `set`

Установить переменную

Тег `set` присваивает значение имени переменной.
В Suika3 **все переменные обрабатываются как текстовые строки**, но их можно сравнивать численно в других тегах, например `[if]`.

### Базовое использование

```
# Присваиваем простой строковый текст переменной
[set name="player_name" value="Kaito"]

# Устанавливаем числоподобное значение (сохраняется как строка)
[set name="health" value="100"]

# Очищаем переменную, присваивая ей пустую строку
[set name="flag_event_01" value=""]

# Прибавляем 1 к var1.
[set name="var1" value1="${var1}" op="+" value2="1"]

```

### Аргументы

| ???????? | ????? ????????     | ????????                                 | ??????????                                                               |
|----------|---------------|---------------------------------------------|---------------------------------------------------------------------|
| `name`   | No            | Уникальное имя переменной.                  | Для лучшей совместимости используйте буквы, цифры и символы подчеркивания. |
| `value`  | Yes           | Содержимое, которое нужно сохранить в переменной. | Помните: все сохраняется как строка!                         |
| `value1` | Yes           | Первый операнд для кода операции.           |                                                                     |
| `value2` | Yes           | Второй операнд для кода операции.           |                                                                     |
| `op`     | Yes           | Код операции. (`+`, `-`, `*`, `/`, `//`, `%`) |                                                                     |
| `global` | Yes (`false`) | Сделать флаг глобальным.                    | Глобальные переменные используются для флагов достижений, например "Saw ED1".         |

### Советы

**Работа со строками**:
* Поскольку Suika3 считает все текстом, `value="100"` и `value="May"` внутри обрабатываются одинаково.
* Эти переменные можно использовать в других тегах (например, `text` или `if`) через синтаксис `${variable_name}`.

**Управление флагами**:
* Для игровых флагов, таких как "встретил героя", обычно используют `"true"` и `"false"` либо `"1"` и `"0"`.
* Последовательность важна! Если вы начали использовать `"1"`, придерживайтесь этого варианта, чтобы проверки `[if]` не путались.

**Именование переменных**:
* Избегайте пробелов и специальных символов в именах переменных. `my_variable` гораздо надежнее, чем `my variable!`.

---

## `click`

Ожидание клика

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

### Базовое использование

```
# Меняем фон, затем ждем клика игрока
[bg file="sunset.png" time="1.0"]
[click]

# После клика показываем персонажа
[ch center="chara01.png" time="1.0"]
```

### Аргументы

Этот тег не принимает аргументов.

| ???????? | ????? ???????? | ???????? | ??????????           |
|----------|-----------|-------------|-----------------|
| -        | -         | -           | -               |

### Советы

**Тайминг и темп**:
* Используйте `[click]`, когда хотите дать игроку время рассмотреть новый фон или выражение персонажа перед продолжением диалога.
* В отличие от тега `[text]`, который автоматически ждет клика после показа сообщения, `[click]` применяется для ручного управления потоком во время недиалоговых последовательностей.

**Визуальная обратная связь**:
* Когда сценарий доходит до тега `[click]`, игра остается неподвижной. Убедитесь, что у всех предыдущих анимаций, таких как `[bg]` или `[ch]`, задан параметр `time`, иначе экран может слишком резко показаться статичным.

**Для ожидания по времени:**
* Используйте `[wait]` для ожидания по времени.

---

## `goto`

Переход к метке

Тег `goto` немедленно переносит выполнение NovelML к указанной метке.
Это полезный инструмент для управления ходом истории, позволяющий пропускать фрагменты или возвращаться к предыдущим частям.

Обратите внимание, что небольшие ветвления следует реализовывать через `[if]`.

### Базовое использование

```
# Перейти к началу утренней сцены
[goto name="morning_start"]

# ... этот фрагмент сценария будет пропущен ...

[label name="morning_start"]
[text text="Солнце встает над горизонтом."]
```

### Аргументы

| ???????? | ????? ???????? | ????????                       | ??????????                                         |
|----------|-----------|-----------------------------------|-----------------------------------------------|
| `name`   | No        | Имя целевой метки для перехода.   | Должно совпадать с именем, заданным тегом `[label]`. |

### Советы

**Безусловный переход**:
* В отличие от `[if]`, `[goto]` всегда выполняет переход к целевой метке, как только движок доходит до тега.

**Управление потоком**:
* Используйте `[goto]` в конце ветвящейся дороги, чтобы вернуть историю на "общий" маршрут.
* Это также отлично подходит для создания циклов, например последовательности "Вернуться к заголовку", если сочетать тег с другой логикой.

**Между файлами?**:
* Помните, что `[goto]` обычно работает внутри текущего файла сценария.
* Если вам нужно перейти в совершенно другой файл, обратите внимание на тег `[load]`!

---

## `defmacro`

Определить макрос

Тег `defmacro` начинает определение макроса.
Макрос позволяет объединить несколько тегов и команд в один именованный блок, который можно повторно использовать во всем сценарии через тег `[callmacro]`.

### Базовое использование

```
# Определяем макрос для появления конкретного персонажа
[defmacro name="enter_kaito"]
    [ch center="kaito_smile.png" time="0.5"]
    [text name="Kaito" text="Привет! Я не заставил тебя ждать?"]
[endmacro]

# Позже в сценарии вызываем его одной строкой
[callmacro name="enter_kaito"]
```

### Аргументы

| ???????? | ????? ???????? | ????????                     | ??????????                                             |
|----------|-----------|---------------------------------|---------------------------------------------------|
| `name`   | No        | Уникальное имя этого макроса.   | Используется для идентификации макроса при последующем вызове. |

### Советы

**Закрытие определения**:
* Каждый `[defmacro]` должен сопровождаться тегом `[endmacro]`, который отмечает конец определения.

**Переиспользование кода**:
* Макросы отлично подходят для повторяющихся последовательностей, например для особых переходов интерфейса, визуальных настроек персонажей или сложных сочетаний звука и изображения.

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

**Вложенность и логика**:
* Внутрь макроса можно поместить почти любой другой тег, включая инструкции `[if]` и даже `[returnmacro]`, чтобы завершить макрос раньше при выполнении определенных условий.

---

## `gui`

Показ GUI

Тег `gui` загружает и отображает определение графического интерфейса пользователя (GUI) из указанного файла.
Он используется для показа меню, экранов заголовка или пользовательских панелей взаимодействия.

### Базовое использование

```
# Показать GUI главного меню
[gui file="main_menu.txt"]

# Показать пользовательский экран сохранения/загрузки
[gui file="save_screen.txt"]
```

### Аргументы

| ???????? | ????? ???????? | ????????                                 | ??????????                                               |
|----------|-----------|---------------------------------------------|-----------------------------------------------------|
| `file`   | No        | Имя файла с определением GUI для загрузки.  | Файл должен существовать в каталоге GUI проекта.    |

### Советы

**Определения GUI**:
* Аргумент `file` указывает на текстовый файл, который определяет расположение элементов, кнопок и действий вашего интерфейса.
* Эти файлы задают, где размещаются изображения и что происходит при взаимодействии пользователя, например переход к метке или выход из игры.

**Использование в потоке**:
* Обычно тег `[gui]` применяется для графического меню, например экрана заголовка.

**Настройка**:
* Поскольку GUI определяется во внешнем файле, вы можете создавать несколько вариантов оформления игры и переключаться между ними, просто вызывая разные файлы этим тегом.

---

## `label`

Определить метку

Тег `label` задает определенную точку в сценарии, на которую можно ссылаться командами перехода, такими как `[goto]` или `[load]`.
Он служит закладкой для навигации внутри вашей истории.

### Базовое использование

```
# Определяем метку для начала новой главы
[label name="chapter_01_start"]

# Используем команду перехода, чтобы достичь этой метки
[goto name="chapter_01_start"]
```

### Аргументы

| ???????? | ????? ???????? | ????????                     | ??????????                                                  |
|----------|-----------|---------------------------------|--------------------------------------------------------|
| `name`   | No        | Уникальное имя этой метки.      | Чувствительно к регистру. Не используйте пробелы или специальные символы. |

### Советы

**Управление навигацией**:
* Метки полезны для создания разветвленных маршрутов.
* Например, вы можете поставить `label` в начале раздела истории, чтобы сделать длинный переход.

**Уникальные имена**:
* Каждое имя метки внутри одного файла сценария должно быть уникальным.
* Если у вас есть две метки с одинаковым именем, движок может не понять, куда переходить, а это неудобно для всех!

**Организация**:
* Хорошая привычка - использовать описательные имена вроде `label_evening_park` вместо `label1`.
* Так вам (и мне!) будет гораздо проще позже читать сценарий и понимать, что происходит.

---

## `text`

Показ текста

Тег `text` отображает сообщение в окне сообщения.
Он может показывать основной диалог или повествование, а также при необходимости отображать имя персонажа в поле имени.

### Базовое использование

```
# Повествовательный стиль (имя не отображается)
[text text="Ветер выл среди деревьев."]

# Реплика персонажа
[text name="Keith" text="Я ждал тебя здесь, в этой маленькой комнате."]
```

### Аргументы

| ????????         | ????? ???????? | ????????                                      | ??????????                                            |
|------------------|-----------|--------------------------------------------------|--------------------------------------------------|
| `text`           | No        | Содержимое сообщения, которое нужно показать.   |                                                  |
| `text-<locale>`  | Yes       | Содержимое сообщения, которое нужно показать. (localized) |                                                  |
| `voice`          | Yes       | Файл голоса.                                     |                                                  |
| `voice-<locale>` | Yes       | Файл голоса. (localized)                         |                                                  |
| `name`           | Yes       | Имя персонажа, которое отображается в поле имени. | Если опущено, поле имени обычно скрывается.      |
| `action`         | Yes       | Для режима NVL и ручного показа/скрытия.         |                                                  |
| `space`          | Yes       | Для режима NVL.                                  |                                                  |

### Локализация

Например, если в ОС пользователя выбран японский язык, предпочтительнее `text-ja`, а не `text`.

| ???????      | ????                                 |
|-------------|------------------------------------------|
| -en         | Английский (резервный вариант)           |
| -en-us      | Английский (США)                          |
| -en-gb      | Английский (Великобритания)              |
| -en-au      | Английский (Австралия)                    |
| -en-nz      | Английский (Новая Зеландия)              |
| -fr         | Французский (резервный вариант)          |
| -fr-fr      | Французский (Франция)                    |
| -fr-ca      | Французский (Канада)                     |
| -es         | Испанский (Испания, резервный вариант)   |
| -es-es      | Испанский (Испания, резервный вариант)   |
| -es-la      | Испанский (Латинская Америка)            |
| -de         | Немецкий                                  |
| -it         | Итальянский                               |
| -ru         | Русский                                   |
| -el         | Греческий                                 |
| -zh-cn      | Китайский (упрощенный)                    |
| -zh-tw      | Китайский (традиционный, Тайвань)        |
| -ja         | Японский                                  |
| (no suffix) | Резервный вариант (решение разработчика) |

Для всех английских локалей ОС, включая все регионы, в качестве
стандартного резервного варианта используется `-en`. Если в теге
указан более конкретный вариант, например `-en-gb`, и он лучше всего
соответствует региону пользователя, будет выбран именно он. То же
самое правило применяется к испанскому и французскому. Обратите
внимание, что для традиционного китайского нет резервного перехода к
упрощенному китайскому.

Например, если локаль пользователя `en-GB`, применяется следующий приоритет:
* 1. text-en-gb
* 2. text-en
* 3. text

Следующие варианты сейчас не поддерживаются, но планируется их поддержать.

| ???????      | ????                                 |
|-------------|------------------------------------------|
| -ko         | Корейский                                |
| -vi         | Вьетнамский                              |
| -id         | Индонезийский                            |
| -zh-hk      | Традиционный китайский (Гонконг)        |
| -pt         | Португальский (резервный вариант)        |
| -pt-br      | Португальский (Бразилия)                |
| -pl         | Польский                                 |
| -tr         | Турецкий                                 |
| -ta         | Тамильский                               |
| -te         | Телугу                                   |
| -kn         | Каннада                                  |
| -si         | Сингальский                              |
| -ar         | Арабский (RTL)                           |
| -fa         | Персидский (RTL)                         |

### Действия

В теге `text` можно использовать специальные параметры.

```
# Очистить окно сообщения.
[text action="clear"]

# Очистить окно сообщения и показать его.
[text action="new"]

# Показать окно сообщения.
[text action="show"]

# Скрыть окно сообщения.
[text action="hide"]
```

### Режим NVL

Перейти в режим NVL можно, задав некоторые параметры конфигурации.

```
[text action="hide"]
[wait time="0.3"] # Ждем, пока окно сообщения скроется.
[config name="game.novel" value="true"]
[config name="msgbox.image" value="system/message/msgbox-nvl.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="0"]
[config name="msgbox.margin.line" value="60"]
[config name="namebox.enable" value="false"]
[config name="choose.box1.idle" value="system/choose/nvl.png"]
[config name="choose.box1.hover" value="system/choose/nvl.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box2.idle" value="system/choose/nvl.png"]
[config name="choose.box2.hover" value="system/choose/nvl.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box3.idle" value="system/choose/nvl.png"]
[config name="choose.box3.hover" value="system/choose/nvl.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="click.move" value="true"]
[text action="clear"]
```

Вернуться в режим ADV можно, сбросив конфигурацию.

```
[text action="hide"]
[wait time="0.3"] # Ждем, пока окно сообщения скроется.
[config name="game.novel" value="false"]
[config name="msgbox.image" value="system/message/msgbox.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="520"]
[config name="msgbox.margin.line" value="40"]
[config name="namebox.enable" value="true"]
[config name="choose.box1.idle" value="system/choose/idle.png"]
[config name="choose.box1.hover" value="system/choose/hover.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box2.idle" value="system/choose/idle.png"]
[config name="choose.box2.hover" value="system/choose/hover.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box3.idle" value="system/choose/idle.png"]
[config name="choose.box3.hover" value="system/choose/hover.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover.anime"]
[config name="click.move" value="false"]
```

В режиме NVL можно управлять текстовыми сообщениями так:

```
# Новая страница.
[text action="clear"]
[text text="Привет, это тест режима NVL."]
[text text="В режиме NVL окно сообщений оформлено как полноэкранное."]
[text text="По умолчанию каждый тег text делает перевод строки."]
[text text="Чтобы продолжить абзац,"]
[text text="укажите параметр space." space=" "]

# Новая страница.
[text action="clear"]
[text text="Пожалуйста, очищайте окно сообщения явно."]
```

### Голос

Если текущий язык `en-us`, файл голоса будет разрешаться в следующем порядке:

1. Параметр `voice-en-us`
2. `voice/en-us/` + параметр `voice`
3. Параметр `voice-en`
4. `voice/en/` + параметр `voice`
5. Параметр `voice`

Если текущий язык `ja`, файл голоса будет разрешаться в следующем порядке:

1. Параметр `voice-ja`
2. `voice/ja/` + параметр `voice`
3. Параметр `voice`

### Советы

**Автоматическое ожидание**:
* В отличие от других тегов, тег `text` автоматически ждет клика игрока после того, как сообщение полностью отображено.
* Не нужно добавлять тег `[click]` после каждой реплики!

**Использование переменных**:
* Вы можете подставлять переменные в текст, используя синтаксис `${variable_name}`.
* Пример: `[text text="Привет, ${player_name}!"]` поприветствует игрока тем именем, которое хранится в этой переменной.

**Переносы строк**:
* Проверьте конфигурацию проекта, чтобы понять, какой длины может быть одна строка.
* Если текст слишком длинный, он может выйти за пределы окна сообщения, поэтому следите за длиной аргумента `text`!

---

## `if`

Условное ветвление

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

### Базовое использование

```
# Проверить, равна ли переменная определенному значению
[if lhs="${points}" op="==" rhs="100"]
    [text text="Идеальный результат! Ты великолепен."]
[elseif lhs="${points}" op=">=" rhs="80"]
    [text text="Отличная работа! Ты справился."]
[else]
    [text text="В следующий раз повезет больше."]
[endif]
```

### Аргументы

| Аргумент | Можно опустить | Описание                           | Примечания                                     |
|----------|---------------|-------------------------------------|------------------------------------------------|
| `lhs`    | Нет           | Левая часть условия.                | Обычно это переменная вроде `${var_name}`.    |
| `op`     | Нет           | Оператор, используемый для сравнения. | См. таблицу "Операторы" ниже.              |
| `rhs`    | Нет           | Правая часть условия.               | Значение или переменная для сравнения.        |

### Операторы сравнения (`op`)

Вы можете использовать эти операторы, чтобы определить, как сравниваются две стороны:

| Оператор   | Описание                   |
|------------|----------------------------|
| `===`      | Equal (String)             |
| `==`       | Equal (Numeric)            |
| `>`        | Greater Than (Numeric)     |
| `>=`       | Greater Or Equal (Numeric) |
| `<`        | Less Than (Numeric)        |
| `<=`       | Less Or Equal (Numeric)    |

### Советы

**Закрытие блока**:
* Каждый блок `[if]` ОБЯЗАТЕЛЬНО должен заканчиваться тегом `[endif]`.
* Если вы забудете его, движок может запутаться, где заканчивается условие!

**Синтаксис переменных**:
* Если используете переменную как `lhs`, всегда заключайте ее в `${}`.
* Например, используйте `lhs="${flag_01}"`, а не просто `lhs="flag_01"`.

**Строки и числа**:
* Suika3 рассматривает значения переменных как строки, но эти операторы позволяют выполнять числовые сравнения.
* Просто последовательно используйте свои значения (например, "1" для true и "0" для false).

**Несколько ветвей**:
* Между `[if]` и `[endif]` можно использовать столько тегов `[elseif]`, сколько нужно, чтобы проверить несколько конкретных условий.

---
## `elseif`

Дополнительное условное ветвление

Тег `elseif` задает дополнительное условие внутри блока `[if]`.
Он вычисляется только в том случае, если предыдущее условие `[if]` и все предыдущие условия `[elseif]` оказались ложными.

### Базовое использование

```
[if lhs="${rank}" op="==" rhs="A"]
    [text text="Превосходно! Ты профи."]
[elseif lhs="${rank}" op="==" rhs="B"]
    [text text="Хорошая работа! Так держать."]
[elseif lhs="${rank}" op="==" rhs="C"]
    [text text="Неплохо, но можно лучше."]
[else]
    [text text="Не сдавайся! Попробуй еще раз."]
[endif]
```

### Аргументы

То же, что и у `[if]`. См. также [if](#if).

### Советы

**Последовательная проверка**:
* Движок проверяет условия сверху вниз.
* Как только одно из условий `[if]` или `[elseif]` выполняется, его блок запускается, а остальная часть ветви, включая другие `[elseif]` и `[else]`, пропускается.

**Размещение**:
* `[elseif]` всегда должен находиться между тегом `[if]` и тегом `[else]` или `[endif]`.
* Вы можете использовать столько тегов `[elseif]`, сколько нужно, чтобы учесть все варианты!

**Эффективность**:
* Если у вас много условий, проверяющих одну и ту же переменную, несколько тегов `[elseif]` гораздо чище и эффективнее, чем вложенные блоки `[if]` друг в друга.

---
## `else`

Ветвь по умолчанию

Тег `else` определяет блок кода, который выполняется, если ни одно из предыдущих условий `[if]` или `[elseif]` не было выполнено.
Он служит "ветвью по умолчанию" в вашей логике ветвления.

### Базовое использование

```
[if lhs="${weather}" op="==" rhs="sunny"]
    [text text="Прекрасный день!"]
[elseif lhs="${weather}" op="==" rhs="rainy"]
    [text text="Мне стоит взять зонт."]
[else]
    # Этот код выполняется, если не sunny ИЛИ rainy (например, cloudy или snowy)
    [text text="Сегодня небо выглядит интересно."]
[endif]
```

### Аргументы

Этот тег не принимает аргументов.

| Аргумент | Можно опустить | Описание | Примечания |
|----------|---------------|----------|------------|
| -        | -         | -           | -     |

### Советы

**Финальная ветвь на все случаи**:
* Используйте `[else]`, чтобы обработать любые сценарии, которые вы явно не покрыли в проверках `[if]` или `[elseif]`.
* Это гарантирует, что у игры всегда будет допустимый путь продолжения.

**Размещение**:
* `[else]` должен идти после всех тегов `[elseif]` (если они есть) и непосредственно перед тегом `[endif]`.
* В одном блоке `[if]` может быть только один `[else]`.

**Необязательность**:
* Вам *не обязательно* включать блок `[else]`.
* Если условия не выполнены и `[else]` отсутствует, движок просто пропустит все и продолжит выполнение после `[endif]`.

---
## `endif`

Завершение условной ветви

Тег `endif` обозначает конец условного блока, начатого тегом `[if]`.
Он сообщает движку, что после завершения логики ветвления нужно вернуться к обычному выполнению сценария.

### Базовое использование

```
[if lhs="${love_points}" op=">=" rhs="50"]
    [text text="Она дарит тебе теплую улыбку."]
[else]
    [text text="Она вежливо приветствует тебя."]
[endif]

# Выполнение сценария продолжается здесь независимо от результата выше
[text text="The day continues..."]
```

### Аргументы

Этот тег не принимает аргументов.

| Аргумент | Можно опустить | Описание | Примечания |
|----------|---------------|----------|------------|
| -        | -         | -           | -     |

### Советы

**Обязательное закрытие**:
* Каждый тег `[if]` обязательно должен иметь соответствующий `[endif]`.
* Думайте о них как о паре скобок, которые помогают упорядочить логику вашей истории.

**Размещение**:
* Всегда размещайте `[endif]` в самом конце последовательности условий, после любых блоков `[elseif]` или `[else]`.

**Вложенность**:
* Если вы помещаете один `[if]` внутрь другого `[if]`, убедитесь, что у каждого есть свой собственный `[endif]`.
* Правильная вложенность - это секрет сложных, безошибочных сюжетных флагов!

---
## `load`

Загрузка файла сценария

Тег `load` переключает текущий сценарий на другой файл NovelML.
Он в первую очередь используется для организации больших историй по нескольким главам или для перехода между разными частями игры, например от экрана заголовка к основному сюжету.

### Базовое использование

```
# Загрузить `scene02.novel` и начать с самого начала
[load file="scene02.novel"]

# Загрузить scene02.novel и перейти сразу к определенной метке
[load file="scene02.novel" label="chapter2_start"]
```

### Аргументы

| Аргумент | Можно опустить | Описание                                     | Примечания                                                |
|----------|---------------|---------------------------------------------|-----------------------------------------------------------|
| `file`   | Нет           | Имя файла NovelML-сценария для загрузки.    | Должен быть допустимым файлом в каталоге сценариев проекта. |
| `label`  | Да            | Целевая метка, к которой нужно перейти в новом файле. | Если не указано, сценарий начинается с самой первой строки. |

### Советы

**Организация проекта**:
* Вместо того чтобы писать всю игру в одном огромном файле, используйте `[load]`, чтобы разбить ее на управляемые части вроде `chapter1.novel`, `chapter2.novel` и так далее.

**Немедленный переход**:
* Когда движок достигает тега `[load]`, он немедленно прекращает выполнение текущего файла NovelML и переключается на новый.
* Любые команды, размещенные после `[load]` в исходном файле, выполняться не будут.

**Глобальные флаги**:
* Не беспокойтесь о своих переменных: любые значения, заданные тегом `[set]`, сохранятся даже после загрузки нового файла сценария!

---
## `se`

Воспроизведение звукового эффекта

Тег `se` проигрывает звуковой эффект (SE).
Звуковые эффекты используются для коротких аудиосигналов, например стуков в дверь, шагов или откликов интерфейса, добавляя вашим сценам слой погружения и реализма.

### Базовое использование

```
# Один раз проиграть звуковой эффект
[se file="door_open.ogg"]

# Остановить все звуковые эффекты, которые сейчас воспроизводятся
[se file="none"]
```

### Аргументы

| Аргумент | Можно опустить | Описание                                  | Примечания                                   |
|----------|---------------|-------------------------------------------|----------------------------------------------|
| `file`   | Нет           | Имя файла звукового эффекта для воспроизведения. | Установите `none`, чтобы остановить воспроизведение звука. |
| `loop`   | Да (`false`)  | Воспроизводить ли звуковой эффект по кругу. |                                              |

### Советы

**Требуемый формат**:
* Как и BGM, Suika3 требует, чтобы файлы SE были в формате **Ogg Vorbis**.
* Частота дискретизации ОБЯЗАТЕЛЬНО должна быть **44,100Hz**, чтобы обеспечить высокое качество и совместимость.

**Наложение звуков**:
* Звуковые эффекты обычно можно проигрывать, пока воспроизводится BGM.
* Они используют собственную аудиодорожку, поэтому не прерывают музыку.

**Управление громкостью**:
* Чтобы изменить громкость звуковых эффектов, не трогая громкость BGM, используйте тег `[volume]` с `track="se"`.

**Использование для фоновых звуков**:
* Хотя SE часто используется для коротких звуков, его также можно применять для зацикленных фоновых звуков, например ветра или дождя.
* Зацикленный SE восстанавливается при загрузке файла сохранения.

---
## `volume`

Установка громкости звука

Тег `volume` задает громкость звука для конкретной аудиодорожки.
Он идеально подходит для того, чтобы фоновая музыка не заглушала важные звуковые эффекты или реплики персонажей.

### Базовое использование

```
# Установить громкость BGM на 50%
[volume track="bgm" volume="0.5"]

# Установить громкость SE на максимум
[volume track="se" volume="1.0"]

# Выключить голоса
[volume track="voice" volume="0.0"]
```

### Аргументы

| Аргумент | Можно опустить | Описание                          | Примечания                               |
|----------|---------------|------------------------------------|------------------------------------------|
| `track`  | Нет           | Аудиодорожка, которую нужно настроить. | См. таблицу "Дорожки" ниже.           |
| `volume` | Нет           | Уровень громкости от `0.0` до `1.0`. | `0.0` означает тишину, `1.0` - максимум. |
| `time`   | Да (`0`)      | Время затухания в секундах.        | `0` означает мгновенное изменение.      |

### Типы дорожек (`track`)

Suika3 разделяет аудио на три основные дорожки:

| Название дорожки | Описание                    |
|------------------|-----------------------------|
| `bgm`            | Фоновая музыка.             |
| `se`             | Звуковые эффекты и системные звуки. |
| `voice`          | Файлы голосов персонажей.   |

### Советы

**Немедленное изменение**:
* Изменение громкости происходит постепенно, когда `time` больше `0`.
* `time="0"` означает мгновенное изменение.

**Уровни по умолчанию**:
* Хорошая идея - задать предпочитаемые уровни громкости в начале игры (например, в метке `start`), чтобы у игрока с самого начала был стабильный опыт.

---
## `skip`

Установка состояния пропуска

Тег `skip` включает или отключает функцию пропуска в игре.
Он полезен для того, чтобы не позволять игрокам пропускать важные кинематографические сцены или чтобы определенные сцены воспринимались в заданном темпе.

### Базовое использование

```
# Включить функцию пропуска
[skip enable="true"]

# Отключить функцию пропуска во время критической сцены
[skip enable="false"]
```

### Аргументы

| Аргумент | Можно опустить | Описание                               | Примечания                                            |
|----------|---------------|---------------------------------------|-------------------------------------------------------|
| `enable` | Нет           | Включена функция пропуска или нет.    | Установите `true`, чтобы разрешить пропуск, `false`, чтобы заблокировать его. |

### Советы

**Управление кинематографией**:
* Функция пропуска обычно отключается перед титульным логотипом при запуске.

**Восстановление настроек**:
* Не забудьте снова установить `[skip enable="true"]`, когда критическая сцена закончится.
* Игроки обычно ценят возможность пропускать уже прочитанный текст.

**Поведение системы**:
* Этот тег управляет общим состоянием "Skip" в движке.
* Даже если игрок нажмет горячую клавишу пропуска, движок проигнорирует ее, если `enable` имеет значение `false`.

---
## `config`

Задание значения конфигурации

Тег `config` позволяет напрямую изменять параметры конфигурации игровой системы из разметки.
Он незаменим для динамической настройки UI, например для перемещения окна сообщения или изменения системных параметров на лету.

### Базовое использование

```
# Изменение позиции окна сообщения
[config name="msgbox.x" value="100"]
[config name="msgbox.y" value="200"]

# Обновление конкретной системной настройки
[config name="msgbox.font.size" value="24"]
```

### Аргументы

| ???????? | ????? ???????? | ????????                                        | ??????????                                                    |
|----------|-----------|----------------------------------------------------|----------------------------------------------------------|
| `name`   | No        | Имя параметра конфигурации, который нужно изменить.| См. список конфигурации системы для допустимых имен.     |
| `value`  | No        | Новое значение, которое нужно присвоить параметру. | Значения обрабатываются как строки, но могут быть числами. |

### Советы

**Настройка интерфейса**:
* Можно использовать `[config]`, чтобы смещать окно сообщения в отдельных сценах и делать их более кинематографичными.

**Динамическая подстройка**:
* Поскольку этот тег можно вызывать в любом месте скрипта, вы можете менять "вид и ощущение" игры по мере развития сюжета.
* Например, сдвигать UI для сцены "flashback".

**Имена параметров**:
* Будьте внимательны с аргументом `name`!
* Он должен в точности совпадать с внутренними ключами конфигурации, определенными в настройках проекта Suika3.
* См. также [полный список конфигураций](config.md)

---
## `layer`

Прямое управление слоями

Тег `layer` позволяет напрямую управлять отдельными слоями изображений и текста.
Если для стандартных сцен теги вроде `[bg]` и `[ch]` использовать проще, то `[layer]` дает точность для независимого изменения позиции, масштаба и поворота любого отдельного слоя.

### Базовое использование

```
# Загрузить изображение напрямую на центральный слой персонажа (chc)
[layer name="chc" file="heroine_smile.png"]

# Изменить только позицию и прозрачность фона (bg)
[layer name="bg" x="100" y="100" alpha="128"]

# Повернуть слой лица
[layer name="chf" rotate="45.0" center-x="100" center-y="100"]
```

### Аргументы

| ????????  | ????? ????????   | ????????                          | ??????????                              |
|-----------|-------------|--------------------------------------|------------------------------------|
| `name`    | No          | Имя целевого слоя.                   | См. таблицу "??? ????s" ниже.    |
| `file`    | Yes         | Имя файла, который нужно загрузить на слой. | Используйте `none`, чтобы очистить слой. |
| `x`       | Yes (`0`)   | Позиция слоя по X.                   |                                    |
| `y`       | Yes (`0`)   | Позиция слоя по Y.                   |                                    |
| `alpha`   | Yes (`255`) | Уровень непрозрачности слоя.         | `0` до `255`.                      |
| `scale-x` | Yes (`1.0`) | Коэффициент масштабирования по X.    | `1.0` - исходный размер.           |
| `scale-y` | Yes (`1.0`) | Коэффициент масштабирования по Y.    | `1.0` - исходный размер.           |
| `center-x`| Yes (`0`)   | Центр вращения (X).                  | Точка опоры для вращения.          |
| `center-y`| Yes (`0`)   | Центр вращения (Y).                  | Точка опоры для вращения.          |
| `rotate`  | Yes (`0.0`) | Вращение в градусах.                 | Положительное значение - по часовой стрелке. |

### Часто используемые имена слоёв (`name`)

В Suika3 есть богатый набор предопределенных слоев.

Ниже приведен полный список слоев:

|??? ????       |????????                              |
|-----------------|-----------------------------------------|
|bg               |Фоновое изображение                     |
|bg2              |Фоновое изображение 2                   |
|efb1             |Задний эффект 1                         |
|efb2             |Задний эффект 2                         |
|efb3             |Задний эффект 3                         |
|efb4             |Задний эффект 4                         |
|chb              |Центральный задний персонаж             |
|chb-eye          |Глаза центрального заднего персонажа    |
|chb-lip          |Губы центрального заднего персонажа     |
|chb-fo           |Исчезающий центральный задний персонаж  |
|chl              |Левый персонаж                          |
|chl-eye          |Глаза левого персонажа                  |
|chl-lip          |Губы левого персонажа                   |
|chl-fo           |Исчезающий левый персонаж               |
|chlc             |Левый центральный персонаж              |
|chlc-eye         |Глаза левого центрального персонажа     |
|chlc-lip         |Губы левого центрального персонажа      |
|chlc-fo          |Исчезающий левый центральный персонаж    |
|chr              |Правый персонаж                         |
|chr-eye          |Глаза правого персонажа                 |
|chr-lip          |Губы правого персонажа                  |
|chr-fo           |Исчезающий правый персонаж              |
|chrc             |Правый центральный персонаж             |
|chrc-eye         |Глаза правого центрального персонажа    |
|chrc-lip         |Губы правого центрального персонажа     |
|chrc-fo          |Исчезающий правый центральный персонаж   |
|chc              |Центральный персонаж                    |
|chc-eye          |Глаза центрального персонажа           |
|chc-lip          |Губы центрального персонажа            |
|chc-fo           |Исчезающий центральный персонаж         |
|msgbox           |Окно сообщения (невидимо для `[layer]`) |
|namebox          |Окно имени (невидимо для `[layer]`)     |
|click            |Анимация клика (невидимо для `[layer]`) |
|eff1             |Передний эффект 1                       |
|eff2             |Передний эффект 2                       |
|eff3             |Передний эффект 3                       |
|eff4             |Передний эффект 4                       |
|chf              |Персонаж лица                           |
|chf-eye          |Глаза персонажа лица                   |
|chf-lip          |Губы персонажа лица                    |
|chf-fo           |Исчезающий персонаж лица                |
|text1            |Текстовый слой 1                        |
|text2            |Текстовый слой 2                        |
|text3            |Текстовый слой 3                        |
|text4            |Текстовый слой 4                        |
|text5            |Текстовый слой 5                        |
|text6            |Текстовый слой 6                        |
|text7            |Текстовый слой 7                        |
|text8            |Текстовый слой 8                        |
|gui1             |Кнопка GUI 1 (невидимо для `[layer]`)   |
|gui2             |Кнопка GUI 2 (невидимо для `[layer]`)   |
|gui3             |Кнопка GUI 3 (невидимо для `[layer]`)   |
|gui4             |Кнопка GUI 4 (невидимо для `[layer]`)   |
|gui5             |Кнопка GUI 5 (невидимо для `[layer]`)   |
|gui6             |Кнопка GUI 6 (невидимо для `[layer]`)   |
|gui7             |Кнопка GUI 7 (невидимо для `[layer]`)   |
|gui8             |Кнопка GUI 8 (невидимо для `[layer]`)   |
|gui9             |Кнопка GUI 9 (невидимо для `[layer]`)   |
|gui10            |Кнопка GUI 10 (невидимо для `[layer]`)  |
|gui11            |Кнопка GUI 11 (невидимо для `[layer]`)  |
|gui12            |Кнопка GUI 12 (невидимо для `[layer]`)  |
|gui13            |Кнопка GUI 13 (невидимо для `[layer]`)  |
|gui14            |Кнопка GUI 14 (невидимо для `[layer]`)  |
|gui15            |Кнопка GUI 15 (невидимо для `[layer]`)  |
|gui16            |Кнопка GUI 16 (невидимо для `[layer]`)  |
|gui17            |Кнопка GUI 17 (невидимо для `[layer]`)  |
|gui18            |Кнопка GUI 18 (невидимо для `[layer]`)  |
|gui19            |Кнопка GUI 19 (невидимо для `[layer]`)  |
|gui20            |Кнопка GUI 20 (невидимо для `[layer]`)  |
|gui21            |Кнопка GUI 21 (невидимо для `[layer]`)  |
|gui22            |Кнопка GUI 22 (невидимо для `[layer]`)  |
|gui23            |Кнопка GUI 23 (невидимо для `[layer]`)  |
|gui24            |Кнопка GUI 24 (невидимо для `[layer]`)  |
|gui25            |Кнопка GUI 25 (невидимо для `[layer]`)  |
|gui26            |Кнопка GUI 26 (невидимо для `[layer]`)  |
|gui27            |Кнопка GUI 27 (невидимо для `[layer]`)  |
|gui28            |Кнопка GUI 28 (невидимо для `[layer]`)  |
|gui29            |Кнопка GUI 29 (невидимо для `[layer]`)  |
|gui30            |Кнопка GUI 30 (невидимо для `[layer]`)  |
|gui31            |Кнопка GUI 31 (невидимо для `[layer]`)  |
|gui32            |Кнопка GUI 32 (невидимо для `[layer]`)  |

### Советы

**Точное управление**:
* Используйте `[layer]`, когда хотите вручную загрузить изображение на слой, особенно при работе с пользовательскими слоями эффектов (`eff1` и т. д.), для которых нет отдельных тегов.

**Мгновенное обновление**:
* В отличие от `[ch]` или `[bg]`, тег `layer` обычно обновляет экран мгновенно.
* Если нужно анимировать эти изменения во времени, используйте вместо него тег `[move]`!

**Иерархия слоев**:
* Помните, что слои накладываются друг на друга.
* Например, `chf` (Персонаж лица) всегда отображается перед `chc` (Центральный персонаж).
* Понимание этого "Z-order" - ключ к сложным визуальным композициям.

---
## `move`

Анимация слоя

Тег `move` анимирует отдельные слои в течение заданной длительности.
Он идеально подходит для создания эффектов скольжения, увеличения персонажей или вращения элементов экрана, чтобы добавить сценам динамики.

### Базовое использование

```
# Переместить центрального персонажа в новую позицию за 2.0 секунды
[move time="2.0" center-x="150" center-y="100"]

# Относительное движение: сдвинуть фон на 50px вправо
[move time="1.0" bg-x="r50"]

# Постепенно сделать слой прозрачным, одновременно вращая его
[move time="3.0" face-alpha="0" face-rotate="r360"]
```

### Аргументы

**Общие:**
| ????????         | ????? ????????     | ????????                               | ??????????                                      |
|------------------|---------------|-------------------------------------------|--------------------------------------------|
| `name`           | No            | Целевой слой для анимации.               | См. таблицу "Moveable Layers" ниже.       |
| `time`           | No            | Длительность анимации в секундах.        | Поддерживает дробные значения (например, `0.5`). |
| `async`          | Yes (`false`) | Если `true`, выполнять анимацию без блокировки. |                                            |
| `accel`          | Yes (`normal`)| Тип ускорения.                           | Один из                                     |
| (layer)-(suffix) | Yes           |                                           |                                            |

**(layer):**
| ????????       | ????????                               |
|----------------|-------------------------------------------|
| `bg`           | Фоновый слой.                             |
| `bg2`          | Второй фон.                               |
| `back`         | Задний центральный персонаж.              |
| `left`         | Левый персонаж.                           |
| `right`        | Правый персонаж.                          |
| `center`       | Центральный персонаж.                     |
| `left-center`  | Левый центральный персонаж.               |
| `right-center` | Промежуточный персонаж.                  |
| `face`         | Персонаж лица.                            |

**(suffix):**
| ???????      | ????? ????????     | ????????                | ??????????                                                         |
|-------------|---------------|----------------------------|---------------------------------------------------------------|
| `-x`        | Yes (`0`)     | Позиция по X.              | Поддерживает абсолютные значения (например, `100`) или относительные (например, `r50`). |
| `-y`        | Yes (`0`)     | Позиция по Y.              | Поддерживает абсолютные значения (например, `100`) или относительные (например, `r-50`). |
| `-a`        | Yes (`255`)   | Значение альфы (непрозрачность). | `0` (прозрачно) до `255` (непрозрачно).                 |
| `-scale-x`  | Yes (`1.0`)   | Коэффициент масштабирования по X. | `1.0` - исходный размер. Поддерживает префикс `r`.      |
| `-scale-y`  | Yes (`1.0`)   | Коэффициент масштабирования по Y. | `1.0` - исходный размер. Поддерживает префикс `r`.      |
| `-center-x` | Yes (`0`)     | Центр вращения по X.       | Точка опоры для эффекта вращения.                          |
| `-center-y` | Yes (`0`)     | Центр вращения по Y.       | Точка опоры для эффекта вращения.                          |
| `-rotate`   | Yes (`0`)     | Вращение в градусах.       | Положительное значение - по часовой стрелке. Поддерживает префикс `r`. |
| `-dim`      | Yes (`false`) | Состояние затемнения.      | Если `true`, слой отображается на 50% темнее.             |

### Советы

**Неблокирующая анимация (`async="true")`**:
* Скрипт сразу переходит к следующей команде после запуска `[move]`.
* Если нужно дождаться завершения анимации, следуйте за ним тегом `[wait]` с тем же значением `time`.

**Относительные преобразования**:
* Использование префикса `r` (например, `x="r100"`) очень полезно для повторяющихся движений, например чтобы заставить персонажа "прыгать" или "трястись" без вычисления абсолютных координат.

**Визуальная полировка**:
* Комбинируйте `scale-x` и `scale-y` с `move`, чтобы создавать эффекты "приближения" к лицу персонажа для драматичных крупных планов!

---
## `pencil`

Карандаш

Рисует текст на слое.

### Базовое использование

```
[pencil layer="bg" font-size="30" text="Hello, World!"]
```

### Аргументы

| ????????      | ????? ????????        | ????????              |
|---------------|------------------|--------------------------|
| text          | No               | Текст для вывода.        |
| layer         | Yes (`text1`)    | Имя слоя.                |
| font-type     | Yes (`0`)        | Выбор шрифта. (0-3)      |
| font-size     | Yes (`16`)       | Размер шрифта.           |
| color         | Yes (`#000000`)  | Цвет шрифта.             |
| outline-width | Yes (`0`)        | Ширина обводки шрифта.   |
| outline-color | Yes (`#ffffff`)  | Цвет обводки шрифта.     |
| line-margin   | Yes              | Межстрочный интервал.    |
| char-margin   | Yes (`0`)        | Межсимвольный интервал.  |
| x             | Yes (`0`)        | Позиция области вывода по X. |
| y             | Yes (`0`)        | Позиция области вывода по Y. |
| width         | Yes              | Ширина области вывода.   |
| height        | Yes              | Высота области вывода.   |
## Поддерживаемые имена слоёв

|??? ????       |????????                              |
|-----------------|-----------------------------------------|
|bg               |Фоновое изображение                     |
|bg2              |Фоновое изображение 2                   |
|efb1             |Задний эффект 1                         |
|efb2             |Задний эффект 2                         |
|efb3             |Задний эффект 3                         |
|efb4             |Задний эффект 4                         |
|chb              |Центральный задний персонаж             |
|chl              |Левый персонаж                           |
|chlc             |Левый центральный персонаж              |
|chr              |Правый персонаж                          |
|chrc             |Правый центральный персонаж             |
|chc              |Центральный персонаж                    |
|eff1             |Передний эффект 1                       |
|eff2             |Передний эффект 2                       |
|eff3             |Передний эффект 3                       |
|eff4             |Передний эффект 4                       |
|chf              |Персонаж лица                           |
|text1            |Текстовый слой 1                        |
|text2            |Текстовый слой 2                        |
|text3            |Текстовый слой 3                        |
|text4            |Текстовый слой 4                        |
|text5            |Текстовый слой 5                        |
|text6            |Текстовый слой 6                        |
|text7            |Текстовый слой 7                        |
|text8            |Текстовый слой 8                        |

---
## `returnmacro`

Возврат из макроса

Тег `returnmacro` немедленно завершает текущий макрос и возвращает выполнение скрипта к строке, следующей за исходным тегом `[callmacro]`.
Он особенно полезен для досрочного выхода из макроса на основе определенных условий внутри блока `[if]`.

### Базовое использование

```
[defmacro name="check_item"]
    [if lhs="${has_key}" op="==" rhs="false"]
        [text text="Дверь заперта."]
        [returnmacro]
    [endif]

    # Эта часть выполняется только если has_key равно true
    [text text="Вы открыли дверь ключом!"]
[endmacro]
```

### Аргументы

Этот тег не принимает аргументов.

| ???????? | ????? ???????? | ???????? | ?????????? |
|----------|-----------|-------------|-------|
| -        | -         | -           | -     |

### Советы

**Досрочный выход**:
* Используйте `[returnmacro]` внутри блока `[if]`, чтобы пропустить оставшиеся команды макроса при выполнении определенного условия.
* Это делает ваши макросы гибкими и мощными!

**Неявный возврат**:
* На самом деле не нужно ставить `[returnmacro]` в самом конце каждого макроса.
* Как только движок доходит до тега `[endmacro]`, он автоматически возвращается в основной скрипт.

**Управление потоком**:
* Помните, что этот тег завершает только *текущий* макрос. Он не останавливает всю игру и не переходит к другой метке - он просто возвращает вас туда, откуда макрос был вызван.

---
## `video`

Воспроизведение видео

Тег `video` воспроизводит видеофайл на экране.
Он идеально подходит для вступительных роликов, переходных сцен или выразительных визуальных эффектов, которые лучше всего выглядят в формате полноэкранного видео.

### Базовое использование

```
# Воспроизвести вступительный ролик (его нельзя пропустить)
[video file="opening.mp4"]

# Воспроизвести короткую сцену, которую игрок может пропустить щелчком.
[video file="cutscene01.mp4" skippable="true"]
```

### Аргументы

| ????????    | ????? ????????     | ????????                                           | ??????????                                                         |
|-------------|---------------|-------------------------------------------------------|---------------------------------------------------------------|
| `file`      | No            | Имя видеофайла, который нужно воспроизвести.         | Файл должен быть в поддерживаемом формате (например, .mp4).   |
| `skippable` | Yes (`false`) | Можно ли пропустить видео щелчком игрока.            | Установите `false`, чтобы заставить игрока смотреть видео целиком. |

### Советы

**Поддержка файлов**:
* Убедитесь, что ваш видеофайл имеет формат .mp4 (H.264 + AAC).
* Если нужна поддержка 32-битной версии Windows, подготовьте рядом с .mp4 файл .wmv, затем удалите расширение, например `[video file="opening"]`.

**Переход**:
* После завершения воспроизведения видео (или его пропуска) движок автоматически переходит к следующей команде в вашем скрипте.
* Часто удобно следом за тегом `[video]` использовать тег `[bg]`, чтобы после завершения ролика экран выглядел именно так, как нужно.

**Аудио в видео**:
* Большинство видеофайлов содержат собственную звуковую дорожку.
* Учитывайте, что этот звук будет воспроизводиться вместе с любым `[bgm]`, который уже играет.
* Возможно, стоит остановить музыку с помощью `[bgm file="none"]` перед запуском видео со звуком!

---
## `wait`

Ожидание времени

Тег `wait` приостанавливает выполнение NovelML на указанную длительность.
Он необходим для управления темпом визуальных переходов, создания драматических пауз или синхронизации эффектов без участия игрока.

### Базовое использование

```
# Пауза на 1.5 секунды перед следующей командой
[wait time="1.5"]

# Короткая пауза между сменой персонажей
[ch center="chara01_surprised.png" time="0.5"]
[wait time="1.0"]
[text text="Она не могла поверить своим глазам."]
```

### Аргументы

| ????????      | ????? ????????     | ????????                    | ??????????                                  |
|---------------|---------------|--------------------------------|----------------------------------------|
| `time`        | No            | Количество секунд ожидания.    | Поддерживает дробные значения (например, `0.5`). |
| `hidemsgbox`  | Yes (`false`) | Принудительно скрыть окно сообщения. |                                        |
| `hidenamebox` | Yes (`false`) | Принудительно скрыть окно имени.    |                                        |

### Советы

**Пауза без взаимодействия**:
* В отличие от `[click]`, который ждет действий игрока, `[wait]` продолжается автоматически, когда время истекает.
* Это идеально подходит для сегментов с "автовоспроизведением" или временных визуальных последовательностей.

**Совмещение с анимациями**:
* Если использовать тег `[ch]` или `[bg]` с аргументом `time`, движок сразу переходит к следующей команде, пока анимация проигрывается.
* Используйте `[wait]` после анимации, если хотите, чтобы скрипт не продолжался до ее завершения (или даже дольше ради драматического эффекта).

**Пользовательский опыт**:
* Следите за тем, чтобы значения `[wait]` не были слишком длинными (например, больше 3 секунд) без визуальной причины, иначе игрок может подумать, что игра зависла!
