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 стоит на префабе контента |
не срабатывает никогда |