NaniExtensions

Мост между фреймворком Vortex и визуальной новеллой Naninovel. Содержит подпакеты разных слоёв.

Назначение

• Трансляция настроек громкости Vortex в Naninovel
• Управление Nani-сценами из Vortex (пауза, стоп, сброс акторов)
• Многоканальная локализация (общий язык, диалоги, озвучка)
• Управление катсценами на Spine-анимациях через Nani-бэкграунды

Вне ответственности: Naninovel-скрипты, контент сцен, настройка Spine-ассетов.

Подпакеты

Активация всего семейства Nani-пакетов — через символ USING_NANINOVELL, который выставляется тогглом naninovellExt (SdkSettings, атрибут [DefineSymbol("USING_NANINOVELL")]).

---

Core

Namespace: Vortex.NaniExtensions.Core

NaniWrapper — статический класс с lazy-кешированным доступом к сервисам Naninovel через Engine.GetService<T>().

Доступные сервисы

AudioManager, StateManager, L10N, CommunityL10N, ScriptPlayer, BackgroundManager, CharacterManager, TextPrinterManager, ChoiceHandlerManager, UnlockableManager, UIManager, VariablesManager

Жизненный цикл

• [RuntimeInitializeOnLoadMethod] — подписка на GameController.OnNewGame, OnLoadGame, OnGameStateChanged
• OnNewGame → ScriptPlayer.Stop() + ResetNani() + VariablesManager.ResetAllVariables()
• OnLoadGame → ScriptPlayer.Stop() + ResetNani()
• GameStates.Off/Win/Fail → ScriptPlayer.Stop() + ResetNani()

API

NaniSessionService

Адаптер Naninovel.Engine под контракт IGameSessionService из Sdk/Core. Регистрируется автоматически через [RuntimeInitializeOnLoadMethod]. После регистрации GameController дожидается Engine.Initialized перед каждым переходом в Play (после NewGame и OnLoad). До этого ожидание было жёстко зашито в Sdk/Core — теперь Sdk/Core не знает о Naninovel, и зависимость живёт исключительно здесь.

public sealed class NaniSessionService : IGameSessionService
{
    public bool IsReady => Engine.Initialized;
    public string Name => "Naninovel.Engine";
}

LogicChainsExt — NaninovelInitialized

Условие для логических цепочек (LogicChainsSystem), лежит в Core/LogicChainsExt/. Наследник UnityCondition, ждёт Engine.Initialized (через Engine.OnInitializationFinished).

Симметрично условию SystemsLoaded из ru.vortex.unity.logicconditions (которое ждёт App.Running): поставленные на один коннектор вместе они дают конъюнкцию — переход цепочки происходит только когда готовы обе подсистемы, и Vortex, и Naninovel, независимо от того, кто финишировал первым. Типовое применение — этап «Waiting Loading» цепочки-загрузчика приложения (детальный пример — в README LogicChainsSystem (Unity)).

Появляется в дропдаунах условий цепочки автоматически, пока подключён ru.vortex.nani.core.

---

AudioSystem

Namespace: Vortex.NaniExtensions.AudioSystem, Audio

NaniVortexAudioConnector

Трансляция настроек громкости каналов Vortex → Naninovel.

• Каналы (bgm, sfx, voice, voiceCutscene) загружаются из AudioChannelsConfig через partial-расширение AudioChannelsConfigExtNani
• При GameStates.Off — изменение настроек сразу проецируется в Nani
• При запущенной игре — только через явные вызовы GetNaniBgmVolume(), GetNaniSfxVolume(), GetNaniVoiceVolume()
• SetCutsceneMode(bool) — переключает источник громкости голоса между voiceChannel и voiceCutsceneChannel

AudioNaniController

Управление Nani-аудио из Vortex.

AudioChannelsConfigExtNani

Partial-расширение AudioChannelsConfig (сборка ru.vortex.unity.audiosystem.ext). Добавляет 4 поля с атрибутом [AudioChannelName] для маппинга Nani-каналов на Vortex-каналы.

NaniVoicePlayBus

Шина событий начала/завершения реплики персонажа. Объединяет два источника — ITextPrinterManager и IAudioManager — в единый контракт:

public static event Action<string> OnVoiceStart;   // authorId говорящего
public static event Action<string> OnVoiceStop;    // authorId говорящего

Воспроизведение voice детектируется поллингом IAudioManager.GetPlayedVoice(). Шина корректно ловит:

• конец voice (path → null);
• смену voice на другого актора (pathA → pathB) даже без null-окна между ними;
• «тихий переход» (тот же автор продолжает с новой voice-дорожкой — аниматор остаётся в Forward, ни Stop, ни Start не эмитятся);
• реплику без voice — Stop эмитится в PrintFinished, чтобы подписчик не залипал в состоянии «говорит» при отсутствии следующей PrintStarted (конец диалога, пауза на выбор).

Алгоритм:

1. OnPrintStarted — закрытие предыдущей реплики (если без voice), эмит OnVoiceStart, старт/продолжение поллинга, немедленная реконсиляция через PollVoice() (voice мог уже играть к моменту события: @print awaitит PlayVoice до фаер'инга).
2. Поллинг через TimeController.AddCallback ловит любые transitions path и эмитит OnVoiceStop / запоминает нового автора как cached.
3. OnPrintFinished — OnVoiceStop, если у завершившейся реплики не было собственной voice. Если voice играет — закрытие через поллинг (voice имеет право продолжаться после печати текста).
4. OnNaniStop / App.OnExit — FlushAll, закрытие всех открытых реплик.

Жизненный цикл: подписки в App.OnStart, отписка в App.OnExit. Не требует регистрации/инициализации со стороны проекта.

---

CutsceneSystem

Namespace: Vortex.NaniExtensions.CutsceneSystem, Vortex.NaniExtensions.CutsceneSystem.Models

Контроллер Spine-анимированных катсцен, отображаемых как Naninovel SpineBackground.

CutsceneController

Статический контроллер. Жизненный цикл:

Open(key) → загрузка CutsceneData → SpineBackground → LoadPhase → [NextPhase]* → Close

Фазы:

• Каждая CutscenePhase — анимация (looped/не looped) + опциональный ambient-звук
• Не looped-анимации автоматически переходят к следующей фазе
• Spine-события (Event) маппятся на звуки через EventToAudioData

Реакция на GameStates:

• Play → timeScale = 1, возобновление звуков
• Paused → timeScale = 0, остановка всех звуков
• Off → Close()

Модели

CutsceneData.SyncWithSpine() — Editor-кнопка: синхронизирует фазы и события с SkeletonDataAsset.

---

Misc

Namespace: Vortex.NaniExtensions.Misc Сборка: ru.vortex.nani.misc

Точечные хэндлеры для интеграции Nani-сцены с проектным UI и логикой. Каждый — самостоятельный MonoBehaviour, вешается на UI-объекты сцены и работает поверх NaniWrapper/NaniVoicePlayBus.