Commandlet в Unreal Engine — что это и зачем?

Во время разработки на Unreal Engine могут возникнуть задачи, которые требуют автоматизации, повторяемых действий или пакетной обработки. Эти задачи могут варьироваться от компиляции Blueprint'ов до упаковки игры на удаленном сервере. В таких случаях на помощь приходят Commandlet'ы.

Я на них наткнулся случайно, когда при запаковке проекта было много ошибок и было нужно пройтись по всем Blueprint - классам в проекте чтобы проверить, правильно ли они компилируются после изменений в C++.

Что Такое Commandlet?

Commandlet — это специализированный класс в UE, предназначенный для выполнения определённых задач в автоматизированном режиме. Командлеты выполняются в «сырой» среде, в которой не загружается игра, не загружается клиентский код, не загружаются уровни и не существуют актеры, что делает их быстрыми и удобными для сценариев автоматизации. Commandlet'ы могут быть использованы для выполнения различных задач, таких как:

• Компиляция всех Blueprint'ов в проекте.

• Подготовка (готовка) контента для конкретной платформы.

• Проверка целостности активов (assets) и исправление ошибок.

• Генерация пакетов и патчей.

• Запуск автоматических тестов.

Зачем использовать Commandlet?

Командлеты становятся особенно полезными, когда вам нужно:

• Автоматизация: Commandlet'ы позволяют автоматизировать рутинные задачи, такие как готовка ресурсов (ассетов) к запаковке, компиляция и их пересохранение. Например, вы можете создать сценарий, который ежедневно запускает Commandlet для проверки целостности вашего проекта.

• Пакетная обработка: С помощью Commandlet'ов можно обработать большой объём данных за один проход. Например, вы можете использовать команду для пересохранения всех пакетов вашего проекта после обновления движка.

• Скриптинг: Commandlet'ы отлично интегрируются с системами сборки и тестирования, такими как Jenkins или другие CI/CD инструменты. Вы можете легко написать скрипт, который запускает несколько командлетов подряд, обеспечивая автоматическую сборку проекта, тестирование и упаковку.

• Экономия ресурсов: Так как Commandlet'ы запускаются без загрузки полного пользовательского интерфейса Unreal Editor, они потребляют меньше ресурсов, что делает их идеальными для серверов и скриптовых задач.

Как Работают Commandlet?

Commandlet'ы запускаются из командной строки операционной системы с помощью UnrealEditor.exe. Общий синтаксис запуска Commandlet выглядит так:

UnrealEditor.exe [Path to .uproject] -run=[CommandletName] [Additional Parameters]

Важное уточнение: для читаемого запуска рекомендуется использовать UnrealEditor-Cmd.exe, а не UnrealEditor.exe, поскольку так вы сможете увидеть лог выполнения команды и окошко консоли не закроется после выполнения

Важное уточнение 2: в Windows нужно будет предварительно перейти в коммандой строке в папку с UnrealEditor.exe если у вас 5я версия UE или в папку с UE4Editor для 4й версии.

Для вывода результата выполнения Commandlet в лог-файл, можно использовать 2 аргумента:

-stdout 

или

-log=Test.log

Лог будет сохранен в

/saved/logs

папке в вашего проекта

Основные встроенные командлеты в Unreal Engine 5

• CompileAllBlueprints

Компилирует все Blueprint'ы в проекте.

• CookCommandlet

Подготавливает все ресурсы для конкретной платформы.

• GenerateDistillFileSets

Используется для генерации набора файлов для дистилляции данных, как указали эпики в комментарии в .h: "Find AnimNotify instances that do not have the AnimSeqeunce that 'owns' them as their outer.". Могу предположить, что эта командлета используется для отсортировки используемых и не используемых классов в игре.

• GeneratePatchScript

Создаёт сценарий для создания патча.

• ListMaterialsUsedWithMeshEmitters

Перечисляет материалы, используемые со статик мешами.

• ListStaticMeshes

Перечисляет все статик меши, используемые в проекте.

• LoadPackage

Загружает и проверяет ассет. Полезно для тестирования, если ассеты могут быть загружены без ошибок.

• ResavePackages

Пересохраняет ассеты.

• FixupRedirects

Исправляет сломанные референсные ссылки ассетов друг на друга в проектах, возникшие при переименовании или перемещении ресурсов.

• DumpBlueprintsInfo

Выводит информацию о всех существующих Blueprint'ах в проекте.

• GlobalShaderCacheCommandlet

Компилирует и обновляет кеш глобальных шейдеров.

• MergeShaderCaches

Объединяет кеши шейдеров для использования в проекте.

• PakFileCommandlet

Создаёт архив .pak из содержимого проекта.

• PluginCommandlet

Работает с плагинами, проверяя их или создавая из них сборку.

• ScreenshotComparisonCommandlet

Используется для сравнения скриншотов, например, при тестировании рендеринга.

• StatsDumpMemoryCommandlet

Выгружает статистику использования памяти.

• TestPAL

Запускает тесты PAL (Platform Abstraction Layer) для платформы.

• UnrealEdTest

Запускает тесты редактора Unreal Engine.

• ValidateAssetsCommandlet

Проверяет корректность загрузки ассетов в проекте.

• CookOnTheFlyServer

Запускает сервер для готовки ресурсов "на лету" (в реальном времени). Полный список коммандлетов можно найти в исходниках движка. Даже если вы установили движок через Epic Games, а не собирали из исходников, их можно найти в папке

EngineSource

Дополнительные примечания

Помимо командлет в UE есть так же большой список полезных консольных команд, которыми многие пользуются во время разработки в редакторе вроде stat unitgraph или show fps, но и их тоже можно выполнять в автоматическом режиме через cmd; Синтаксис там немного другой:

параметр к UnrealEditor-Cmd.exe

-ExecCmds="Команда1, Команда2...."

Чтобы запустить при этом движок без интерфейса, можно воспользоваться командой

-nullrhi 

Полностью отключает рендеринг или

-nogui

Отключает интерфейс, но позволяет выполнять команды через командную строку Порядок вызова следующий:

UnrealEditor-Cmd.exe ПутьИНазвание.uproject -nogui -ExecCmds=""

UnrealEditor-Cmd.exe ПутьИНазвание.uproject -ExecCmds="" -nullrhi 

Дополнительные ссылки на документацию, на случай если читатель захочет подробнее разобраться в вопросе (хоть документация у Epic Games по данному вопросу довольно скудная и большая часть полезной информации содержится в комментариях к исходному коду движка).