3-3. Scripted Actions | UE5 Editor Tools Deep Dive

01

Scripted Actions란?

Blutility의 확장 - 컨텍스트 메뉴 통합 액션

Scripted Actions는 에셋 또는 액터의 우클릭 컨텍스트 메뉴에 자동으로 통합되는 블루프린트 기반 에디터 액션입니다. Scripted Asset Actions와 Scripted Actor Actions 메뉴 섹션에 표시됩니다.

특성	Scripted Actions	일반 Blutility
실행 위치	우클릭 컨텍스트 메뉴에 자동 통합	에셋 우클릭 > Run
발견성	높음 (기존 메뉴에 표시)	낮음 (별도 실행 필요)
대상 필터링	클래스 기반 자동 필터	수동 필터
파라미터	대상 객체 자동 전달	수동 획득 필요

Scripted Actions 활성화

Editor Preferences > General > Asset Browser > Enable Scripted Actions가 활성화되어 있어야 합니다. UE5에서는 기본적으로 활성화되어 있습니다.

02

에셋 Scripted Actions 생성

콘텐츠 브라우저 에셋 메뉴에 커스텀 액션 추가

Step 1: AssetActionUtility 블루프린트 생성

콘텐츠 브라우저에서 Editor Utilities > Editor Utility Blueprint를 생성하고 부모 클래스로 AssetActionUtility를 선택합니다.

Step 2: 함수 작성

                    Blueprint 함수 구성
                    // 함수: FixNamingConvention
// Category: "Naming"
// Call In Editor: True

FixNamingConvention():
    Assets = GetSelectedAssets()

    for each Asset in Assets:
        if Asset is UStaticMesh:
            EnsurePrefix(Asset, "SM_")
        elif Asset is UMaterialInterface:
            EnsurePrefix(Asset, "M_")
        elif Asset is UTexture:
            EnsurePrefix(Asset, "T_")
        elif Asset is UBlueprint:
            EnsurePrefix(Asset, "BP_")

    ShowMessage("완료: {N}개 에셋 이름 수정")

// 함수: MoveToOrganizedFolder
// Category: "Organization"

MoveToOrganizedFolder():
    Assets = GetSelectedAssets()

    for each Asset in Assets:
        if Asset is UStaticMesh:
            TargetFolder = "/Game/Meshes/"
        elif Asset is UMaterialInterface:
            TargetFolder = "/Game/Materials/"
        elif Asset is UTexture:
            TargetFolder = "/Game/Textures/"

        EditorAssetLibrary::RenameLoadedAsset(
            Asset, TargetFolder + Asset.Name)
                

Step 3: 에셋 저장 위치

Scripted Actions 저장 위치

Scripted Actions 블루프린트는 /Game/ 경로 아래 어디에든 저장할 수 있습니다. 엔진은 프로젝트 내 모든 AssetActionUtility와 ActorActionUtility 서브클래스를 자동으로 검색하여 컨텍스트 메뉴에 등록합니다. 팀에서는 /Game/EditorUtilities/ScriptedActions/ 같은 전용 폴더를 사용하는 것을 권장합니다.

03

액터 Scripted Actions

뷰포트에서 선택된 액터에 대한 배치 작업

                    C++ - 고급 액터 스크립티드 액션
                    UCLASS(meta = (DisplayName = "Level Setup Utilities"))
class ULevelSetupActions : public UActorActionUtility
{
    GENERATED_BODY()

public:
    // 선택된 액터의 머티리얼을 일괄 교체
    UFUNCTION(CallInEditor, Category = "Materials")
    void ReplaceMaterial();

    // 선택된 액터를 그리드에 정렬
    UFUNCTION(CallInEditor, Category = "Transform")
    void SnapToGrid();

    // 선택된 액터들을 원형으로 배치
    UFUNCTION(CallInEditor, Category = "Transform")
    void ArrangeInCircle();

    // 배치 파라미터
    UPROPERTY(EditAnywhere, Category = "Transform")
    float CircleRadius = 500.0f;

    UPROPERTY(EditAnywhere, Category = "Transform")
    float GridSize = 100.0f;
};

void ULevelSetupActions::ArrangeInCircle()
{
    TArray<AActor*> SelectedActors;
    GEditor->GetSelectedActors()->
        GetSelectedObjects(SelectedActors);

    const int32 Count = SelectedActors.Num();
    if (Count == 0) return;

    // Undo 지원 트랜잭션
    GEditor->BeginTransaction(
        LOCTEXT("ArrangeCircle", "Arrange in Circle"));

    // 중심점 계산
    FVector Center = FVector::ZeroVector;
    for (AActor* Actor : SelectedActors)
    {
        Center += Actor->GetActorLocation();
    }
    Center /= Count;

    // 원형 배치
    for (int32 i = 0; i < Count; ++i)
    {
        float Angle = (2.0f * PI * i) / Count;
        FVector NewLocation = Center + FVector(
            FMath::Cos(Angle) * CircleRadius,
            FMath::Sin(Angle) * CircleRadius,
            0.0f);

        SelectedActors[i]->Modify();
        SelectedActors[i]->SetActorLocation(NewLocation);
    }

    GEditor->EndTransaction();
}
                

트랜잭션 필수

Scripted Actions에서 액터를 수정할 때는 반드시 BeginTransaction/EndTransaction과 Actor->Modify()를 호출하여 Undo/Redo를 지원해야 합니다. 사용자가 실수로 실행해도 되돌릴 수 있어야 합니다.

04

실전 활용 패턴

팀 프로젝트에서의 Scripted Actions 활용 전략

카테고리	액션 이름	설명
Naming	Fix Naming Convention	에셋 타입별 접두사 자동 적용
Naming	Batch Rename with Pattern	정규식 기반 일괄 이름 변경
Organization	Move to Organized Folder	타입별 폴더로 자동 분류
Organization	Find Unused Assets	참조되지 않는 에셋 검색
Mesh	Setup LODs	메시 LOD 일괄 설정
Mesh	Setup Collision	콜리전 프로파일 일괄 설정
Level	Align to Surface	표면에 자동 정렬
Level	Randomize Transform	위치/회전/스케일 랜덤화

핵심 요약

Scripted Actions는 에셋/액터 우클릭 메뉴에 자동 통합되어 높은 발견성과 접근성을 가진 에디터 액션입니다
AssetActionUtility와 ActorActionUtility를 상속하여 C++ 또는 블루프린트로 구현합니다
액터 수정 시 BeginTransaction/EndTransaction과 Modify()로 Undo/Redo를 반드시 지원합니다
GetSupportedClass로 특정 타입에만 표시되도록 필터링하여 메뉴 오염을 방지합니다
네이밍 컨벤션, 에셋 정리, LOD 설정, 트랜스폼 조작 등 반복적인 에디터 작업을 자동화하는 핵심 도구입니다

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: Scripted Action 등록 및 실행

UEditorUtilityLibrary를 활용하여 에디터에서 실행 가능한 Scripted Action을 만드세요. 현재 선택된 모든 Actor를 격자 패턴으로 정렬하는 'Grid Align' 액션을 구현하고, 간격과 방향을 파라미터로 받으세요.

실습 2: 조건부 Scripted Action

선택된 Actor의 타입에 따라 다른 작업을 수행하는 Scripted Action을 구현하세요. StaticMeshActor이면 LOD 설정을, PointLight이면 밝기/색상 조정을, BP Actor이면 변수값 일괄 수정을 수행하세요.

심화 과제: Undo/Redo 지원 Scripted Action

FScopedTransaction을 사용하여 Scripted Action의 모든 변경사항을 Undo/Redo로 되돌릴 수 있게 구현하세요. 복수의 Actor를 수정하는 복잡한 작업도 단일 Undo 단위로 묶어 처리하세요.