Unreal Engine Construction Script를 안전하게 사용하는 법

Construction Script와 OnConstruction의 관계#

Blueprint Class에는 UserConstructionScript, 즉 편집기의 Construction Script 그래프가 있다. C++ Actor는 비슷한 목적의 virtual hook인 OnConstruction을 override할 수 있다.

1
virtual void OnConstruction(const FTransform& Transform) override;

1
void AMyProceduralActor::OnConstruction(const FTransform& Transform)
2
{
3
    Super::OnConstruction(Transform);
4
    // 편집 가능한 입력으로부터 파생된 컴포넌트 상태를 재구성한다.
5
}

둘을 완전히 같은 단계라고 부르면 세부 순서를 놓친다. ExecuteConstruction은 대략 아래 순서로 흐른다.

1. native component와 Blueprint의 Simple Construction Script 컴포넌트를 준비한다.
2. Blueprint UserConstructionScript를 실행한다.
3. Blueprint로 만든 컴포넌트까지 생성·등록한 뒤 virtual OnConstruction을 호출한다.

C++ OnConstruction은 Blueprint Construction Script가 끝난 뒤 실행되는 마지막 알림에 가깝다. C++로 override할 때도 Super::OnConstruction을 호출하고, Blueprint 파생 클래스가 추가한 컴포넌트나 값을 어느 단계에서 읽는지 실제 클래스 계층으로 검증해야 한다.

생성자, Construction, BeginPlay의 역할 분리#

“Construction Script를 쓰면 생성자나 BeginPlay를 쓰면 안 된다”는 식의 규칙은 정확하지 않다. 세 단계는 함께 사용하되 책임을 분리해야 한다.

PostLoad와 PostActorCreated는 서로 배타적인 생성 경로다. 저장된 레벨의 Actor는 load 경로를 사용하고, SpawnActor로 만든 Actor는 creation 경로를 사용한다. 이 구분은 Construction Script의 런타임 동작을 이해하는 데 중요하다.

언제 다시 실행되는가#

Blueprint Foundations는 Blueprint Actor가 생성될 때 컴포넌트를 만든 다음 Construction Script를 실행하고, 에디터에서 transform이나 프로퍼티를 바꿀 때도 즉시 결과를 갱신한다고 설명한다. 엔진에는 그 밖에도 Blueprint compile/reinstance, undo/redo, component 편집, duplicate와 paste, 일부 level·sequencer 작업처럼 construction을 재실행하는 경로가 있다.

Blueprint의 Run Construction Script on Drag가 켜져 있으면 Actor를 끌어 움직이는 동안 계속 재실행될 수 있다. 끄더라도 drag가 끝날 때 한 번은 실행된다. 위치를 따라 즉시 바뀌는 미리보기가 꼭 필요하지 않다면 이 설정을 끄는 것만으로도 편집기 hitch를 크게 줄일 수 있다.

배치 Actor가 패키지 실행 시 다시 구성되지 않는다는 사실은 특히 중요하다. 에디터나 cook 과정에서 만든 결과가 레벨에 직렬화되는 일반 경로에서는, 런타임에만 존재하는 subsystem 등록, 네트워크 권한 검사, 타이머 시작 같은 동작을 Construction Script에 넣으면 실행 여부가 생성 경로에 따라 달라진다. 그런 동작은 BeginPlay나 적합한 gameplay 초기화 단계로 옮긴다.

동적 spawn에서 Construction 전에 값을 넣어야 한다면 일반 SpawnActor 반환 뒤에 값을 대입하지 말고 SpawnActorDeferred와 FinishSpawning 사이에서 설정한다.

재실행 가능한 코드의 첫 번째 조건: 멱등성#

멱등인 construction은 같은 입력으로 여러 번 실행해도 같은 결과를 만든다. “이전 결과에 하나 더 추가”하는 방식이 아니라, 자신이 관리하는 파생 상태를 초기화한 뒤 현재 입력으로 다시 구성한다.

다음은 한 native UHierarchicalInstancedStaticMeshComponent에 울타리 미리보기를 다시 채우는 예다. 입력 수에는 상한을 두고, 재실행 때 이전 instance를 먼저 지운다.

1
#pragma once
2

3
#include "CoreMinimal.h"
4
#include "GameFramework/Actor.h"
5
#include "ProceduralFence.generated.h"
6

7
class UHierarchicalInstancedStaticMeshComponent;
8
class UStaticMesh;
9

10
UCLASS()
11
class YOURGAME_API AProceduralFence : public AActor
12
{
13
    GENERATED_BODY()
14

15
public:
16
    AProceduralFence();
17
    virtual void OnConstruction(const FTransform& Transform) override;
18

19
private:
20
    UPROPERTY(VisibleAnywhere, Category = "Fence")
21
    UHierarchicalInstancedStaticMeshComponent* PreviewInstances = nullptr;
22

23
    UPROPERTY(EditAnywhere, Category = "Fence")
24
    UStaticMesh* SegmentMesh = nullptr;
25

26
    UPROPERTY(EditAnywhere, Category = "Fence", meta = (ClampMin = "0", ClampMax = "1000"))
27
    int32 SegmentCount = 4;
28

29
    UPROPERTY(EditAnywhere, Category = "Fence", meta = (ClampMin = "1.0"))
30
    float SegmentSpacing = 100.0f;
31
};

1
#include "ProceduralFence.h"
2
#include "Components/HierarchicalInstancedStaticMeshComponent.h"
3

4
AProceduralFence::AProceduralFence()
5
{
6
    PreviewInstances =
7
        CreateDefaultSubobject<UHierarchicalInstancedStaticMeshComponent>(
8
            TEXT("PreviewInstances"));
9
    SetRootComponent(PreviewInstances);
10
}
11

12
void AProceduralFence::OnConstruction(const FTransform& Transform)
13
{
14
    Super::OnConstruction(Transform);
15

16
    PreviewInstances->ClearInstances();
17
    PreviewInstances->SetStaticMesh(SegmentMesh);
18

19
    if (!SegmentMesh)
20
    {
21
        return;
22
    }
23

24
    const int32 SafeCount = FMath::Clamp(SegmentCount, 0, 1000);
25
    const float SafeSpacing = FMath::Max(SegmentSpacing, 1.0f);
26

27
    for (int32 Index = 0; Index < SafeCount; ++Index)
28
    {
29
        const FVector LocalLocation(Index * SafeSpacing, 0.0f, 0.0f);
30
        PreviewInstances->AddInstance(FTransform(LocalLocation));
31
    }
32
}

이 패턴에는 의도적인 경계가 있다.

• 생성자에서는 native default subobject만 만든다.
• OnConstruction은 instance editable 입력만 읽고 자기 컴포넌트만 갱신한다.
• 실행 횟수에 관계없이 같은 입력은 같은 instance 집합을 만든다.
• 수천 개의 별도 component나 Actor 대신 instancing을 사용한다.
• 잘못된 수치가 에디터를 멈추지 않도록 상한을 둔다.

실제 도구에서는 메시의 bounds와 spline 길이 등을 사용할 수 있지만 원칙은 같다. 파일 I/O, 전체 World 검색, asset 저장, blocking load, 복잡한 pathfinding처럼 비용과 부작용이 큰 작업은 자동 construction 경로에서 분리한다.

재실행은 컴포넌트의 수명도 바꾼다#

RerunConstructionScripts는 construction에서 자동 생성한 컴포넌트를 파괴하고 다시 만든 뒤, 보존 가능한 instance data를 복원하려 한다. Construction Script에서 추가한 component의 raw pointer나 외부 Actor가 보관한 참조가 다음 재실행 뒤에도 같은 객체를 가리킨다고 가정하면 안 된다.

아래 방법 중 하나를 선택한다.

• 고정된 핵심 컴포넌트는 가능하면 C++ constructor 또는 Blueprint Components 패널에서 만든다.
• 가변적인 다수 요소는 ISM/HISM, spline mesh처럼 한 owner가 명확히 관리하는 표현을 사용한다.
• 다시 찾아도 되는 컴포넌트는 안정적인 이름, tag, 명시적 UPROPERTY와 소유 관계로 식별한다.
• async 결과가 돌아올 때는 대상의 weak reference와 construction revision을 확인한다. 가능하면 async 작업 자체를 explicit editor command로 옮긴다.

Construction Script 안에서 다른 Actor를 spawn해 영구 배치하거나 asset을 저장하는 동작은 재실행과 transaction 경계 때문에 특히 위험하다. Actor가 관리하는 자식이 필요하면 Child Actor Component 등 수명이 owner의 reconstruction과 결합된 기능을 우선 검토하고, 대규모 생성·베이크는 별도 도구로 만든다.

다른 Actor를 변경하면 순환 재구성이 생긴다#

대표적인 사례는 A Actor의 Construction Script가 B의 editable property를 바꾸고, B의 Construction Script가 다시 A를 바꾸는 구조다.

1
A Construction → B property 변경 → B reconstruction
2
       ↑                              ↓
3
       └──────── A property 변경 ─────┘

엔진에 같은 Actor의 construction 재진입을 막는 처리와 Child Actor 재구성을 다루는 경로가 있어도, 서로 다른 Actor 사이의 모든 ping-pong과 간접 부작용까지 안전하게 해결해 주는 것은 아니다. 반복 재실행, 비결정적인 최종값, 심한 hitch, ensure나 stack overflow, crash로 이어질 수 있다.

다른 Actor와 협력해야 한다면 양방향 mutation을 없앤다.

1. 두 Actor가 읽기만 하는 하나의 Data Asset이나 설정 객체를 둔다.
2. 한쪽만 owner가 되어 자식의 입력을 단방향으로 계산한다.
3. 여러 Actor를 함께 변경하는 작업은 explicit CallInEditor 함수나 Editor Utility로 옮긴다.
4. 변경 전에 값이 실제로 달라졌는지 비교하더라도, 그것만으로 잘못된 순환 설계가 안전해진다고 보지 않는다.

특히 construction에서 무작위 값을 만들 때는 비시드 random을 피한다. 디자이너가 편집할 수 있는 seed와 Random Stream을 사용해 같은 입력이 같은 결과를 만들게 하거나, 확정된 결과를 명시적으로 bake한다.

무거운 작업은 명시적 에디터 명령으로 바꾸기#

프로퍼티를 바꿀 때마다 자동으로 실행할 필요가 없는 작업이라면 Details 패널 버튼으로 실행 시점을 사용자에게 돌려줄 수 있다.

1
UFUNCTION(CallInEditor, Category = "Fence")
2
void RebuildBakedFence();

UFunction 문서는 CallInEditor 함수를 선택한 instance의 Details 패널에서 호출할 수 있다고 설명한다. 여러 asset이나 Actor를 일괄 처리하거나 별도 UI와 진행률, 취소가 필요하다면 Editor Utility Blueprint와 Scripted Action이 더 적합하다.

에디터 전용 API를 C++에서 사용할 때는 모듈 경계와 전처리 조건도 구분한다.

• #if WITH_EDITOR: PostEditChangeProperty, PostEditMove와 editor-only 실행 코드를 감싼다.
• #if WITH_EDITORONLY_DATA: cooked build에서 제거할 수 있는 editor-only 데이터 멤버에 사용한다.
• runtime에서 spawn되는 Actor에도 필요한 OnConstruction 전체를 WITH_EDITOR로 감싸지 않는다.
• asset 편집과 저장을 하는 코드는 가능하면 runtime 모듈이 아닌 Editor 모듈에 둔다.

멀티플레이에서 Construction Script를 상태 복제로 쓰지 않기#

Construction Script는 네트워크 동기화 메커니즘이 아니다. 서버에서 실행한 Construction Script의 부작용이 클라이언트에 그대로 재생되거나 복제된다고 보장되지 않는다. 클라이언트에 복제로 생성된 Actor는 초기 replicated property를 받기 전에 construction 단계를 지날 수 있다.

책임은 아래처럼 나눈다.

• 서버가 authoritative gameplay 값을 정한다.
• 동기화할 값은 Replicated 또는 ReplicatedUsing으로 선언한다.
• 클라이언트의 표시 상태는 OnRep에서 적용하고 필요하면 BeginPlay에서 최종 상태를 확인한다.
• Construction Script는 그 값의 editor preview나 서버/로컬 spawn 시 파생 구성에만 사용한다.

Construction Script가 빠르고 결정적이어야 하는 이유는 성능만이 아니다. editor, standalone, listen server, dedicated server, client proxy처럼 실행 환경이 달라도 gameplay 정본은 replication 계약으로 수렴해야 한다.

실전 점검표#

참고 자료#

• Epic Games: Construction Script
• Epic Games: Blueprint Foundations
• Epic Games: Actor Lifecycle
• Epic Games: AActor initialization order
• Epic Games: UFunctions and CallInEditor
• Epic Games: Scripting the Editor using Blueprints
• UE4 – Be careful with the Construction Script