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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

anime
move

Эти теги:

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

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

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

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

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

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

5.1 Метки

[label start]

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

5.2 Переходы

[goto name="start"]

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

[if ...]
  ...
[elseif ...]
  ...
[else]
  ...
[endif]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[callmacro name="greet"]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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