Автоматизация Python в Unreal Engine: начало работы с редактором

Чему вы научитесь в этом руководстве?

Вы узнаете, как включить Python в Unreal Editor, запустить простой скрипт и выбрать подходящий способ автоматизации. Epic Games помечает поддержку Python как экспериментальную и рекомендует проявлять осторожность, особенно при выпуске продукта. Поэтому здесь речь идёт не о коде игрового процесса, работающем во время игры, а о задачах производства и управления контентом внутри редактора.

Python можно использовать как общий скриптовый язык, связывающий производственные процессы в разных 3D-приложениях. В Unreal Editor он также подходит для автоматизации управления ресурсами, выполнения трудоёмких задач — например, создания LOD для Static Mesh, процедурного размещения контента на уровне и разработки интерфейсов для редактора. Это примеры использования из документации, а не готовые средства автоматизации для каждого проекта.

Требования и подготовка проекта

Возможности Python предоставляются через Python Editor Script Plugin в Unreal Editor. Плагин нужно включать отдельно для каждого проекта: активация в одном проекте автоматически не распространяется на остальные. Epic Games также рекомендует включить Editor Scripting Utilities — плагин с упрощёнными API для распространённых задач редактора.

Редактор использует Python 3.11.8, включённый в плагин. Поэтому для запуска скриптов только в Unreal Editor устанавливать Python на компьютер отдельно не нужно. Тем, кто хочет встроить другую версию Python, необходимо задать в операционной системе переменную среды UE_PYTHON_DIR и заново собрать Unreal Engine из исходного кода. Для начала это не требуется.

Пошаговая инструкция: включите Python и запустите первый скрипт

1. Откройте нужный проект Unreal. В главном меню выберите Edit > Plugins.

2. Найдите раздел Scripting в окне Plugins и включите Python Editor Script Plugin. По рекомендации Epic Games также можно включить Editor Scripting Utilities.

3. Перезапустите Unreal Editor. Одной активации плагина недостаточно — перед запуском скриптов редактор нужно перезапустить.

4. Для первого теста откройте панель Output Log и переключите ввод консоли в режим Python. Консоль также можно открыть клавишей обратной кавычки (). В этом режиме введённые строки Python выполняются сразу; для ввода нескольких строк можно использовать **Shift + Enter**. Вывод print` отображается в панели Output Log.

5. Чтобы запустить скрипт из файла, выберите File > Execute Python Script в главном меню и укажите файл на компьютере. Повторно запустить ранее использовавшиеся файлы можно из списка Recent Python scripts. При этом редактор считывает актуальную версию скрипта из файла.

В обычном режиме консоли команду py также можно использовать для запуска строки Python или файла. Пример из документации:

py "C:\MyScripts\my_script.py"

Замените путь в примере на расположение нужного скрипта. Если скрипту требуются дополнительные аргументы командной строки, их можно указать после имени файла.

Автоматизация повторяющихся задач

Если нужно запускать скрипт при каждом открытии проекта, есть два варианта. В настройках Project Settings, относящихся к конкретному проекту, добавьте скрипты в параметр Startup scripts раздела Plugins > Python. Unreal Editor запускает их после полной загрузки уровня по умолчанию. После внесения изменений перезапустите редактор: скрипты начнут выполняться при следующем открытии проекта.

Другой вариант — поместить файл с именем init_unreal.py в папку Content/Python проекта или плагина. Если редактор обнаружит скрипт с таким именем в одном из настроенных путей, он запустит его автоматически. Epic Games описывает этот способ для случаев, когда участникам команды, работающим с одним и тем же контентом, нужно выполнять общий стартовый код при каждом запуске редактора.

Для повторяемых операций или запуска без открытия интерфейса можно использовать командную строку. Способ с полным редактором запускает скрипт после загрузки проекта и уровня по умолчанию; согласно документации, для этого в проекте должны быть включены оба соответствующих плагина. Способ с командлетом работает без интерфейса и выполняется быстрее. Однако уровни автоматически не загружаются: если скрипту нужен контент уровня, загрузку необходимо предусмотреть отдельно. При обоих вариантах запуска из командной строки Unreal Editor закрывается после выполнения скрипта.

Команды запуска Python в Blueprint могут пригодиться командам, использующим Blueprint, однако доступны они только в классах, предназначенных для редактора, таких как Editor Utility Widget и Editor Utility Blueprint. Для вызова Python из Blueprint документация рекомендует узел Execute Python Script. Входные данные этого узла считываются до запуска скрипта, а выходы задаются по его завершении. Успешность выполнения можно проверить на выходе Return Value; сведения об ошибках отображаются в Output Log. Этот узел выполняет строки Python, но не запускает файлы.

Частые ошибки и ограничения

Главное различие — между автоматизацией редактора и игровым временем выполнения. Среда Python доступна в Unreal Editor, но не работает в Play In Editor (PIE), Standalone Game и упакованных исполняемых файлах. Поэтому Python не следует рассматривать как язык скриптов игрового процесса.

Ещё одна распространённая проблема — плагин включён только в другом проекте. Для каждого проекта нужна отдельная активация и перезапуск редактора. Ошибкой может стать и предположение, что скрипты, запущенные командлетом, автоматически загружают уровень. Если выполнение не удаётся через узел Blueprint, подробности ошибки следует искать в Output Log.

Следующие шаги: рабочие процессы в архитектуре и визуализации

Для команд, работающих в архитектуре, дизайне интерьеров и archviz, Python может помочь сократить объём повторяющихся задач по управлению контентом в Unreal Editor и связать производственные процессы, включающие разные 3D-приложения. Например, автоматизация управления ресурсами или размещения контента на уровне соответствует сценариям использования, описанным в документации. Это не означает гарантированной поддержки определённого импорта BIM или совместимости с конкретным программным обеспечением: интеграцию нужно проектировать с учётом содержимого проекта.

Для начала выберите небольшую задачу, результат которой можно проверить в редакторе, и протестируйте скрипт в консоли или через Execute Python Script. Если операцию приходится повторять, переходите к стартовым скриптам или запуску из командной строки. При планировании производства учитывайте предупреждение об экспериментальном статусе поддержки Python, необходимость включать плагин отдельно для каждого проекта и невозможность использовать Python во время игры. Документация Unreal Python 5.8 API — отправная точка для изучения доступных разделов API и типов.

Источник и лицензия

Это руководство адаптировано на турецкий язык на основе руководства Epic Games Scripting the Unreal Editor using Python и страницы Unreal Python 5.8 API Documentation. Оба источника — официальная документация Epic Games.