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

С чего начать

Настройки проекта

Откройте Edit → Project Settings → World Graph Editor. Здесь можно задать:

• Прозрачность фона нод в окне графа;
• Режим подсветки портов в Hierarchy (имена и цвета, только имена или без подсветки);
• Расширения главного тулбара Unity: кнопку быстрого открытия префаба Transition Manager (подпись TM), выпадающий список сцен с режимами Neighbours (соседи по графу для активной сцены), Build Settings и All Scenes;
• Массив кастомных тестов валидации сцен;
• Force-refresh affected scenes on graph save — если включено, при сохранении графа все сцены, затронутые изменением портов, по очереди открываются и в них принудительно обновляются компоненты ITransitionComponent. Это нужно для предотвращения сброса значений в PortsDropdown при переименовании портов в графе;
• Use Custom Transition Manager и поле Container — переключение на собственную реализацию TransitionManager.

Создание WorldGraphContainer

1. В папке проекта создайте WorldGraphContainer:
   • ПКМ → Create → World Graph Editor → World Graph Container;
2. Дважды нажмите ЛКМ по созданному объекту, чтобы открыть окно редактора.

Добавление сцен

Перетащите нужные сцены в открывшееся окно для создания нод. Каждая нода представляет собой сцену, а каждый порт на ноде обозначает переход на другую сцену.

warning

Избегайте дубликатов сцен, так как это приведёт к ошибкам. Дубликаты будут подсвечены красным.

Виды портов

При создании портов с помощью кнопки "+" на ноде открывается контекстное меню, позволяющее создать один из следующих портов:

• Left Passage, Right Passage, Top Passage, Bottom Passage — связующие порты (проходы), для создания связей, которые используются для соединения нод;
• Additional Port — порт, не предназначенный для связи, используется в случаях, требующих, например, реализации системы быстрого перемещения.

Создание портов и связей

1. Нажмите на "+" на выбранной ноде и создайте связующий порт;
2. Перетащите связь из порта первой ноды к середине второй ноды;
3. Если все сделано правильно, между нодами появится связь.

Таким образом, вы указали какими проходами сцены будут связаны между собой. Дополнительная настройка портов доступна в окне Inspector. Выберите нужную ноду, чтобы изменить её параметры.

warning

Каждый порт на ноде должен иметь уникальное название, а также оно не может быть пустым или состоять только из пробелов. В противном случае это приведет к ошибкам.

Типы возможных связей между нодами

• Undirected — Связь по умолчанию. Перемещение между проходами возможно в любом направлении;
• Shortcut — Указывает, что проход изначально доступен только с одной стороны (например, запертая дверь, открывающаяся с другой стороны). Может учитываться в собственной реализации портов и блокировать переход в зависимости от условий (bool флага);
• One-Way — Связь, позволяющая проходить исключительно в заданном направлении.

Тип связи настраивается в контекстном меню, которое открывается с помощью клика ПКМ по уже существующей связи.

Сохранение и настройка

Сохранение графа

Когда закончите работу с графом, нажмите кнопку "Save" чтобы сохранить его.

примечание

При сохранении, все несвязанные порты, кроме дополнительных (Additional Port), будут удалены, а так же, будет предложено добавить все использованные сцены в Build Settings, так как это необходимо для дальнейшей работы.

Настройка встроенного TransitionManager

1. Убедитесь, что менеджер существует по пути: Assets/WorldGraphEditor/Resources/TransitionManager. Если нет, создайте его с помощью пункта меню:
   • Tools → World Graph Editor → Create Transition Manager Prefab;
2. Перетащите сохранённый WorldGraphContainer в соответствующее поле в TransitionManager. Таким образом, вы указываете какой контейнер будет использоваться;
3. Установите AutoLoad в значение true. Это позволит менеджеру загружаться автоматически при старте игры;
4. Установите чекбокс в правой части поля PlayerPrefab в значение true и перетащите в него префаб игрока.

Благодаря этому на каждой сцене автоматически будет создаваться объект игрока. Если вам не подходит данный способ загрузки менеджера, см. Ручной запуск встроенного TransitionManager.

Настройка сцен

Для представления портов на сценах добавьте соответствующие компоненты.

По умолчанию доступны:

• Passage2D - Перемещает игрока к противоположному порту, опираясь на заданную связь в графе;
• Teleport2D - Перемещает игрока к любому другому существующему порту на графе.

Вы также можете задать позицию по умолчанию, добавив на сцену объект с компонентом DefaultSpawnPosition. Благодаря этому, если на сцене не будет найден выходной порт OutputTransitionComponent, игрок появится на этой позиции.

Настройка компонентов

• Passage2D
  • В поле AssignedPort выберите имя прохода, который будет соответствовать порту в графе.
• Teleport2D
  • В поле AssignedPort выберите имя прохода, который будет соответствовать порту в графе;
  • В поле GoTo выберите порт, к которому должен быть осуществлён переход.

подсказка

Каждый порт на сцене в поле AssignedPort должен ссылаться к одному порту на ноде.

При необходимости, вы можете написать собственные реализации.

Поведение в Play Mode

Ожидаемое поведение

• При запуске в DontDestroyOnLoad автоматически создаётся объект TransitionManager;
• При контакте с объектом порта, персонаж перемещается на другую сцену, в позицию соответствующую целевому порту.

Ошибки

Если целевой порт отсутствует на сцене:

• Объект игрока появится в позиции, заданной в DefaultSpawnPoint, или, если она не задана — в позиции (0, 0, 0)
• В консоль будет выведено сообщение об ошибке

warning

В консоль будет выведено предупреждение, если:

• При включенном встроенном TransitionManager:
  • TransitionManager отсутствует по пути:Assets/WorldGraphEditor/Resources/TransitionManager;
  • Поле Container в TransitionManager пустое.
• При включенном кастомном TransitionManager:
  • Поле Container в Project Settings пустое.
• Контейнер содержит в себе ошибки;
• Сцены в Build Settings были удалены, отключены или изменён их порядок.

В консоль будет выведена ошибка с инструкцией по её исправлению.

Оверлеи Scene View

В окне Scene доступны два встроенных оверлея пакета: Scene Inspector WGE и Screenshot Utility WGE. Их можно включить, закрепить и скрыть так же, как и другие оверлеи Scene View.

Scene Inspector WGE

Показывает краткий статус конфигурации Transition Manager и контейнера: назначен ли контейнер, нет ли ошибок в данных, совпадают ли сцены с Build Settings, а также какой TransitionManager используется — встроенный или собственный (Default / Custom). Для активной сцены выводится сводка по соответствию графу (в т.ч. наличие данных по сцене и портам). Внизу панели — кнопка Project Settings, открывающая Edit → Project Settings → World Graph Editor.

Screenshot Utility WGE

Служит для съёмки превью текущей сцены, которое затем используется в окне графа на ноде сцены. Задаются область кадра (позиция, размер, поворот), дистанция и тип камеры (перспектива / ортография), а также параметры изображения (разрешение, режим для текстур non-power-of-two). Настройки можно сохранить для этой сцены (Save Scene Preset), задать глобальный набор по умолчанию для сцен без своих настроек (Save as Global Default) или сбросить к встроенным значениям (Reset to Built-In). Кнопка Take Screenshot сохраняет изображение; в Scene View отображаются ручки для позиционирования и рамки кадра.

Если для текущей сцены отключён авто-захват (см. ниже), оверлей скрывает поля настройки кадра и показывает сообщение с кнопкой Enable Auto-Preview.

В окне графа на верхней панели есть кнопка Capture Scene Previews — пакетный (авто) захват превью для всех доступных сцен графа.

В инспекторе ноды (раздел Scene Preview) доступны кнопки Delete Preview (удаляет файл скриншота; неактивна, если файла нет) и Enable/Disable Auto-Preview (включает или отключает захват и отображение превью для конкретной сцены; поддерживает Undo/Redo). Если авто-захват отключён, нода на графе и инспектор не показывают превью для этой сцены, а сама сцена пропускается при пакетном захвате; уже сохранённый файл скриншота при этом не удаляется.

Валидация сцен

Помимо базовой проверки целостности данных (контейнер, соответствие Build Settings), пакет умеет запускать набор тестов по каждой сцене графа.

Встроенные тесты

Тест	Что проверяет	Статус при провале
Missing Ports	На сцене присутствуют ITransitionComponent для каждого порта из графа.	Warning
Ports Duplicates	На сцене нет двух ITransitionComponent с одинаковым Guid.	Error
Достижимость	Все сцены достижимы от стартовой по графу (алгоритм SCC).	Группы недостижимых сцен сохраняются в результат.

Запуск

• Вручную: Edit → Project Settings → World Graph Editor, кнопка Validate Project. Запускает встроенные и все добавленные пользовательские тесты по всем сценам графа, сохраняет результат в ассет ProjectValidationResult. Кнопка Open Result открывает результат валидации в окне инспектора.
• При сборке проекта: ValidationBuildProcessor (IPreprocessBuildWithReport) проверяет целостность контейнера и соответствие сцен Build Settings. При расхождении предлагает синхронизировать контейнер; при остальных ошибках сборка останавливается с сообщением. Полный набор тестов на сборке не запускается — для этого используйте Validate Project вручную.
• При сохранении графа: обновляются пути и build index сцен; пользовательские тесты при сохранении не запускаются.

Где смотреть результат

Результат хранится по пути: Assets/WorldGraphEditor/ProjectValidationResult.asset.

После запуска валидации, кнопка Open Result становится активной и открывает этот ассет в инспекторе для просмотра деталей.

Сам ассет хранит в себе ссылку на проверенный контейнер, флаги (_ignoreShortcuts, _considerAdditionalPorts) и результат проверки достижимости в виде SCC-групп.

Свой тест

Создаётся как ScriptableObject, наследованный от SceneTestBase (реализует ISceneTest) и содержит в себе следующие методы:

Метод	Описание
TestResult Run(in TestContext context)	Передает TestContext, вызывается каждый раз при загрузке новой сцены. Метод должен вернуть TestResult.
void Init()	Опциональный. Вызывается единожды, перед началом загрузки первой сцены. Нужен в случаях, требующих инициализацию или сброс предыдущих результатов.

Общий шаблон:

[CreateAssetMenu(menuName = "My Game/Validation/My Custom Test")]
public class MyCustomSceneTest : SceneTestBase
{
	public override TestResult Run(in TestContext context)
	{
		// context.SceneNodeData содержит данные ноды текущей сцены: порты, имя сцены, пути.

        if (/* условие провала */ false)
	        return new TestResult(TestStatusType.Warning, "Описание проблемы для отчёта.");

        return new TestResult(TestStatusType.Passed, "OK");
    }
}

Конкретный пример:

Допустим, в вашем проекте есть коллекционные предметы с уникальными идентификаторами и вам нужно удостовериться, что во всем проекте не встречаются два уникальных идентификатора. В таком случае, тест мог бы выглядеть так:

[CreateAssetMenu(menuName = "My Game/Validation/My Coin Test")]
public class CoinsIDTest : SceneTestBase
{
    private HashSet<string> _coinsIds;

    public override void Init()
    {
        _coinsIds = new HashSet<string>();
    }

    public override TestResult Run(in TestContext context)
    {
        var coins = FindObjectsByType<Coin>(FindObjectsSortMode.None);

        foreach (var coin in coins)
        {
            if (!_coinsIds.Add(coin.Id))
                return new TestResult(TestStatusType.Error, $"Coin with ID [{coin.Id}] already exists.");
        }

        return new TestResult(TestStatusType.Passed, "All coin IDs are unique.");
    }
}

Возможные статусы прохождения теста:

public enum TestStatusType
{
    Passed,
    Warning,
    Error
}

После создания ассета добавьте его в массив Custom Tests в Edit → Project Settings → World Graph Editor (раздел Validation). При следующем нажатии Validate Project ваш тест будет вызван для каждой сцены графа.

примечание

Контракт ISceneTest живёт под #if UNITY_EDITOR — тесты исполняются только в редакторе и не попадают в билд.

Поддержка Addressables

Поддержка Addressables включается автоматически, если в проекте установлен пакет com.unity.addressables — это реализовано через versionDefines в asmdef-файлах пакета, которые подключают define WGE_ADDRESSABLES. Включать что-либо вручную не нужно; если пакет не установлен, функция просто не активна и ошибок компиляции не возникает.

Чтобы сцена загружалась через Addressables, добавьте её в Addressables Groups обычным способом (Window → Asset Management → Addressables → Groups). Граф сам определяет это через настройки Addressables.

Визуальные признаки в редакторе:

• На ноде графа появляется бейдж "ADR" (в левом верхнем углу) с тултипом Loaded via Addressables и адресом, если он задан.
• В инспекторе ноды (Scene Node Data) появляется уведомление: "This scene is loaded via Addressables at runtime. It is not required in Build Settings."

примечание

Сцены, помеченные как Addressable, исключаются из требования присутствовать в Build Settings — их пропускают и валидатор, и автодобавление сцен при сохранении графа.

На уровне API у графа (WorldGraph и EditorGraph) доступен метод TryGetSceneDataByAddress(string address, out TSceneData data) — он существует только при включённых Addressables (#if WGE_ADDRESSABLES).

Встроенный TransitionManager подхватывает Addressables автоматически: при переходе он смотрит RuntimeTransitionData.GetTargetSceneAddress() — если адрес задан, сцена грузится через Addressables.LoadSceneAsync(address, LoadSceneMode.Single); если нет — fallback на SceneManager.LoadSceneAsync(buildIndex). Никакой ручной настройки переключения не требуется.

примечание

Если вы пишете собственный TransitionManager, Addressables-загрузку нужно реализовывать самостоятельно — адрес сцены доступен через RuntimeTransitionData.GetTargetSceneAddress() / SceneRuntimeData.GetAddress().