NaniExtensions — CutsceneSystem

⚠️ Экспериментальный пакет — спутник CutsceneSystem, который не прошёл обкатку в продуктовой эксплуатации. Набор и параметры команд сценария может измениться вместе с ним без обратной совместимости.

Namespace: Vortex.NaniExtensions.CutsceneSystem Сборка: ru.vortex.nani.cutscenes (defineConstraints: USING_NANINOVELL)


Назначение

Команды сценария Naninovel для CutsceneSystem. Команды только переводят строки сценария в вызовы CutsceneBus: загрузкой контента, фазами и завершением занимается пакет катсцен.

Шина катсцен исполняет команды не сразу, а в конце кадра. Поэтому команды сценария, от результата которых зависит следующая строка, ждут этого результата.

Вне ответственности:

  • Закрытие катсцены при остановке сценария само не делается: катсцену завершает её цепочка либо @cutscene_Stop / @cutscene_Skip. Страховка на этот случай — CutsceneAutostopHandler на сцене (см. ниже).
  • Порядок отрисовки катсцены относительно фонов, персонажей и текста Naninovel.

Команды

Команда Что делает Чего ждёт сценарий
@cutscene_Play ключ открывает катсцену; ключ — идентификатор записи LogicChain начала показа либо отказа
@cutscene_Next «дальше»: переход к следующему этапу ничего
@cutscene_Stop останавливает катсцену: показ прерывается, контент выгружается закрытия катсцены
@cutscene_Skip то же, что @cutscene_Stop закрытия катсцены

@cutscene_Play

  • Идущая катсцена сначала закрывается, и сценарий ждёт её закрытия.
  • Затем сценарий ждёт, пока контент загрузится и показ начнётся, — либо пока открытие не будет отклонено (причину пишет в лог пакет катсцен). Команда слушает события шины только со своим ключом.
  • Конца катсцены команда не ждёт: сценарий идёт дальше, пока катсцена показывается.

@cutscene_Next

Действует на любой фазе идущей катсцены. Игнорируется: до запуска первой фазы (контент ещё грузится), во время пролёта и раньше задержки защиты от дребезга (настройка оркестратора). Фаза сменится на ближайшем проходе оркестратора; спрайтовый контент покажет её с учётом своей задержки переключения.

@cutscene_Stop и @cutscene_Skip

Прерывание у шины одно — пролёт цепочки до завершающего этапа, поэтому по действию команды совпадают. Два имени — для читаемости сценария: Stop — катсцену останавливает сам сценарий, Skip — её пропускают.

Сценарий продолжается, когда катсцена закрыта.


CutsceneAutostopHandler

Аварийный останов катсцены по остановке сценария. Компонент ставится на сцену — на объект, который включён всё время, пока на сцене могут идти катсцены (обычно на объект оркестратора). Настроек у него нет.

Хэндлер держит защёлку «катсцена открыта»:

  • событие шины OnShowOpening (оркестратор принял открытие и начал загрузку) защёлку открывает;
  • событие OnShowFinished её закрывает.

Сценарий остановился (NaniWrapper.OnNaniStop) при открытой защёлке — катсцена прерывается, как по @cutscene_Stop: идущая пролетает до конца, загружаемая отменяется. Защёлка закрыта — хэндлер ничего не делает.

Контракт хэндлера: катсцена играется, пока играется скрипт. Защёлка одна и ключ катсцены не сверяет — настройки на конкретную катсцену у хэндлера нет. Если защёлка открыта, останавливается та катсцена, что открыта сейчас, какой бы она ни была.

  • Нужен там, где сценарий может оборваться раньше катсцены: выход в меню, загрузка сохранения, ошибка в сценарии. Если катсцену всегда закрывает сам сценарий, компонент не нужен.
  • Действует на любую катсцену сцены, в том числе запущенную не из сценария, и на естественный конец сценария тоже. На сцену, где катсцены должны переживать сценарий, компонент не ставится.
  • Катсцену, открытую, пока хэндлер был выключен, он не видит: при выключении защёлка закрывается.
  • Рассчитан на штатное использование пакета катсцен — один источник управления. При состязательных открытиях из обработчиков событий показа защёлка может разойтись с действительностью (см. «Ограничения» в README пакета катсцен).
  • На префабе контента компонент не работает: к моменту создания контента событие OnShowOpening уже прошло.

OnNaniStop приходит, когда плеер сценария остановился и не ждёт выбора игрока, — через кадр после остановки. Смена скрипта и переходы внутри сценария остановкой не считаются: если новый скрипт запущен в пределах этого кадра, событие не приходит и катсцена не прерывается.


Пример

@cutscene_Play 3f6c1c0e-8d2a-4b7e-9a51-0c2f6d1e7b90
Первая фаза идёт под этот текст.
@cutscene_Next
Вторая фаза.
@cutscene_Stop

Граничные случаи

Ситуация Поведение
@cutscene_Play без ключа Debug.LogError, команда пропущена
Нет оркестратора, ключа нет в индексе, цепочка не прошла проверку ошибка в лог от пакета катсцен, сценарий идёт дальше
Сценарий остановлен во время ожидания ожидание снимается; начатая загрузка и уже выданная команда не отменяются
Сценарий остановлен, пока @cutscene_Play ждала закрытия прежней катсцены новая катсцена не открывается
@cutscene_Next / @cutscene_Stop / @cutscene_Skip без открытой катсцены ничего
@cutscene_Play той же катсцены, что уже идёт прежний показ закрывается, затем катсцена открывается заново
Сценарий остановился при идущей катсцене, на сцене есть CutsceneAutostopHandler катсцена прерывается: событие остановки приходит через кадр, пролёт — на ближайшем проходе оркестратора
Сценарий остановился, пока контент катсцены грузится, на сцене есть CutsceneAutostopHandler загрузка отменяется, катсцена не появляется
CutsceneAutostopHandler стоит на префабе контента не срабатывает никогда