4-1. Python 환경 설정 | UE5 Editor Tools Deep Dive

01

UE5 Python 스크립팅 개요

Python으로 에디터를 자동화하는 방법과 제약사항

UE5는 Python 3.11+을 내장하고 있으며, unreal 모듈을 통해 에디터의 거의 모든 기능에 Python으로 접근할 수 있습니다.

특성	설명
Python 버전	3.11+ (UE5 내장)
핵심 모듈	`unreal` — 에디터 API 접근
실행 환경	에디터 전용 (런타임 게임에서 사용 불가)
실행 방식	Output Log 콘솔, .py 파일, init_unreal.py 자동 실행
외부 패키지	pip 설치 가능 (Engine/Binaries/ThirdParty/Python3)

에디터 전용

UE5 Python은 에디터 자동화 전용입니다. 패키징된 게임에서는 Python 스크립트가 동작하지 않습니다. 게임플레이 로직에는 블루프린트나 C++를 사용하세요.

02

Python 플러그인 활성화

단계별 Python 스크립팅 환경 설정 가이드

Step 1: 플러그인 활성화

Edit > Plugins에서 다음 플러그인을 활성화합니다:

Python Editor Script Plugin — 핵심 Python 스크립팅
Editor Scripting Utilities — EditorAssetLibrary, EditorLevelLibrary 등
Sequencer Scripting (선택) — 시퀀서 자동화

Step 2: 프로젝트 설정

Edit > Project Settings > Plugins > Python에서 설정:

설정	값	설명
`Additional Paths`	`Content/Python`	Python 스크립트 검색 경로
`Startup Scripts`	`init_unreal.py`	에디터 시작 시 자동 실행
`Developer Mode`	True	개발자 모드 (상세 로깅)

Step 3: 디렉터리 구조

                    프로젝트 Python 폴더 구조
                    Content/
└── Python/
    ├── init_unreal.py       # 에디터 시작 시 자동 실행
    ├── asset_tools.py       # 에셋 유틸리티
    ├── level_tools.py       # 레벨 유틸리티
    └── pipeline/
        ├── batch_import.py  # 배치 임포트
        └── batch_export.py  # 배치 익스포트
                

03

unreal 모듈 기초

Python에서 UE5 API에 접근하는 기본 패턴

                    Python - unreal 모듈 기초
                    import unreal

# ===== 핵심 서브시스템 접근 =====
editor_util = unreal.EditorUtilityLibrary()
asset_lib = unreal.EditorAssetLibrary()
level_lib = unreal.EditorLevelLibrary()
system_lib = unreal.SystemLibrary()

# ===== 로깅 =====
unreal.log("일반 로그 메시지")
unreal.log_warning("경고 메시지")
unreal.log_error("에러 메시지")

# ===== 에셋 경로 다루기 =====
# 에셋이 존재하는지 확인
exists = unreal.EditorAssetLibrary.does_asset_exist(
    "/Game/Meshes/SM_Chair")

# 에셋 로드
asset = unreal.EditorAssetLibrary.load_asset(
    "/Game/Meshes/SM_Chair")

# 에셋 정보 확인
if asset:
    unreal.log(f"Name: {asset.get_name()}")
    unreal.log(f"Class: {asset.get_class().get_name()}")

# ===== 선택된 에셋 가져오기 =====
selected = unreal.EditorUtilityLibrary.get_selected_assets()
for asset in selected:
    unreal.log(f"Selected: {asset.get_path_name()}")
                

자주 사용하는 unreal 클래스

클래스	용도
`unreal.EditorAssetLibrary`	에셋 CRUD, 경로 조작, 메타데이터
`unreal.EditorLevelLibrary`	레벨 액터 조작, 스폰, 선택
`unreal.EditorUtilityLibrary`	선택 에셋, 다이얼로그, 범용 유틸리티
`unreal.AssetTools`	에셋 생성, 임포트, 리임포트
`unreal.MaterialEditingLibrary`	머티리얼 파라미터 편집
`unreal.StaticMeshEditorSubsystem`	메시 LOD, 콜리전 설정
`unreal.LevelSequenceEditorBlueprintLibrary`	시퀀서 제어

04

init_unreal.py와 자동 실행

에디터 시작 시 자동으로 도구를 초기화하기

                    Content/Python/init_unreal.py
                    import unreal

# 에디터 시작 시 자동 실행되는 초기화 스크립트

def setup_menus():
    """커스텀 Python 메뉴 등록"""
    menus = unreal.ToolMenus.get()

    # Tools 메뉴에 Python 섹션 추가
    menu = menus.find_menu("LevelEditor.MainMenu.Tools")
    if menu:
        section = menu.add_section(
            "PythonTools",
            "Python Tools")

        entry = unreal.ToolMenuEntry(
            name="RunAssetAudit",
            type=unreal.MultiBlockType.MENU_ENTRY)
        entry.set_label("Run Asset Audit")
        entry.set_tool_tip("Python 에셋 감사 실행")
        entry.set_string_command(
            unreal.ToolMenuStringCommandType.PYTHON,
            "",
            "import asset_tools; asset_tools.run_audit()")
        section.add_entry(entry)

    menus.refresh_all_widgets()

def register_tick_callback():
    """에디터 틱 콜백 등록 (주의: 성능 영향)"""
    # 매 틱마다 호출 - 가벼운 작업만
    def on_tick(delta_time):
        pass  # 필요 시 로직 추가

    unreal.register_slate_post_tick_callback(on_tick)

# 초기화 실행
unreal.log("[Python] init_unreal.py loaded")
setup_menus()
                

init_unreal.py 주의사항

에디터 시작마다 실행되므로 무거운 작업은 피하세요
에러가 발생하면 에디터 시작이 지연될 수 있습니다
try/except로 안전하게 래핑하는 것을 권장합니다

SUMMARY

핵심 요약

UE5는 Python 3.11+을 내장하며, Python Editor Script Plugin과 Editor Scripting Utilities 플러그인 활성화가 필요합니다
unreal 모듈로 EditorAssetLibrary, EditorLevelLibrary 등 에디터 전체 API에 접근합니다
init_unreal.py에서 에디터 시작 시 자동으로 메뉴 등록, 콜백 설정 등 초기화를 수행합니다
Python 스크립트는 Content/Python/ 폴더에 배치하고, Project Settings에서 경로를 등록합니다
Python은 에디터 전용이며, 패키징된 게임에서는 동작하지 않습니다

PRACTICE

도전 과제

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

실습 1: UE5 Python 환경 활성화

플러그인 매니저에서 Python Editor Script Plugin을 활성화하세요. Output Log의 Python 콘솔에서 import unreal; print(unreal.EditorAssetLibrary.list_assets('/Game/', recursive=False))를 실행하여 루트 에셋 목록을 출력하세요.

실습 2: Python 스크립트 파일 실행

Content/Python/ 폴더에 hello_editor.py 파일을 만들고 unreal.log('Hello from Python!')을 작성하세요. 에디터 콘솔에서 py hello_editor.py로 실행하고, startup_script.py를 설정하여 에디터 시작 시 자동 실행되게 구성하세요.

심화 과제: Python 개발 환경 최적화

VS Code에서 UE5 Python 자동완성을 설정하세요. unreal.py stub 파일을 생성하여 IntelliSense를 활성화하고, 디버깅을 위한 debugpy 연동을 구성하세요. 자주 사용하는 유틸리티 함수를 패키지로 구조화하세요.