Wiki
Плагин для Unreal Engine
Плагин uVersion для Unreal Engine: нативный контроль версий в редакторе, diff Blueprint, аудит Project Health и два правила, которые чаще всего блокируют отправку.
Предварительные требования
.uversion/, поднимаясь от проекта вверх; если он не находит её и если ранее не был
сохранён ни один токен аутентификации, он вообще не активируется, и Unreal остаётся без контроля версий.
Это не сбой: именно это мешает ему навязываться вашим проектам, которые не версионируются с
uVersion. Открывайте проект из папки, склонированной desktop-клиентом, а не из копии, положенной
в другом месте.
Установка
Плагин uVersion распространяется в виде предварительно скомпилированного бинарного файла и управляется desktop-клиентом. Никакой компиляции с вашей стороны, никаких исходных файлов, с которыми нужно возиться. Он никогда не версионируется: он не приходит вместе с репозиторием и не должен отправляться в него. Каждая машина устанавливает бинарный файл, соответствующий ЕЁ версии Unreal и ЕЁ системе.
Поддерживаемые версии Unreal: 5.6 и выше.
1. Открыть workspace в desktop-клиенте
Установите desktop-клиент uVersion, войдите, затем откройте workspace, который содержит проект Unreal. Всё происходит из клиента: нет никакого архива, который нужно скачивать, и никакого, который нужно вручную распаковывать в проект.
2. Дать клиенту обнаружить проект
Клиент ищет ваш .uproject (файл, который описывает проект Unreal) под корнем
workspace, при условии, что он не зарыт глубже трёх уровней. Как только он его находит, вверху вкладки workspace появляется панель
Unreal, и он кладёт плагин, соответствующий вашей версии
Unreal, в Plugins/uVersion/. Значок слева несёт состояние плагина и его номер
версии: там же читаются и обновления.
3. Открыть проект в Unreal
Плагин активен сразу же. Ничего не нужно отмечать в окне Plugins редактора, ничего не нужно перезапускать: если он отсутствовал, значит клиент его ещё не положил, а не что его осталось включить.
Позже: обновления
Desktop-клиент проверяет наличие новых версий при открытии проекта и периодически после. Внимание, автоматическая проверка делает не одно и то же в двух случаях:
- Плагин отсутствует: он устанавливается, ничего у вас не спрашивая. Именно это делает первый запуск незаметным.
-
Плагин уже есть, но устарел (новая версия или смена версии Unreal): клиент
лишь уведомляет вас. Он никогда не заменяет установленный плагин сам по себе. Значок
панели Unreal тогда переключается на
Update ready.
Чтобы применить обновление: закройте редактор Unreal, затем нажмите на значок. Загруженный плагин
нельзя заменить на диске; если редактор ещё открыт, значок показывает
Restart UE.
Первое подключение
В обычном случае подключать нечего. Плагин выбирает себя сам в качестве поставщика контроля версий, как только обнаруживает workspace uVersion вокруг проекта или уже сохранённый токен. Ваши учётные данные берутся из desktop-клиента, без повторного ввода. Открыть проект достаточно.
Три шага ниже нужны только в том случае, если этот автоматический выбор не произошёл.
1. Открыть меню Revision Control
Оно находится внизу справа в строке состояния редактора, а не в верхних меню. Оно
открывается вверх и несёт действия Unreal, среди них Submit Content, плюс раздел
uVersion с нашим пунктом Audit Project (Project Health). Возьмите
Connect to Revision Control.
2. Выбрать uVersion в списке Provider
Открывается окно Revision Control Login. Разверните Provider и возьмите uVersion. Когда workspace распознан, окно само сообщает об этом зелёным (Automatically configured from workspace), а поля Workspace, Server URL и Username уже заполнены: вводить нечего.
3. Подтвердить через Accept Settings
Кнопка Accept Settings внизу окна применяет выбор и закрывает окно. Строка состояния тогда показывает Connected to, за которым следуют имя репозитория и ваш логин. Выбор запоминается: следующие открытия проекта не будут проходить через это снова.
Зарезервировать asset, затем отправить его
Полный путь из редактора, на файле контента. Код же никогда не отправляется отсюда: см. Код идёт через desktop-клиент.
1. Посмотреть состояние asset перед началом
Каждая миниатюра в Content Browser несёт значок, который говорит, на каком этапе asset: зарезервирован вами, зарезервирован кем-то другим или устарел по сравнению с сервером. Всплывающая подсказка даёт полную фразу, например File is out of date, sync to get the latest version. В этом случае сначала синхронизируйте (правый клик, Revision Control, Sync): начинать работать над устаревшей версией значит готовить конфликт.
2. Зарезервировать asset
Правый клик по asset, подменю Revision Control, затем Check Out. Здесь есть всё: Sync, Check Out, Check In, History, Diff Against Depot, Revert, как с любым другим поставщиком Unreal. Художникам не нужно учить ничего нового.
На практике вам часто не придётся ничего делать: как только вы изменяете asset, плагин ставит блокировку на стороне сервера сам, без ручного checkout.
3. Сравнить перед отправкой
Diff Against Depot открывает стандартный визуальный инструмент сравнения редактора, в том числе на Blueprint: две ревизии показаны бок о бок, а добавленные, удалённые или изменённые узлы обведены. Работает на любом коммите истории, из History.
4. Отправить
Правый клик, Revision Control, Check In по выбору, или Submit Content в меню строки состояния, чтобы отправить всё сразу. Окно перечисляет затронутые файлы, включая удаления, и требует описание. В момент отправки плагин чистит redirector, оставленные вашими переименованиями, и запускает активные правила валидации: правило в состоянии error останавливает отправку и называет виновные файлы.
Что плагин делает в Unreal
Project Health: аудит проекта
Меню Revision Control в строке состояния содержит пункт
Audit Project (Project Health). Он проходит по реестру assets проекта,
не загружая ни одного asset, и выдаёт отчёт о здоровье: именование, структура папок,
зависимости, осиротевший контент, издержки. Он работает офлайн (отчёт записывается под
Saved/uVersionAudit) и отправляет его на сервер, когда вы подключены, где он питает
вкладку Project Health desktop-клиента.
Очистка redirector
Когда вы переименовываете или перемещаете asset, Unreal оставляет за собой redirector: маленький файл-перенаправитель, который указывает старый путь на новый, чтобы assets, которые ссылались на старое имя, продолжали работать. Они быстро накапливаются и в итоге делают дерево нечитаемым. Плагин обнаруживает их и чистит в момент checkin, обновляя ссылки во всех затронутых assets.
Проверка перед checkin
Плагин умеет запускать серию проверок отправленных файлов: компиляция Blueprint, соглашение об именовании, размер текстур, настройки импорта, отсутствующие зависимости, циклические зависимости, осиротевшие assets, дубликаты, сложность материалов. Всего девять правил. Правило в состоянии error блокирует отправку, правило в состоянии warning разрешает её после подтверждения.
Согласование при запуске
При открытии проекта плагин сравнивает состояние ваших assets с сервером. Он проходит по Content/
и по Content/ плагинов проекта, и автоматически резервирует всякий asset, найденный
доступным для записи на диске, который ещё не был зарезервирован. Замысел в том, чтобы вас защитить: файл, который вы начали изменять,
не может быть перехвачен товарищем по команде между двумя сессиями.
Код идёт через desktop-клиент, а не через Unreal
Плагин отказывает в отправке файлов кода: .cpp, .h,
.hpp, .c и .cs. Попытка останавливается на блокирующем окне, которое
называет виновные файлы. Это не дефект: desktop-клиент компилирует перед отправкой и публикует
бинарники редактора, которые ваши товарищи по команде получают при sync. Коммит кода, ушедший из редактора, прошёл бы
мимо обоих и приостановил бы раздачу бинарников для всей команды.
Поэтому отправляйте свой код из desktop-клиента. А файлы контента остаются совершенно свободны уходить из Unreal.
.uasset. Сообщение говорит вам сначала отправить ваш код из
desktop-клиента.
Это самая частая блокировка, и она охотно падает на того, кто не пишет код: достаточно, чтобы исходный файл был сделан доступным для записи на диске, чтобы согласование при запуске зарезервировало его само. Причина реальна: asset, сохранённый против неотправленного кода, ломает всех, кто его синхронизирует, поскольку у их бинарников нет кода, от которого он зависит.
Разблокировка: откройте вкладку Pending desktop-клиента, список My Pending Changes, найдите файлы кода и сделайте Checkin Selected, если вы их изменили, или Revert, если вы их не трогали. Ваша отправка контента после этого уходит нормально. Может понадобиться несколько секунд, пока редактор обновит своё представление о блокировках.
Частые проблемы
Никакого меню uVersion: редактор игнорирует контроль версий
Проект, вероятно, не находится в workspace uVersion. Проверьте, что папка .uversion/ существует
в корне склонированной папки, и что вы действительно открываете проект из этой папки, а не из копии, положенной
в другом месте.
« Failed to connect to source control »
Проверьте, что desktop-клиент запущен и что вы в него вошли: именно он держит ваши учётные данные и умеет говорить с самоподписанным сервером. Если аккаунт-владелец workspace не вошёл в клиент, плагин отказывается работать под другой личностью, и это сделано намеренно.
Отправка отклонена, хотя я не трогал никакого кода
Вы держите резервирование файла кода. См. Код идёт через desktop-клиент.
Мне нужен asset, который заблокировал кто-то другой
Это не запрашивается из Unreal: у плагина нет функции запроса на снятие. Пройдите через desktop-клиент, вкладка Pending, раздел Other Users' Locks, кнопка Request Release на строке файла. Держатель получает запрос в виде карточки на доске Production.
Плагин не обновляется
Это ожидаемое поведение: автоматическая проверка устанавливает отсутствующий плагин, но об обновлении она лишь
сигнализирует. Закройте редактор Unreal (загруженный плагин нельзя заменить), затем нажмите на значок
Update ready в панели Unreal desktop-клиента, чтобы применить его.
Правило валидации никогда не срабатывает
Девять правил поставляются отключёнными. Администратор должен включать их для каждого проекта из вкладки Rules панели Admin.