Установка и развёртывание Vortex Framework

Пошаговая инструкция установки Vortex в Unity-проект и базовой настройки конфигов после установки.

---

Шаг 1. Установка

Vortex можно установить двумя способами — через Unity Asset Store или из локального .tgz-архива.

Вариант A. Через Unity Asset Store

1. Открыть страницу Vortex Framework в Asset Store и нажать Add to My Assets.
2. В Unity открыть Window → Package Manager.
3. В выпадашке выбрать Packages: My Assets.
4. Найти Vortex Framework, нажать Download, затем Import.
5. Дождаться импорта и компиляции.

Вариант B. Из .tgz-архива

Подходит для приватных сборок и обновлений вне Asset Store.

1. Открыть Window → Package Manager.
2. Нажать + в верхнем левом углу → Add package from tarball...
3. Выбрать файл ru.tottenhurt.vortex-X.Y.Z.tgz.
4. Дождаться импорта и компиляции.

После установки пакет появится в списке как Vortex Framework (ru.vortex.framework).

---

Шаг 2. Проверка внешних зависимостей

Обязательные

Опциональные

Если Addressables не установлен — соответствующие пакеты Vortex (AssetCacheSystem, Database-драйверы на Addressables) автоматически выключаются через defineConstraints в asmdef. Можно работать с Resources-драйвером Database или вообще без Database.

Если в Console красные ошибки про Sirenix.OdinInspector или Cysharp.Threading.Tasks — соответствующая обязательная зависимость не установлена.

---

Шаг 3. Авто-создание Core-ассетов

После первой компиляции Vortex автоматически создаст все системные ассеты в одной папке:

• Assets/Resources/Settings/ — все конфиги Vortex:
  • ICoreAsset-наследники (создаёт CoreAssetsController): SdkSettings, DriverConfig, AudioChannelsConfig, AssetCacheSettings и т. д.
  • SettingsPreset-наследники (создаёт SettingsDriver): StartSettings, DatabaseSettings и т. д.

Если ассеты не появились — открой меню Tools → Vortex → Debug → Check Core Assets для ручного запуска.

Авто-создание можно выключить через Edit → Preferences → Vortex/Editor (рекомендуется отключать только если ассетов слишком много и Editor зависает на старте).

---

Шаг 4. Настройка SdkSettings

Файл: Assets/Resources/Settings/SdkSettings.asset

Назначение: управляет включёнными SDK-пакетами Vortex через scripting define symbols (USING_NANINOVELL, USING_SPINE, и т. п.). Каждое поле — bool-toggle, связанный с конкретным define.

Что делать:

1. Открыть ассет.
2. Включить toggle'ы тех SDK-пакетов, которые нужны проекту:
   • Naninovel
   • MapLevels
   • Quests
   • RoofTransparency
   • SaveLoad
   • Spine
3. Нажать Apply Changes — defines синхронизируются с PlayerSettings.
4. После смены платформы (iOS/Android/PC) defines актуализируются автоматически.

Кнопки:

• Apply Changes — записать состояние тоглов в PlayerSettings → Scripting Define Symbols.
• Reload States — синхронизировать тоглы с текущим состоянием Scripting Define Symbols.

---

Шаг 5. Настройка DriverConfig

Файл: Assets/Resources/Settings/DriverConfig.asset

Назначение: связка «системный контроллер ↔ драйвер». Vortex использует Driver-pattern (canonical для всех систем: AudioSystem, VideoSystem, LocalizationSystem и т. п.) — конфиг хранит whitelist пар.

Что делать:

1. Открыть ассет.
2. Нажать Reload — Vortex просканирует все ISystemController-наследники и заполнит таблицу.
3. Для каждой системы выбрать конкретный драйвер из выпадашки Driver Type.
4. Нажать Save Config — сгенерируется автогенерированный файл Assets/DriversGenericList.cs с whitelist'ом.

Поле Искать драйверы только в ru.vortex* пакетах:

• true (по умолчанию) — поиск ограничен Vortex-сборками. Если в проекте есть собственные драйверы, поставить false.

Важно: без сгенерированного DriversGenericList.cs системы не подцепят свои драйверы — рантайм будет молча работать без аудио/видео/локализации. Save Config обязателен.

---

Шаг 6. Настройка AudioChannelsConfig

Файл: Assets/Resources/Settings/AudioChannelsConfig.asset

Назначение: список аудио-каналов проекта. Каждый канал — отдельная шина громкости/mute, экспонируется в UI слайдерами громкости.

Что делать:

1. Открыть ассет.
2. Заполнить массив channels именами каналов. Типовой набор:

   Music
   Sfx
   Ambient
   Voice
   UI
   

3. Имена становятся идентификаторами для атрибута [AudioChannelName] в коде, привязок AudioChannelVolumeSlider в UI, и для драйвера AudioDriver.

При изменении массива AudioDriver.ResetChannels() вызывается автоматически — runtime-каналы пересоздаются.

---

Шаг 7. Настройка StartSettings

Файл: Assets/Resources/Settings/StartSettings.asset

Назначение: стартовая сцена при запуске из любого места в редакторе. Только для удобства разработки, в build не влияет.

Что делать:

1. Открыть ассет.
2. В поле Start Scene выбрать из выпадашки нужную сцену (показываются все сцены в Build Settings).
3. Запуск Play-mode из любой сцены автоматически переключится на стартовую.

---

Шаг 8. Добавление префаба System на стартовую сцену

Префаб: Packages/Vortex Framework/_Prefabs/System.prefab

Назначение: готовая базовая инфраструктура Vortex для рантайма. Префаб содержит:

System
├── Audio
│   ├── SoundsPool
│   │   └── AudioSource         ← шаблон для пула SFX-источников
│   ├── Music                   ← AudioSource для основного музыкального канала
│   └── CoverMusic              ← AudioSource для перехватывающей музыки (cutscene, заставка)
└── AppState                    ← MonoBehaviour-обработчик жизненного цикла приложения

Что делать:

1. Открыть стартовую сцену проекта (ту, что указана в StartSettings).
2. Найти префаб System в Project window (Packages/Vortex Framework/_Prefabs/System.prefab).
3. Перетащить префаб на корень иерархии сцены.
4. Не разрывать связь с префабом — обновления Vortex дойдут до проекта только через сам префаб.

Что префаб даёт:

• AppState — слой управления жизненным циклом приложения: переходы между состояниями (Starting/Running/Loading/Paused/Stopping), реакция на focus/pause, событие выхода. Без него App.OnExit и подобные шины не сработают.
• Audio/SoundsPool — пул объектов AudioSource для проигрывания SFX. AudioDriver инстанцирует копии шаблонного AudioSource под нужное количество одновременных звуков.
• Audio/Music — выделенный AudioSource для фоновой музыки канала Music.
• Audio/CoverMusic — выделенный AudioSource для перехватывающей музыки (например, музыка кат-сцены поверх обычной).

Все три аудио-объекта подцепляются к каналам, объявленным в AudioChannelsConfig (шаг 6).

Важно: на сцене должен быть только один экземпляр System-префаба. При наличии нескольких — AppStateHandler и AudioDriver могут работать с непредсказуемым поведением.

---

Шаг 9. Настройка пакетов SDK

После включения SDK-пакета в SdkSettings (шаг 4) и перекомпиляции — настроить связанные с пакетом ассеты.

Пункты 9.1 и 9.2 актуальны только при установленном Addressables-пакете. Без него соответствующие ассеты не создаются автоматически (asmdef отключены через defineConstraints: ["ENABLE_ADDRESSABLES"]).

9.1. Database — Addressables (опционально)

Файл: Assets/Resources/Settings/DatabaseSettings.asset

Требования:

• Установлен пакет com.unity.addressables.
• Define ENABLE_ADDRESSABLES активен (выставляется автоматически при первой настройке Addressables-группы).
• В проекте создана хотя бы одна Addressable Group через Window → Asset Management → Addressables → Groups.

Что делать:

1. Перейти в Addressables Groups, назначить нужным ассетам labels (например, database, characters, items).
2. Открыть DatabaseSettings.asset.
3. В поле Database Labels выбрать из выпадашки те labels, по которым DatabaseDriver (Addressables) загрузит свои Records при старте.

Dropdown показывает только labels, реально присвоенные хотя бы одному ассету.

Если labels не указаны — Database останется пустой, все Database.GetRecord<T>(id) вернут null.

Альтернатива без Addressables — Resources-драйвер Database (ассеты лежат в Resources/, грузятся по имени папки). См. README пакета Vortex.Unity.DatabaseSystem.

9.2. AssetCache — кэш Addressables (опционально)

Файл: Assets/Resources/Settings/AssetCacheSettings.asset

Требования:

• Установлен пакет com.unity.addressables.
• Define ENABLE_ADDRESSABLES активен.

Без Addressables пакет AssetCacheSystem не компилируется (asmdef содержит defineConstraints: ["ENABLE_ADDRESSABLES"]) — ассет не создаётся, использовать его невозможно.

Что делать:

1. Открыть AssetCacheSettings.asset.
2. Настроить:
   • Survivor Capacity (default 32) — размер LRU-буфера освобождённых, но не выгруженных ассетов. Чем больше — тем больше памяти, но меньше повторных загрузок при возврате на предыдущие экраны/сцены.

Типовые значения:

• мобильный проект с ограничением памяти — 16-32;
• desktop / богатые ассеты — 64-128;
• стресс-сценарии (много возвратов на одни и те же эффекты/UI) — увеличивать выше.

---

Шаг 10. UI-примитивы (опционально)

Папка: Packages/Vortex Framework/_Prefabs/UIPrimitives/

Назначение: сбалансированный образец базовых UI-блоков для быстрого старта. Все примитивы построены на штатных компонентах Vortex (AdvancedButton, UIComponent, TweenerHub, UserInterface) и могут использоваться как точка отсчёта при сборке UI проекта.

Состав:

К префабам приложены TweenPreset-ассеты (ButtonTween.asset, UserInterfaceTween.asset) — их используют сами префабы, отдельной настройки не требуют.

Способы использования (любой допустим, выбирается по нуждам проекта):

1. Drag & drop напрямую — перетащить префаб из пакета в сцену. Связь с пакетом сохраняется, обновления Vortex доезжают автоматически. Подходит для прототипов и небольших проектов.
2. Prefab Variant — Right-click → Create → Prefab Variant. Override-правки локальны для варианта, базовый префаб продолжает обновляться вместе с Vortex.
3. Копирование в проект (рекомендуется для долгоживущих проектов) — скопировать префаб из Packages/Vortex Framework/_Prefabs/UIPrimitives/ в Assets/..., после чего связь с пакетом разорвана. Это даёт устойчивость к обновлениям Vortex и полную свободу правок, но снимает с примитивов автообновления.

Примечание: UI-примитивы — образец, а не обязательный канон. Никакая система Vortex от них не зависит. Можно использовать их, заменить своими аналогами или собирать UI с нуля.

---

Проверка корректности установки

После всех шагов запусти Play и проверь в Console отсутствие ошибок инициализации. В Debug-режиме (включается через Tools → Vortex → Debug → ... или флаг DebugMode в SettingsModel) каждая система пишет лог об успешной инициализации:

[Database] Initialized. Loaded N records.
[Settings] Initialized. SettingsModel populated.
[AssetCache] Initialized. SurvivorCapacity=32.
...

Если какая-то система молчит или пишет error — проверь:

1. Соответствующий toggle в SdkSettings.
2. Назначен ли драйвер в DriverConfig и нажат ли Save Config.
3. Существует ли соответствующий *Settings-ассет в Resources/Settings/.

---

Типичные проблемы