Справочник по синтаксису NovelML
================================

Этот документ объясняет базовый синтаксис NovelML и то, как он выполняется.

Подробное описание каждого тега см. в "Suika3 Tag Reference".

---

## 1. NovelML - это список команд движка, называемых тегами

NovelML - это список **тегов**. Тег - это **команда для движка**.

- Каждый тег говорит движку выполнить какое-либо действие
- Теги выполняются **один за другим**, в том порядке, в котором они записаны
- После выполнения тег считается "завершенным", а "позиция выполнения" переходит дальше

Если записать тот же тег снова, он выполнит то же действие **каждый раз при выполнении**.

---

## 2. Выполнение идет сверху вниз

NovelML выполняется от начала файла к концу, по одному тегу за раз.

- Обычно выполнение движется вперед
- Существует только одна текущая **позиция выполнения**

```PlainText
[text text="Привет"]
[text text="Мир"]
```

В этом случае:

1. Показывается `Привет`
2. Затем показывается `Мир`

---

## 3. Все должно быть записано как теги

В NovelML **каждая строка должна быть тегом**.

- Весь сценарий записывается с помощью тегов
- Даже текст должен использовать тег `[text]`

```PlainText
[text text="Сегодня прекрасный день."]
```

---

## 4. Теги, которые ждут, и теги, которые не ждут

Есть два основных вида тегов:

- **Теги, которые выполняются и сразу переходят к следующему тегу**
- **Теги, которые ждут** ввода пользователя или завершения какого-либо действия

Распространенные теги "ожидания":

- `text` (ждет щелчка)
- `click` (ждет щелчка)
- `wait` (ждет указанное время)
- `video` (ждет завершения воспроизведения)

Эти теги приостанавливают выполнение **без какого-либо специального синтаксиса**.

### 4.1 Теги, которые выполняются в фоне (асинхронно)

Некоторые теги могут **выполняться в фоне** (асинхронно).

Типичные примеры:

- `anime`
- `move`

Эти теги:

- Создают и запускают анимацию или движение
- Если указан `async="true"`, движок **не ждет** завершения и сразу продолжает выполнение следующего тега

Из-за этого теги после тега с `async="true"` могут выполняться **пока анимация еще проигрывается**.

Это позволяет делать, например, следующее:

- Двигать фон или персонажа
- Одновременно показывать текст или запускать другие эффекты

---

## 5. Теги, которые изменяют поток выполнения

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

### 5.1 Метки

```PlainText
[label start]
```

- Метка отмечает именованную позицию в сценарии
- Само выполнение метки ничего не делает

### 5.2 Переходы

```PlainText
[goto name="start"]
```

---

## 6. Условное ветвление (if / elseif / else)

```PlainText
[if ...]
  ...
[elseif ...]
  ...
[else]
  ...
[endif]
```

- Выполняется только первый подходящий блок
- Блоки, которые не выбраны, **полностью пропускаются**
- `elseif` можно записывать ноль или более раз
- `else` необязателен

---

## 7. Переменные и подстановка переменных

### 7.1 Установка переменных

Используйте тег `[set]`, чтобы задать переменную.

```PlainText
[set name="player_name" value="Alice"]
```

- Все переменные являются **строками**
- Числа и булевы значения также хранятся как строки

### 7.2 Подстановка переменных

Подстановку переменных можно использовать внутри значений тегов и текста.

```PlainText
[text text="${player_name} встает"]
```

- `${...}` заменяется значением переменной во время выполнения
- Подстановка происходит **при выполнении тега**

```PlainText
[set name="x" value="1"]
[text text="${x}"]
[set name="x" value="2"]
[text text="${x}"]
```

В этом примере выводом будет `1`, а затем `2`.

---

## 8. Макросы - это блоки, которые можно выполнять как единое целое

Макросы позволяют сгруппировать несколько тегов и выполнить их вместе.

```PlainText
[defmacro name="greet"]
  [text text="Привет"]
[endmacro]

[callmacro name="greet"]
```

---

## 9. Переключение файлов (load)

```PlainText
[load file="scene2.txt" label="start"]
```

`file=` обязателен, а `label=` необязателен.

---

## 10. Что происходит в конце файла

Если выполнение:

- Достигает конца файла, и
- Больше не выполняются теги `goto` или `load`

Тогда **выполнение сценария завершается**.

Однако на некоторых платформах (например, iOS или игровых консолях) приложению не разрешено завершаться.

Поэтому рекомендуется, чтобы ваш сценарий **явно**:

- Возвращался к заголовку с помощью `goto`, или
- Загружал сцену заголовка с помощью `load`

вместо автоматического завершения.

---

## 11. Как этот документ связан с другой документацией

Этот документ предназначен для использования вместе с:

- Tag Reference: объясняет, что делает каждый тег
- Этот документ: объясняет, как выполняется сценарий

Подробности по отдельным тегам см. в "Tag Reference".
