Автоматизация редактора Unreal Engine с Python: пошаговое руководство

Что вы узнаете из этого руководства?

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

В этом руководстве мы сначала настроим проект, затем запустим короткую команду Python и сравним варианты автоматизации с помощью файловых скриптов. Описанные методы предназначены для автоматизации редактора: поддержка Python доступна, пока открыт Unreal Editor; использовать её нельзя, когда игра запущена в Play In Editor, Standalone Game или в упакованном исполняемом файле.

Требования

Вам понадобятся проект Unreal Engine, в котором можно включить Python Editor Script Plugin, и Unreal Editor. Согласно руководству Epic, плагин активируется отдельно для каждого проекта; чтобы использовать Python в другом проекте, его нужно включить и там. Также рекомендуется активировать Editor Scripting Utilities: этот плагин предоставляет упрощённые API для распространённых операций в редакторе.

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

В документации Epic по Python API версия Unreal Python 5.8 помечена как “Experimental”. В основном руководстве также отмечается экспериментальный статус функции. Поэтому разумно сначала проверить скрипты на копии производственного проекта или в контролируемом тестовом проекте.

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

1. Откройте проект, с которым будете работать в Unreal Editor. В верхнем меню выберите Edit > Plugins.

2. В разделе Scripting окна плагинов найдите Python Editor Script Plugin и установите флажок Enabled.

3. В том же окне включите плагин Editor Scripting Utilities. После внесения изменений перезапустите редактор.

4. Откройте панель Output Log и переключите ввод консоли в режим Python. В качестве альтернативы нажмите ~, чтобы открыть строку ввода консоли. Строки кода, введённые в режиме Python, сразу выполняются в редакторе.

5. Для первой проверки выведите сообщение в Output Log с помощью функции Python print:

print("Python etkin")

Вывод print направляется в панель Output Log. Чтобы выполнить несколько строк в консоли, разделяйте их сочетанием Shift+Enter или вставьте многострочный код. Этот способ удобен для проверки отдельных строк и выполнения простых тестов.

Варианты запуска файлов скриптов

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

py "C:\MyScripts\my_script.py"

Здесь приведён пример из документации Epic; замените путь на расположение вашего скрипта. Другой вариант — выбрать скрипт на компьютере через File > Execute Python Script в главном окне. Можно также повторно запускать файлы из списка Recent Python scripts. Редактор перечитывает файл с диска, поэтому при запуске учитываются и последние изменения.

Запуск из командной строки — ещё один вариант для команд, которые хотят добавить скрипты в конвейер автоматизации. Скрипт можно запустить после полной загрузки редактора, проекта и уровня, заданного по умолчанию:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -ExecutePythonScript="c:\my_script.py"

Для этого метода в проекте должны быть включены Python Scripting Plugin и Editor Scripting Utilities. После выполнения скрипта редактор закроется.

Для более быстрого запуска без интерфейса можно использовать commandlet pythonscript:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="c:\\my_script.py"

Этот метод не загружает уровни автоматически. Если скрипту нужен доступ к содержимому определённого Level, можно использовать вызов загрузки, приведённый Epic в качестве первой строки. Путь в нём относится к примеру проекта и должен быть изменён в соответствии с путём к Level в вашем проекте:

unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).load_level("/Game/maps/UVlayoutTest.UVlayoutTest")

Распространённые ошибки и ограничения

Чаще всего забывают, что плагин нужно включать отдельно для каждого проекта. Не рассчитывайте, что скрипт, работающий в одном проекте, запустится и в другом: сначала проверьте состояние соответствующего плагина. При запуске полного редактора из командной строки не забудьте и о требовании включить Editor Scripting Utilities.

Запуск через commandlet и запуск полного редактора ведут себя по-разному. Commandlet не загружает уровень автоматически, поэтому в скриптах, работающих с содержимым уровня, нужно явно предусмотреть его загрузку. При запуске полного редактора скрипт выполняется после открытия проекта и загрузки уровня, заданного по умолчанию.

Python также не подходит для реализации игровой логики. В документации Epic указано, что среда Python доступна в Unreal Editor и не используется в режимах выполнения. Узлы запуска Python из Blueprint также доступны только в ориентированных на редактор классах Blueprint, таких как Editor Utility Widget и Editor Utility Blueprint, но не в обычных классах времени выполнения.

Применение в архитектуре, дизайне интерьеров и archviz

Для архитектурных бюро и команд визуализации главное преимущество — возможность управлять повторяющимися операциями с ассетами прямо в редакторе с помощью скриптов. Например, к явно указанным в документации сценариям использования относятся организация управления ассетами проекта, автоматизация создания LOD и размещение содержимого на уровне. Использование Python в качестве общего языка скриптов в производственных конвейерах с несколькими 3D-приложениями также может помочь связать процессы между собой.

При этом руководство не гарантирует совместимость с конкретным плагином для archviz, требованиями к оборудованию, моделью лицензирования или определённым проектом. Особенно важно проверять, что необходимые функции экспериментальных API работают в используемой версии Unreal. Не переносите автоматизацию в производственный процесс, не проверив, как она влияет на загрузку уровней, плагины редактора и настройки проекта у других участников команды.

Что делать дальше

После запуска первого скрипта выберите небольшую задачу, которую легко отменить: например, проверьте команду из редактора или контролируемо автоматизируйте существующий этап производства. Затем сохраните операцию в файл и попробуйте запустить её через Execute Python Script или подходящий способ командной строки. Для проектов, которыми будут пользоваться несколько человек, можно также настроить стартовые скрипты: init_unreal.py можно поместить в папку Content/Python проекта или плагина, и редактор запустит его автоматически. В настройках проекта также можно указать скрипты, которые должны выполняться при запуске.

По мере развития рабочего процесса изучайте документацию Unreal Python API для используемой версии: она содержит справочную информацию о модулях, типах и заголовках API. Учитывая экспериментальный статус функции и то, что скрипты работают только в редакторе, расширяйте область применения постепенно.

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

Это руководство адаптировано на турецкий язык на основе руководства Epic Games “Scripting the Unreal Editor Using Python” и страницы “Unreal Python API Documentation”. Источники отмечены как свободные для использования; текст и описание примеров были переработаны.