CutsceneSystem

⚠️ Экспериментальный пакет. Не прошёл обкатку в продуктовой эксплуатации. Публичное API CutsceneBus, контракт префаба контента и набор логик для LogicChain могут измениться без обратной совместимости. Вместе с ним экспериментальны пакеты-спутники: NaniExtensions/CutsceneSystem, SpineExtensions/Cutscenes, Sdk/CutsceneSystem.

Namespace: Vortex.Unity.CutsceneSystem.* Сборка: ru.vortex.unity.cutscene


Назначение

Показ катсцены как последовательности фаз. Чем показана фаза, пакет не знает: это может быть Spine, смена спрайтов или что угодно ещё, собранное в префабе контента.

  • Описание катсцены — логическая цепочка (LogicChain). Своего движка фаз нет: этапы, переходы и ожидания даёт LogicChainsSystem.
  • Контент — подгружаемый префаб. Он в памяти только на время показа.
  • Фазы — состояния контента. Номер фазы переводится в состояние UIStateSwitcher.
  • Одна шина обращений CutsceneBus: открыть, дальше, пропустить. Шина ничего не исполняет: она передаёт обращение оркестратору сцены и хранит данные показа.
  • Всё делает оркестратор. Обращение он запоминает, а исполняет на своём LateUpdate. Обращения и события никогда не исполняются вложенно друг в друга.
  • Пролёт вместо обрыва. Прерывание — быстрый проход цепочки до завершающего этапа.

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

  • Ветвление фаз. Последовательность строго линейная.
  • Чем показана фаза и чем она озвучена. Это содержимое префаба: элементы UIStateSwitcher, хэндлеры AudioAdvancedControl, Spine-хэндлеры из SpineExtensions.
  • Кто запускает катсцену. Сценарий, UI или игровая логика вызывают CutsceneBus сами; команды Naninovel лежат в NaniExtensions/CutsceneSystem.
  • Сохранение. Состояние показа в сейв не входит.
  • Пауза. Заморозка визуала и звука — дело хэндлеров контента.

Зависимости

Зависимость Назначение
Vortex.Core.LogicChainsSystem, Vortex.Unity.LogicChainsSystem цепочка, её запуск, база звеньев UnityLogicAction, идентификатор цепочки у звена и условия
Vortex.Unity.LogicConditionsSystem база условий UnityCondition
Vortex.Core.DatabaseSystem, Vortex.Unity.DatabaseSystem получение цепочки по ключу, [DbRecord] в индексе оркестратора
Vortex.Core.AssetHandleSystem AssetHandle<GameObject> — префаб контента
Vortex.Core.Extensions IntData, IReactiveData — управляющие данные
Vortex.Unity.UI.Misc DataStorage, DataStorageView<T>, UIStateSwitcher, [StateSwitcher]
Vortex.Unity.AppSystem TimeController — отложенная рассылка отказа открытию, пришедшему при пустом слоте
UniTask асинхронная загрузка контента

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

1. Цепочка катсцены

Create → Database → Logic Chain. Этап на каждую фазу и один завершающий:

1. Фаза 1
   Actions:    Cutscene: next phase
   Connector → Фаза 2
      Conditions: Cutscene: wait «Next»

2. Фаза 2
   Actions:    Cutscene: next phase
   Connector → Завершение
      Conditions: Cutscene: wait «Next»

3. Завершение
   Actions:    Cutscene: complete
   Connector → _CompleteChain
      Conditions: — (пусто)

Правила цепочки проверяются при открытии (см. «Проверка цепочки»).

2. Префаб контента

  • На корне — DataStorage и CutsceneContentHandler. Если смена фазы — переход на твинах (смена спрайтов), вместо него ставится CutsceneSpriteContentHandler (см. «Задержка переключения контента»).
  • UIStateSwitcher: нулевое состояние пустое (катсцена ещё не показана), дальше по одному состоянию на фазу, строго в порядке фаз. Стартовое состояние свитчера — пустое.
  • Визуал и звук фазы — элементы и объекты её состояния.
  • В фазе с автопереходом — источник сигнала: вызов CutsceneContentHandler.Next() из состояния (EventFire) либо профильный хэндлер (для Spine — SpineCutsceneAutoNext).

Готовые основы префаба контента лежат слоем выше, потому что звук в них — хэндлеры SDK:

3. Оркестратор на сцене

Объект с CutsceneOrchestrator:

Поле Назначение
cutscenes индекс: запись цепочки и хэндл префаба её контента
switcher свитчер состояний оркестратора: Off / Loading / On
target куда ставится контент; не задано — под сам оркестратор
nextDelay защита от дребезга, секунды; по умолчанию 0,2

4. Команды

CutsceneBus.Open(chainGuid);   // открыть; ключ — идентификатор записи LogicChain
CutsceneBus.Next();            // дальше
CutsceneBus.Skip();            // пропустить

CutsceneBus.OnShowStarted  += key => { };   // показ начался: контент загружен, цепочка запущена
CutsceneBus.OnShowFinished += key => { };   // показ завершён либо не состоялся

Обращение исполняется не в момент вызова, а на ближайшем LateUpdate оркестратора. События приходят после этого.


Архитектура

Bus/
  CutsceneBus (static)             — слот оркестратора, передача обращений, данные и события показа

Models/
  CutsceneControl                  — управляющие данные показа: номер фазы
  CutsceneStageState               — состояния оркестратора: Off / Loading / On

LogicChains/
  CutscenePhase                    — звено «Фаза»
  CutsceneComplete                 — звено «Завершение»
  CutsceneReadyCondition           — условие «Готовность к переходу»

Controllers/
  CutsceneChainValidator           — проверка цепочки перед запуском

Handlers/
  CutsceneOrchestrator             — приём обращений и весь показ: загрузка, цепочка, фазы, закрытие
  CutsceneContentHandler           — номер фазы → состояние свитчера контента
  CutsceneSpriteContentHandler     — то же, с задержкой между переключениями: для переходов на твинах

Шина и оркестратор

Зависимость односторонняя: оркестратор знает шину, шина об оркестраторе — только то, что слот занят.

Что есть на шине Назначение
Слот держатель один; пока слот занят, второй претендент отклоняется
Обращения Open, Next, Next(фаза), Skip и сигналы звеньев цепочки. Шина сразу передаёт их держателю слота событием и больше о них не помнит
Данные показа номер фазы (Control), IsSkipping, идентификатор цепочки идущего показа. Пишет держатель слота, читают контент, звенья и условия
События показа OnShowOpening, OnShowStarted, OnShowFinished. Рассылает держатель слота

Сама шина делает одно: отклоняет открытие, пришедшее при пустом слоте. Оркестратора она не ждёт: ошибка в лог сразу, OnShowFinished(ключ) — в конце кадра. Событие отложено, чтобы подписчик, открывающий катсцену заново на каждый отказ, не ушёл в бесконечную рекурсию. Отложенное событие рассылает TimeController: без него на сцене оно не придёт.

Подписчики событий шины сбрасываются при запуске игры (SubsystemRegistration). Подписываться нужно после этого момента — например, в OnEnable.

Обращения и их исполнение

В момент прихода обращения оркестратор только запоминает просьбу:

Обращение Что запоминается Когда не принимается
Open(ключ) «просили открыть» и ключ. Прежняя, ещё не исполненная просьба открытия вытесняется и получит OnShowFinished —
Next() «просили дальше» первая фаза ещё не запущена (контент грузится, первый этап цепочки не отработал); ждёт исполнения открытие либо пропуск; идёт пролёт; с входа в фазу прошло меньше nextDelay
Next(фаза) «просили дальше» то же, но без защиты от дребезга; вместо неё — фаза должна совпадать с фазой цепочки
Skip() «просили пропустить». Неисполненная просьба открытия отменяется и получит OnShowFinished —

Исполняет оркестратор на своём LateUpdate, всегда в одном порядке:

  1. Пропуск либо открытие поверх идущей катсцены — идущая доводится до конца пролётом, рассылается её OnShowFinished.
  2. Несостоявшиеся открытия получают OnShowFinished — те, что накопились к этому шагу. Отказ, порождённый обработчиком этого события, ждёт следующего прохода.
  3. Открытие — отказ (OnShowFinished(ключ)) либо начало загрузки и OnShowOpening(ключ).
  4. Результат загрузки — создаётся контент, запускается цепочка, первая фаза уходит контенту, OnShowStarted(ключ).
  5. «Дальше» — сигнал цепочке; затем новая фаза уходит контенту либо показ закрывается.

Правила:

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

Поток

CutsceneBus.Open(key)                       — шина передаёт просьбу оркестратору, тот её запоминает
    ↓ (LateUpdate оркестратора)
[Оркестратор] идущая катсцена пролетает и закрывается, OnShowFinished(её ключ)
    ↓
[Оркестратор] ключ в индексе, цепочка из базы, проверка цепочки
    └── свитчер → Loading, OnShowOpening(key), загрузка префаба
    ↓ (загрузка завершена; ближайший LateUpdate)
[Оркестратор] экземпляр под target, CutsceneControl → DataStorage экземпляра
    ├── свитчер → On
    └── цепочка в реестр, запуск
[Цепочка] этап фазы: CutscenePhase → номер фазы +1
[Оркестратор] номер фазы → контент; OnShowStarted(key)
    ↓
[Контент] CutsceneContentHandler → switcher.Set(номер фазы)
    ↓
[Цепочка] CutsceneReadyCondition ждёт сигнала «дальше»
    ├── CutsceneBus.Next()      — команда извне
    └── CutsceneBus.Next(фаза)  — автопереход от контента
    ↓ (LateUpdate оркестратора: сигнал цепочке) … следующие фазы …
[Цепочка] завершающий этап: CutsceneComplete отмечает «показ пора закрыть»
    ↓ (цепочка вернула управление)
[Оркестратор] выключает пролёт, выключает и уничтожает экземпляр, отпускает префаб, свитчер → Off
    ├── номер фазы → 0
    └── OnShowFinished(key)

Звенья

Звено В списке цепочки Что делает
CutscenePhase Cutscene: next phase увеличивает номер фазы на единицу; при пролёте не исполняется
CutsceneReadyCondition Cutscene: wait «Next» ждёт сигнала «дальше»; при пролёте выполнено сразу
CutsceneComplete Cutscene: complete отмечает, что показ пора закрыть; исполняется и при пролёте

Номер фазы порядковый: в звене нет данных, фаза — это «следующая».

Звено знает свою цепочку. LogicChainsSystem сообщает звену и условию идентификатор цепочки, которая их исполняет. Сигнал звена шина передаёт оркестратору вместе с этим идентификатором, и оркестратор сверяет его с цепочкой своего показа:

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

Звено «Завершение» само показ не закрывает. Оно только отмечает, что показ пора закрыть; оркестратор закрывает его, когда цепочка вернёт управление. Поэтому показ никогда не закрывается изнутри исполняемой цепочки, и до конца цепочки режим пролёта не выключается.

Сигнал «дальше» и защита от дребезга

Сигнал один, источников два:

  • CutsceneBus.Next() — команда извне. Не принимается, пока с входа в фазу прошло меньше nextDelay; время считается без учёта Time.timeScale. Номер фазы она не несёт и этап не проверяет.
  • CutsceneBus.Next(фаза) — автопереход от контента. Защиту обходит. Контент называет фазу, которую показывает; сигнал принимается, только если цепочка стоит на этой же фазе.

Обе проверки идут в момент прихода обращения. Оба порядка закрыты:

  • Автопереход сработал, следом пришла команда — она попадает в окно защиты новой фазы и не перескакивает её. Окно отсчитывает звено «Фаза»: у этапа без него и при nextDelay = 0 защиты нет.
  • Команда пришла, следом сработал автопереход прошлой фазы (пока контент догоняет цепочку) — сигнал назван старой фазой и не принимается.

Хэндлер контента подставляет фазу сам: источник автоперехода зовёт CutsceneContentHandler.Next(). Вызов от выключенного контента игнорируется: его показ закрыт, и отложенный сигнал (твин, таймер) не должен попасть в следующую катсцену.

События показа

Событие Когда
OnShowOpening(ключ) открытие принято оркестратором, началась загрузка контента
OnShowStarted(ключ) контент загружен, цепочка запущена, первая фаза ушла контенту
OnShowFinished(ключ) показ закрыт либо не состоялся: отказ открытия, сбой загрузки, отмена
  • Ключ катсцены — параметр события: подписчик отличает свою катсцену от чужой.
  • Порядок для одной катсцены: OnShowOpening → OnShowStarted → OnShowFinished. За OnShowOpening всегда приходит OnShowFinished с тем же ключом, поэтому по этой паре можно вести признак «катсцена открыта», включая загрузку. Отклонённое открытие даёт только OnShowFinished.
  • Рассылает оркестратор, когда состояние приведено в порядок: OnShowFinished — после выгрузки контента, OnShowStarted — после запуска цепочки и передачи первой фазы. Пока цепочка исполняется, события не рассылаются. Исключение одно: если оркестратор выключило звено цепочки, OnShowFinished неисполненных просьб открытия рассылается сразу, изнутри цепочки.
  • IsActive истинно с момента обращения Open и до рассылки её OnShowFinished. Если катсцену закрыло открытие новой, то в обработчике OnShowFinished прежней IsActive истинно.
  • Обращения из обработчика запоминаются и исполняются позже (см. «Без вложенности»).
  • Подписчики изолированы. Исключение одного пишется в лог (со стеком) и остальным не мешает. После исключения подписчика OnShowOpening либо OnShowStarted катсцена прерывается — как по Skip, в следующем кадре.
  • OnShowStarted не рассылается, если запуск сорвался (исключение звена до первого ожидания) либо цепочка завершилась сразу, не встав ни на одном условии.

Задержка переключения контента

CutsceneSpriteContentHandler — наследник CutsceneContentHandler для контента, где смена фазы идёт переходом на твинах. Если следующее состояние выставить посреди перехода, он оборвётся и кадр даст скачок яркости.

Поле Назначение
switchDelay минимальное время между переключениями фаз, секунды; по умолчанию 0,5
  • Следующее состояние выставляется не раньше, чем через switchDelay после предыдущего.
  • Фазы, пришедшие во время ожидания, не теряются и не перескакиваются: состояния выставляются по одному, строго по порядку.
  • Первая фаза показывается сразу: до неё переходов не было.
  • Время считается без учёта Time.timeScale — как и у твинов.
  • Задержка действует только на контент: цепочка и номер фазы идут без ожидания.
  • Автопереход от состояния, которое контент показывает с опозданием, не принимается: цепочка с этой фазы уже ушла.
  • Хэндлер и твины друг о друге не знают. Согласовать switchDelay с длительностью твинов — дело верстальщика.

Пролёт

По просьбе Skip оркестратор включает параметр шины IsSkipping и подаёт цепочке сигнал «дальше». Дальше цепочка идёт сама: условия пакета выполнены сразу, звенья фаз пропускаются, завершающее звено отмечает конец. Когда цепочка вернула управление, оркестратор закрывает показ.

Пока контент ещё грузится, цепочка не запущена: Skip отменяет загрузку.

Пролёт сделан параметром этого пакета, а не свойством LogicChainsSystem: в общем ядре он задел бы цепочки, где ожидания пропускать нельзя (например, загрузку приложения).

Выключение оркестратора

На OnDisable оркестратор отписывается от обращений и сразу освобождает слот. Показ его не переживает; при любой форме выключения оставшиеся этапы цепочки проходят до финала в режиме пролёта:

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

Слот свободен с момента выключения: другой оркестратор может занять его сразу. Оркестратор, включённый обратно, занимает слот заново.

Проверка цепочки

При открытии цепочка проходится от начального этапа до конца. Правила:

  • начальный этап задан, каждый переход ведёт на существующий этап;
  • у этапа ровно один переход;
  • на переходе либо нет условий, либо одно условие CutsceneReadyCondition;
  • звено CutsceneComplete стоит в последнем этапе и только в нём;
  • переход последнего этапа — без условий;
  • этапы не повторяются.

Цепочка, не прошедшая проверку, не запускается. Причины строгости: чужое условие остановило бы пролёт, а без завершающего этапа контент не выгрузится. Два условия на одном переходе не допускаются ещё и потому, что в LogicChainsSystem они могут дать двойное срабатывание перехода, если оба уже выполнены на входе в этап.

Остановившаяся цепочка

Исключение в звене останавливает цепочку. Куда оно попадает, зависит от момента:

  • Цепочка шла по сигналу «дальше» — исключение ловит LogicChainsSystem: пишет в лог его сообщение (без стека) и снимает условие этапа. Показ при этом уже не сдвинуть. Оркестратор это видит — цепочка вернула управление, а сигнала «дальше» никто не ждёт — и закрывает показ с ошибкой в лог, а не оставляет его висеть.
  • Звено до первого ожидания (при запуске показа) — исключение доходит до оркестратора: оно пишется в лог со стеком, показ закрывается как сбой запуска.

Контракт

Гарантии

  • Катсцена одна. Открытие новой сначала доводит идущую до конца пролётом; её OnShowFinished рассылается до начала открытия новой.
  • Без вложенности. Обращение запоминается и исполняется на LateUpdate оркестратора; показ не закрывается изнутри исполняемой цепочки.
  • Один OnShowFinished(ключ) на каждое обращение Open. OnShowOpening(ключ) и OnShowStarted(ключ) — не больше одного каждое и всегда раньше, в этом порядке.
  • Одна просьба «дальше» — один переход. Первая принятая просьба в фазе исполняется, повторные до её исполнения не действуют.
  • Закрытие одно. Все пути — завершающее звено, пролёт, сбой, выключение оркестратора — проходят через одно место: контент выгружается, данные показа сбрасываются, рассылается событие.
  • Пролёт при выключении. При любой форме выключения оркестратора оставшиеся этапы цепочки проходят до финала в режиме пролёта.
  • Контент выгружается при закрытии показа и при выключении оркестратора. Он выключается сразу, не дожидаясь уничтожения в конце кадра: фазу следующего показа не получит.
  • Номер фазы пишется в одном месте. CutsceneControl закрыт ключом владельца шины; фазу сообщает держатель слота.
  • События привязаны к показу и этапу. Звено чужой цепочки и автопереход от уже пройденной фазы на идущий показ не действуют.
  • Устаревшая загрузка ни на что не влияет. Результат отменённой загрузки — и успех, и сбой — отбрасывается.
  • Шина не зависит от оркестратора. Она знает только, что слот занят.

Дисциплина

  • Катсценой управляет один источник. Пакет рассчитан на одну несостязательную систему воспроизведения: сценарий, UI либо игровая логика ведут катсцену по очереди, а не наперебой. Обработчики событий показа, которые в ответ на событие сами открывают, пропускают или двигают катсцены и этим перебивают друг друга, — вне штатного использования (см. «Ограничения»).
  • Оркестратор один. Слот шины единственный; второй оркестратор отклоняется с ошибкой.
  • Состояний свитчера контента — «число фаз + 1», порядок совпадает с порядком этапов.
  • На корне префаба контента — DataStorage.
  • Источник автоперехода стоит только в фазах с автопереходом.
  • Цепочка катсцены соблюдает правила проверки.

Ограничения

  • Результат обращения виден не сразу после вызова, а после LateUpdate оркестратора.
  • Префаб, загрузка которого завершается сразу (прямая ссылка, прогретый кэш), запускается в том же проходе, что и открытие: состояние Loading тогда не доживает до конца кадра.
  • Разные обращения одного кадра исполняются в порядке шагов, а не в порядке прихода.
  • Состязательные обращения из обработчиков событий показа не поддерживаются. Примеры того, что тогда возможно:
    • обработчик OnShowFinished зовёт Skip ровно в момент, когда открытие, пришедшее из другого обработчика, закрывает идущую катсцену, — открытие получает два OnShowFinished (один с пустым ключом и ошибкой «пустой ключ» в логе), и IsActive может стать ложным при идущем показе;
    • OnShowFinished отклонённого открытия приходит кадром позже, уже после OnShowOpening другой катсцены, — подписчик, который ведёт признак «катсцена открыта» по этой паре без сверки ключа, закроет его раньше времени;
    • исключение одного подписчика прерывает катсцену и вместе с ней отменяет открытие, запрошенное другим подписчиком.
  • Рассогласование фаз и состояний видно, только когда фаз больше, чем состояний. Лишние состояния не обнаруживаются.
  • Запись цепочки должна быть MultiInstance (так создаёт её LogicChainPreset). Для записи другого типа открытие отклоняется как «цепочка не найдена в базе».
  • Перезапустить текущую фазу нельзя: свитчер игнорирует повторную установку того же состояния.
  • Ключ в событии не различает два показа одной и той же катсцены подряд.
  • Команда «дальше» этап не проверяет: при частых командах цепочка может уйти вперёд спрайтового контента, и катсцена завершится раньше, чем он покажет последние фазы.
  • Проверка цепочки допускает переход без условия между фазами и несколько звеньев «Фаза» в этапе: фазы при этом идут в одном проходе, и обычный хэндлер контента промежуточную не показывает.
  • Цепочка, остановленная исключением, остаётся в реестре LogicChainsSystem: убрать её оттуда нечем. На показы она не влияет.
  • Отклонённый второй оркестратор сам слот не займёт, когда первый уйдёт, — его нужно включить заново.
  • Если оркестратор выключить из его собственного состояния Loading или On, его свитчер может остаться в этом состоянии до следующего включения: вложенную установку Off свитчер не принимает и пишет об этом ошибку в лог.

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

Ситуация Поведение
Open с пустым ключом Debug.LogError, OnShowFinished(ключ)
Open при пустом слоте Debug.LogError сразу, OnShowFinished(ключ) в конце кадра. Оркестратор, включившийся позже в том же кадре, это открытие не получит
Подписчик OnShowFinished открывает катсцену на каждое событие не больше одного открытия за кадр: отказ, порождённый обработчиком, рассылается следующим проходом
Ключа нет в индексе, не задан префаб, цепочки нет в базе Debug.LogError, OnShowFinished(ключ)
Цепочка не прошла проверку Debug.LogError с причиной, OnShowFinished(ключ)
Исключение при открытии (испорченная запись цепочки, драйвер базы) исключение в лог, OnShowFinished(ключ)
Open при идущей катсцене прежняя пролетает до конца (OnShowFinished), затем в том же проходе начинается загрузка новой
Open во время загрузки прежней загрузка отменяется (OnShowFinished), затем начинается загрузка новой
Два Open за кадр открывается последняя; первая получает OnShowFinished
Open, затем Skip в одном кадре открытие отменяется (OnShowFinished); идущая катсцена пролетает
Open из обработчика события показа запоминается; исполняется в том же проходе, если шаг открытия ещё впереди, иначе в следующем кадре
Оркестратор выключен, пока он запускает показ (из Awake контента, его хэндлеров, состояний свитчера) запуск прекращается, цепочка не запускается, контент убирается, OnShowFinished(ключ)
Сбой загрузки префаба, пустой префаб, нет DataStorage на корне Debug.LogError, контент выгружается, OnShowFinished(ключ)
Исключение при запуске показа (привязка данных контента, звено до первого ожидания) исключение в лог, показ закрывается, OnShowFinished(ключ); OnShowStarted не рассылается
Загрузка завершилась после отмены, в том числе сбоем результат отбрасывается, идущий показ не затрагивается
Next раньше nextDelay после входа в фазу не принимается
Next / Skip без открытой катсцены, Next до запуска первой фазы ничего
Next принят, а в том же проходе катсцену сменила другая просьба пропадает, новая катсцена первую фазу не проскакивает
Несколько Next за кадр из любых источников один переход
Next(фаза) с фазой, с которой цепочка уже ушла не принимается
CutsceneContentHandler.Next() от выключенного контента игнорируется
Звено после CutsceneComplete в последнем этапе исполняется при ещё открытом показе: показ закрывается, когда цепочка вернёт управление; при пролёте звено видит IsSkipping
Skip во время загрузки загрузка отменяется, OnShowFinished(ключ)
Skip дважды за кадр один пропуск
Исключение в подписчике события показа в лог; остальные подписчики событие получают; после OnShowOpening либо OnShowStarted катсцена прерывается в следующем кадре
Исключение в звене цепочки посреди показа цепочка остановлена; показ закрывается с ошибкой в лог, OnShowFinished(ключ)
Оркестратор выключен посреди показа пролёт до конца в момент выключения, выгрузка, слот освобождён
Оркестратор выключен звеном цепочки оставшиеся этапы проходят до финала в режиме пролёта; показ закрывается, когда цепочка вернёт управление
Оркестратор выключен и включён обратно в пределах одного прохода показ доходит до финала пролётом, слот снова за оркестратором
Оркестратор выключен контентом при выгрузке показ уже закрывается; повторного закрытия нет
Оркестратор выключен с неисполненной просьбой открытия OnShowFinished(ключ)
Второй оркестратор Debug.LogError, не регистрируется
Фаз больше, чем состояний свитчера контента в редакторе исключение в лог; в сборке Debug.LogError; состояние не меняется, показ продолжается
Новая фаза раньше switchDelay (CutsceneSpriteContentHandler) состояние выставляется, когда задержка истечёт; несколько фаз — по очереди, каждая со своей задержкой
Катсцена завершена, пока контент ждёт задержку контент выгружается, отложенное переключение не происходит
Пролёт не дошёл до завершающего этапа Debug.LogError, показ закрывается принудительно

Публичный API

namespace Vortex.Unity.CutsceneSystem.Bus
{
    public static class CutsceneBus
    {
        public static CutsceneControl Control { get; }
        public static bool IsSkipping { get; }
        public static bool IsActive { get; }      // открытие принято, контент загружается либо показ идёт

        public static event Action<string> OnShowOpening;    // параметр — ключ катсцены
        public static event Action<string> OnShowStarted;    // параметр — ключ катсцены
        public static event Action<string> OnShowFinished;   // параметр — ключ катсцены

        public static void Open(string key);      // ключ — идентификатор записи LogicChain
        public static void Next();                // команда извне, с защитой от дребезга
        public static void Next(int phase);       // автопереход от контента; phase — показанная фаза
        public static void Skip();
    }
}

namespace Vortex.Unity.CutsceneSystem.Models
{
    public class CutsceneControl : IReactiveData
    {
        public IntData Phase { get; }             // 0 — фаз ещё не было
        public event Action OnUpdateData;         // номер фазы изменился
    }

    public enum CutsceneStageState { Off, Loading, On }
}

namespace Vortex.Unity.CutsceneSystem.LogicChains
{
    public class CutscenePhase : UnityLogicAction { }
    public class CutsceneComplete : UnityLogicAction { }
    public class CutsceneReadyCondition : UnityCondition { }
}

namespace Vortex.Unity.CutsceneSystem.Handlers
{
    public class CutsceneOrchestrator : MonoBehaviour { }     // настраивается в инспекторе

    public class CutsceneContentHandler : DataStorageView<CutsceneControl>
    {
        public void Next();                                   // автопереход
        protected virtual void ShowPhase(int phase);          // показать фазу; наследник может отложить
        protected void SetState(int phase);                   // перевести свитчер в состояние фазы
    }

    public class CutsceneSpriteContentHandler : CutsceneContentHandler { }   // switchDelay — в инспекторе
}