Construction Script в Unreal Engine

Друзья, приветствую, с Вами Будуев Антон. В данной статье мы поговорим о функции Construction Script в Unreal Engine (UE4, UE5), представляющей в Blueprint возможность динамической инициализации и настройки объекта до начала его игрового процесса.

Вскоре выйдет моя бесплатная книга по Blueprints для Unreal Engine в PDF формате. Как она выйдет, рекомендую её скачать, чтобы Вы детально изучили блюпринты Анрил Энджин.

Construction Script

Construction Script (скрипт конструктора) в Unreal Engine — это специальный визуальный скрипт класса Actor, встроенный в Blueprint-редактор, который автоматически выполняется при создании экземпляра Актора, его размещении в сцене или изменении параметров в редакторе. Его основная цель — динамическая инициализация и настройка объекта до начала его игрового процесса, что позволяет гибко управлять внешним видом и структурой компонентов Актора на этапе проектирования.

Construction Script особенно полезен для задач, связанных с автоматической генерацией и настройкой компонентов на основе заданных переменных. Например, его можно использовать для:

• условного создания или скрытия компонентов (например, добавления деталей в зависимости от типа объекта);
• изменения трансформаций, материалов или параметров мешей;
• динамического построения сложных композиций прямо в редакторе (например, генерации ландшафтных элементов, мебели или архитектурных деталей).

Одно из ключевых преимуществ Construction Script — мгновенная визуализация результатов. При любом изменении параметров (например, цвета, размера или типа объекта) скрипт перезапускается, и изменения сразу отображаются в редакторе. Это позволяет быстро итерировать дизайн без необходимости запускать игру, что значительно ускоряет процесс разработки.

Кроме того, скрипт может использоваться для настройки геометрии и позиционирования Mesh-компонентов, включая масштабирование, поворот или смещение элементов на основе логики, определённой в Blueprint. Такие преобразования применяются ещё до начала игры и не требуют участия игрового цикла.

Важно понимать, что Construction Script предназначен исключительно для подготовительных операций в редакторе или при спавне экземпляра Actor. Он выполняется до Begin Play, но после создания компонентов Актора, и не предназначен для логики во время игры. Это делает его идеальным инструментом для предварительных вычислений, настроек, динамического создания компонентов и автоматизации рутинных задач, связанных с визуальной сборкой объектов.

Construction Script и Event Graph

Construction Script и Event Graph в Unreal Engine — это два совершенно разных визуальных скриптовых контекста в Blueprint, предназначенных для выполнения логики в разные моменты жизненного цикла Актора. Они отличаются по времени выполнения, назначению, контексту использования и влиянию на редактор.

ConstructionScript выполняется в момент создания Актора — как в редакторе при размещении его на уровне, так и при спавне во время игры.

Его основное назначение — настройка структуры Актора до начала игрового процесса, включая создание, параметризацию и иерархическое построение компонентов. Благодаря тому, что этот скрипт запускается при любом изменении свойств в редакторе, он позволяет мгновенно визуализировать результат изменений, например, изменение формы, размера или материала объекта, не запуская игру. Это делает его мощным инструментом для создания параметрических и переиспользуемых Blueprint-объектов, чья внешняя структура зависит от настраиваемых переменных.

Construction Script особенно полезен при динамической генерации компонентов, например, при построении сложных конструкций, когда количество или расположение элементов определяется логикой, заданной в Blueprint.

При этом выполнение Construction Script происходит до вызова Begin Play, и он не предназначен для обработки игровых событий или реакции на ввод — его сфера действия ограничена этапом инициализации.

В отличие от Construction Script, Event Graph активизируется только во время выполнения игры и служит для реализации поведенческой логики Актора. Различные события, такие как Event Begin Play, Event Tick, Event Hit, события ввода и прочие события или таймеры, обрабатываются именно в Event Graph. Эта логика не влияет на внешний вид объекта в редакторе и не запускается при изменении параметров в режиме проектирования.

Event Graph используется для управления движением, анимациями, взаимодействием с игроком и другими динамическими аспектами, которые проявляются только в процессе игры. Таким образом, Construction Script отвечает за «подготовку сцены», а Event Graph — за «действие на сцене».

Как Construction Script работает внутри

Обычно Construction Script воспринимается как визуальный скрипт в Blueprint, в который можно поместить узлы для выполнения логики при создании Актора — будь то настройка компонентов, изменение их параметров или генерация элементов на основе переменных. На первый взгляд, это просто специальная функция, вызываемая до начала игры. Однако на самом деле внутренняя реализация Construction Script в C++ значительно сложнее и представляет собой многоэтапный процесс, объединяющий работу движка, системы компонентов и логики Blueprint.

Фактически, то, что в Blueprint называется Construction Script, в C++ разделяется на несколько ключевых этапов, реализованных в методах класса Actor. Основной точкой входа является метод ExecuteConstruction(), который вызывается при создании Актора — как в редакторе, так и во время игры. Этот метод координирует выполнение всей цепочки построения объекта Актора, включая как автоматически сгенерированные компоненты, так и пользовательскую логику.

Сначала движок проходит по всей внутренней иерархии компонентов Актора и запускает набор методов SimpleConstructionScript (SCS), отвечающие за создание и иерархическую организацию компонентов, определённых в редакторе Blueprint. Именно на этом этапе создаются все компоненты, добавленные через графический интерфейс: статические мешы, коллайдеры, свет и т.д. Они помечаются как созданные скриптом построения, и их привязки, трансформации и имена устанавливаются согласно схеме, определённой в редакторе.

Далее происходит регистрация компонентов, если это ещё не сделано, и только затем в C++ через метод ProcessUserConstructionScript() вызывается UserConstructionScript(), а это именно то, что видит пользователь в редакторе Blueprint — функция Construction Script. Именно здесь выполняется пользовательская логика: изменение материалов, масштабирование, условное скрытие компонентов, расчёт позиций и другие действия, основанные на переменных.

Однако и после этого процесс не завершён. После выполнения UserConstructionScript(), иначе говоря, после выполнения Construction Script в Blueprint внутри движка вызывается метод OnConstruction(), который можно переопределить в C++ для дополнительной настройки. Этот метод получает трансформ Актора и гарантирует, что все компоненты уже созданы и зарегистрированы. Он часто используется в C++ для логики, аналогичной Construction Script, но без привязки к Blueprint.

Кроме того, система поддерживает сохранение и восстановление состояния компонентов между перезапусками ConstructionScript. Это критично в редакторе, где пользователь может изменять переменные, и движок должен попытаться сохранить привязки, особенно для динамически созданных компонентов. Для этого используются механизмы вроде FComponentInstanceDataCache, RerunConstructionScripts() и TMap для сопоставления старых и новых компонентов. При перезапуске скрипта (например, при изменении параметра в редакторе) старые компоненты, созданные скриптом, открепляются и помечаются на уничтожение (при этом система старается сохранить их данные для восстановления при отмене), а новые создаются заново, с сохранением ключевых свойств, где это возможно.

В итоге, функционал, реализуемый Construction Script на уровне C++, включает:

• создание компонентов по иерархии Blueprint через SimpleConstructionScript, включая правильную установку привязок и трансформаций;
• выполнение пользовательской логики из визуального скрипта Construction Script через вызов UserConstructionScript();
• гарантированную инициализацию до начала игры (до Begin Play), но после базового создания Актора;
• поддержку динамического перестроения в редакторе, когда изменение переменной перезапускает весь процесс;
• сохранение и восстановление состояния компонентов при перезапуске через FComponentInstanceDataCache;
• работу с рандомизацией — перед запуском скрипта сбрасываются все FRandomStream, чтобы обеспечить предсказуемость при каждом пересчёте;
• интеграцию с системой отката (Undo/Redo) и защиту от повреждения CDO (Class Default Object);
• поддержку наследования — скрипты выполняются от базовых классов к производным, обеспечивая корректную инициализацию всей цепочки.

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

Тонкости применения Construction Script

1. Многократное выполнение — в редакторе ConstructionScript может выполняться многократно при изменении свойств или перемещении Актора. Это может привести к накоплению данных (например, многократному добавлению элементов в массивы) или непредсказуемому поведению, если логика не учитывает повторные вызовы.
2. Порядок выполнения в иерархии наследования —  SimpleConstructionScript в C++ выполняется от базового класса к производному, а ConstructionScript в Blueprint — только для самого производного класса. Соответственно,  необходимо понимать, что родительский Construction Script каждого уровня иерархии не выполняется автоматически — нужно явно вызывать родительский скрипт через узел Call Parent Construction Script.

3. Производительность в редакторе — ConstructionScript в Blueprint выполняется в редакторе при каждом изменении. Сложные вычисления или создание множества компонентов могут существенно замедлить работу редактора. Поэтому необходимо избегать тяжелых операций в данном скрипте, особенно тех, что зависят от часто изменяемых свойств.
4. Неполная инициализация у систем — так как ConstructionScript выполняется на ранних этапах инициализации самого Актора, то другие системы Unreal Engine могут быть еще не до конца загружены или не до конца проинициализированы, компоненты самого Актора могут быть созданы и зарегистрированы, но их специфичная инициализация еще не завершена. Соответственно при создании логики в скрипте, необходимо очень осторожно ссылаться на различные системы движка, обрабатывая пустые и невалидные ссылки.

Практика использования Construction Script в Unreal Engine

В качестве практического примера использования Construction Script в Unreal Engine рассмотрим урок, посвящённый сохранению выбранного персонажа между уровнями с помощью класса Game Instance. В этом уроке реализуется следующая логика: при выборе персонажа (например, SKM_Manny или SKM_Quinn) его модель сохраняется в переменной внутри пользовательского класса CustomGameInstance. При переходе между уровнями эта информация сохраняется, так как Game Instance существует на протяжении всей игровой сессии.

Ключевой момент — восстановление выбранного персонажа при загрузке уровня. Именно здесь используется Construction Script в Blueprint персонажа BP_ThirdPersonCharacter. Скрипт выполняется при создании Актора на уровне и загружает сохранённую модель из Game Instance, применяя её к компоненту Mesh.

Перейти к практике >>>

Этот пример демонстрирует типичное применение Construction Script, но также выявляет важную архитектурную тонкость.

1. Construction Script действительно подходит для первоначальной настройки Актора. В данном случае он используется, чтобы задать внешний вид персонажа до начала игры — ещё на этапе появления Актора в мире. Это выглядит логично: мы хотим, чтобы персонаж сразу появился с правильной моделью, а не менял её с задержкой.
2. Но здесь кроется потенциальная проблема — зависимость от внешней системы. Construction Script выполняется в момент инициализации Актора, когда не гарантируется полная загрузка всех игровых систем. В частности, обращение к Game Instance (при первой загрузке игры) может оказаться преждевременным — его данные могут быть еще не до конца проинициализированы.
3. Лучшая практика: Construction Script должен полагаться только на локальные данные Актора-владельца. Он идеален для настройки масштаба, визуальных компонентов или параметров на основе собственных переменных Актора. Однако если логика зависит от внешних классов (Game Instance, Game Mode, Player Controller), безопаснее перенести её в Event BeginPlay, который срабатывает после полной инициализации мира.

Вывод и рекомендации по данному примеру для самостоятельной работы:

• Добавьте проверку валидности объектов. Перед использованием результата Cast to CustomGameInstance обязательно проверяйте его через Is Valid. Это защитит от сбоев, если приведение типа не удалось или Game Instance не инициализирован.
• Перенесите логику восстановления персонажа в Event BeginPlay. Это сделает реализацию более надёжной. Хотя в простых проектах Construction Script может работать корректно, в продвинутых или масштабных играх Begin Play — более предсказуемое и безопасное место для взаимодействия с глобальными системами. А Construction Script — для настройки объекта на основе его собственных данных.

Пример из урока отлично иллюстрирует концепцию хранения данных между уровнями. Однако он также служит важным напоминанием: Construction Script — мощный инструмент, но его нужно использовать с осторожностью. Полагаться на него можно только тогда, когда логика ограничена внутренним состоянием Актора. При работе с внешними зависимостями — выбирайте Begin Play, а также обеспечивайте проверку на валидность (Is Valid).

Совет. Вскоре выйдет моя бесплатная книга по Blueprints для Unreal Engine в PDF формате. Как она выйдет, рекомендую её скачать, чтобы Вы детально изучили блюпринты Анрил Энджин.