Автоматизация на Python в Unreal Engine: включаем плагин и запускаем первый скрипт

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

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

Важно учитывать область применения: среда Python предназначена для Unreal Editor. Код Python нельзя использовать, когда проект запущен в режиме Play In Editor, как отдельная игра или в виде упакованного приложения. Поэтому описанные здесь приёмы — отправная точка для автоматизации редактора и производственного процесса, а не для создания игровой логики.

Требования

• Проект Unreal Engine и Unreal Editor.

• Плагин Python Editor Script Plugin, который нужно включить для проекта.

• Плагин Editor Scripting Utilities, рекомендованный руководством для доступа к упрощённым API распространённых операций редактора.

• Отдельная установка Python не требуется: согласно документации Epic Games, Python Editor Script Plugin включает встроенную версию Python 3.11.8.

Документация Unreal Python API помечена как «5.8 (Experimental)». Epic Games также предупреждает, что функция является экспериментальной и требует осторожного использования, особенно на этапе выпуска продукта. Поэтому описанные здесь шаги стоит сначала проверить на копии производственного проекта или в тестовом проекте. В источниках также не указано требование к аккаунту.

Шаг за шагом: включаем Python и запускаем код

1. Включите плагины в проекте

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

Эту настройку нужно выполнить отдельно для каждого проекта. После включения плагинов перезапустите редактор. Не пропускайте этот шаг: руководство требует перезапуска Unreal Editor после установки плагина.

2. Используйте режим Python в консоли

Чтобы выполнять код построчно или сразу запускать короткие фрагменты, переключите поле ввода консоли в панели Output Log в режим Python. Открыть строку ввода консоли также можно клавишей ~. Введённые в режиме Python строки выполняются сразу. Для нескольких строк используйте Shift+Enter или вставьте многострочный блок из текстового редактора.

Этот способ подходит для интерактивных экспериментов. Вывод функции print также направляется в панель Output Log. Если консоль команд работает в режиме Cmd, оставшуюся часть строки можно выполнить как Python-код с помощью команды py. Пример вызова существующего файла скрипта:

py "C:\MyScripts\my_script.py"

Путь к файлу здесь приведён в руководстве как пример расположения скрипта. Для собственного файла укажите соответствующий путь.

3. Запустите файл скрипта через меню File

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

Этот способ позволяет запускать код из файла, не вставляя его снова и снова в консоль. В источнике не упоминается автоматическая проверка или валидация содержимого файла, поэтому перед запуском проверьте скрипт и целевой проект.

4. Запустите скрипт из командной строки вместе с редактором

Если скрипт взаимодействует с содержимым проекта или уровнем, загрузка которого может занять время, используйте способ, запускающий полноценный Unreal Editor. Редактор откроет проект, загрузит уровень, заданный по умолчанию при запуске, а затем выполнит скрипт, когда среда будет готова. Пример для командной строки Windows из руководства:

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

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

5. Рассмотрите вариант с командлетом без интерфейса

Способ с командлетом позволяет быстрее запустить скрипт без открытия интерфейса редактора, то есть в headless-режиме. В руководстве показан пример использования UnrealEditor-Cmd.exe с аргументами -run=pythonscript и -script:

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

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

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

Пути к проекту, скрипту и уровню в примерах с командлетом взяты из документации. Перед использованием замените их на актуальные пути своего проекта.

6. Запускайте повторяющиеся задачи при старте

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

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

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

• Полагать, что достаточно включить плагин один раз: Python Editor Script Plugin нужно отдельно включать в каждом проекте.

• Пытаться использовать Python во время игры: эта функция предназначена для редактора и недоступна в Play In Editor, Standalone Game и упакованном приложении.

• Предполагать, что командлет автоматически загрузит уровень: в источнике отдельно отмечено, что командлет сам по себе не загружает уровни.

• Запускать скрипт до готовности среды: руководство не рекомендует запускать скрипт командой py в параметре запуска ExecCmd — среда редактора или стартовый уровень могут быть ещё не готовы.

• Игнорировать экспериментальный статус: поддержка Python обозначена как экспериментальная. Перед передачей или выпуском проекта сначала проведите контролируемое тестирование.

Влияние на рабочие процессы в архитектуре и визуализации

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

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

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

Сначала включите плагины в тестовом проекте и сравните способы запуска через консоль и меню File. Затем перенесите разовые операции в файл; подготовительные задачи, которые нужно выполнять регулярно, оформите как стартовые скрипты проекта. Если планируете использовать Blueprint, помните, что узлы Python доступны только в классах редактора, таких как Editor Utility Widget и Editor Utility Blueprint. Согласно источнику, узел Execute Python Script выполняет фрагмент кода, но не запускает файл; для файла или кода предусмотрен вариант Execute Python Command. Вывод ошибок можно посмотреть в панели Output Log.

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

Руководство подготовлено на основе материалов Epic Games о начале работы с Python в Unreal Editor и документации Python API. Исходные страницы предоставлены для этого материала под свободной лицензией; текст адаптирован и переписан на турецком языке.