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

Содержание

---

anime

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

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

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

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

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

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

Аргументы

Советы

Синхронно или асинхронно:

• Синхронно (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"]

Аргументы

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

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

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

Советы

Относительное позиционирование:

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

Что такое rule-изображение?:

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

---

bgm

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

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

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

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

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

Аргументы

Советы

Требуемый формат:

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

Зацикливание:

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

Плавные переходы:

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

Остановка музыки:

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

---

callmacro

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

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

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

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

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

Аргументы

Советы

Эффективность:

• Используя [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"]

Аргументы

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

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

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

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

Советы

Пакетные обновления:

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

Относительные преобразования:

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

---

chapter

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

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

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

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

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

Аргументы

Советы

Видимость данных сохранения:

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

Последовательность:

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

Обновление имен:

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

---

choose

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

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

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

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

Аргументы

Локализация

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

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

Например, если локаль пользователя en-AU, применяется следующий приоритет:

• 1. text1-en-au
• 1. text1-en
• 1. text1

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

Советы

Логика ветвления:

• Вы можете использовать тег [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"]

Аргументы

Советы

Работа со строками:

• Поскольку 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="Солнце встает над горизонтом."]

Аргументы

Советы

Безусловный переход:

• В отличие от [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"]

Аргументы

Советы

Закрытие определения:

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

Переиспользование кода:

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

Организация:

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

Вложенность и логика:

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

---

gui

Показ GUI

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

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

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

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

Аргументы

Советы

Определения GUI:

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

Использование в потоке:

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

Настройка:

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

---

label

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

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

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

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

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

Аргументы

Советы

Управление навигацией:

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

Уникальные имена:

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

Организация:

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

---

text

Показ текста

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

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

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

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

Аргументы

Локализация

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

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

Например, если локаль пользователя en-GB, применяется следующий приоритет:

• 1. text-en-gb
• 1. text-en
• 1. text

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

Действия

В теге 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]

Аргументы

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

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

Советы

Закрытие блока:

• Каждый блок [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] или [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"]

Аргументы

Советы

Организация проекта:

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

Немедленный переход:

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

Глобальные флаги:

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

---

se

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

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

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

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

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

Аргументы

Советы

Требуемый формат:

• Как и 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)

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

Советы

Немедленное изменение:

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

Уровни по умолчанию:

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

---

skip

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

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

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

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

# Отключить функцию пропуска во время критической сцены
[skip enable="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"]

Аргументы

Советы

Настройка интерфейса:

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

Динамическая подстройка:

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

Имена параметров:

• Будьте внимательны с аргументом name!
• Он должен в точности совпадать с внутренними ключами конфигурации, определенными в настройках проекта Suika3.
• См. также полный список конфигураций

---

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)

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

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

Советы

Точное управление:

• Используйте [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"]

Аргументы

Общие:

(layer):

(suffix):

Советы

Неблокирующая анимация (async="true"):

• Скрипт сразу переходит к следующей команде после запуска [move].
• Если нужно дождаться завершения анимации, следуйте за ним тегом [wait] с тем же значением time.

Относительные преобразования:

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

Визуальная полировка:

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

---

pencil

Карандаш

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

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

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

Аргументы

Поддерживаемые имена слоёв

---

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"]

Аргументы

Советы

Поддержка файлов:

• Убедитесь, что ваш видеофайл имеет формат .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="Она не могла поверить своим глазам."]

Аргументы

Советы

Пауза без взаимодействия:

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

Совмещение с анимациями:

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

Пользовательский опыт:

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