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:
- спрайтовая катсцена —
Sdk/CutsceneSystem/Example; - Spine-катсцена —
SpineExtensions/Cutscenes/Example.
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, всегда в одном порядке:
- Пропуск либо открытие поверх идущей катсцены — идущая доводится до конца пролётом, рассылается её
OnShowFinished. - Несостоявшиеся открытия получают
OnShowFinished— те, что накопились к этому шагу. Отказ, порождённый обработчиком этого события, ждёт следующего прохода. - Открытие — отказ (
OnShowFinished(ключ)) либо начало загрузки иOnShowOpening(ключ). - Результат загрузки — создаётся контент, запускается цепочка, первая фаза уходит контенту,
OnShowStarted(ключ). - «Дальше» — сигнал цепочке; затем новая фаза уходит контенту либо показ закрывается.
Правила:
- Одна просьба «дальше» на фазу. Просьба держится до исполнения; повторные до этого момента ничего не добавляют. Игрок нажмёт ещё раз, автопереход сработает для своей фазы сам.
- «Дальше» — только то, что просили до прохода. Просьба, пришедшая во время исполнения (например, автопереход из состояния только что показанной фазы), исполняется следующим кадром.
- «Дальше» — только для своей катсцены и только после запуска первой фазы. Пока контент грузится и первый этап цепочки не отработал, любая просьба игнорируется. Просьба, принятая для одной катсцены, на другую не переходит.
- Без вложенности. Обработчик события и звено цепочки могут обращаться к шине: просьба запоминается и исполняется позже — в том же проходе, если её шаг ещё впереди, иначе в следующем кадре.
- Сбой не останавливает проход. Исключение на шаге пишется в лог; остальные шаги исполняются.
- Порядок шагов постоянный, а не порядок прихода. Разница видна, только когда в одном кадре пришли разные обращения:
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 — в инспекторе
}