Во время разработки на 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

Запускает сервер для готовки ресурсов "на лету" (в реальном времени). С полным списком коммандлет можно ознакомиться по ссылке в конце статьи.

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

Помимо командлет в 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 по данному вопросу довольно скудная и большая часть полезной информации содержится в комментариях к исходному коду движка).

Ссылки

https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Editor/UnrealEd/Commandlets?application_version=5.4

https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/Commandlets/UCommandlet?application_version=5.4

https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/Commandlets?application_version=5.4

https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Editor/UnrealEd/Commandlets?application_version=5.4

https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/NiagaraEditor/Commandlets?application_version=5.4

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