Python 스크립팅은 시퀀서(Sequencer) 의 다양한 부분을 자동화하고 제어하는 데 사용할 수 있습니다. 이 문서에서는 시퀀서와 함께 Python을 사용하는 기본 방법과 일반적인 시퀀서 스크립팅 예시를 간략하게 살펴봅니다.
전제조건
언리얼 엔진에서의 Python 스크립팅 경험이 어느 정도 있어야 합니다.
시퀀서를 사용하는 방법을 알고 있어야 합니다.
시퀀서 Python 용어
시퀀서에서는 다음과 같은 용어를 사용합니다.
컨트롤 릭 Python 용어 |
설명 |
---|---|
월드(World) |
액터와 컴포넌트가 존재할 수 있고 렌더링될 수 있는 맵을 나타내는 오브젝트로서 레벨(Level) 이라고도 합니다. |
레벨 시퀀스(LevelSequence) |
시네마틱 씬의 컨테이너인 에셋으로서 시퀀스(Sequence) 라고도 합니다. 레벨 시퀀스(Level Sequences)에는 애니메이팅을 위해 다양한 오브젝트에 바운드될 수 있는 트랙과 데이터가 포함되어 있습니다. |
시퀀서 바인딩 프록시(SequencerBindingProxy) |
레벨 시퀀스에 의해 바운드되는 컴포넌트 또는 액터를 정의하는 구조체로서, 바인딩(Binding) 이라고도 합니다. |
포제서블(Possessable) |
레벨 시퀀스가 애니메이팅 가능한 프로퍼티를 소유할 수 있는 레벨에 존재하는 컴포넌트나 액터를 설명하는 바인딩 타입입니다. |
스포너블(Spawnable) |
시퀀스가 재생되는 동안만 존재하는 컴포넌트나 액터를 설명하는 바인딩 타입입니다. |
무비 씬 트랙(MovieSceneTrack) |
바인딩 (SequencerBindingProxy) 아래 있는 오브젝트로서 특정 타입의 프로퍼티에 대한 모든 편집 섹션을 포함하고 있습니다. 예를 들어, MovieScene3DTransformTrack > 액터/컴포넌트 트랜스폼(Actor/Component Transform) 이 있습니다. |
무비 씬 섹션(MovieSceneSection) |
트랙 (MovieSceneTrack) 아래 있는 오브젝트로서 특정 타입의 프로퍼티에 대한 모든 채널과 길이, 파라미터를 포함하고 있습니다. 예를 들어, MovieScene3DTransformSection > 프리롤/포스트롤(Pre / Post Roll), 스테이트 완료 시(When Finished State), 활성/비활성(Active/Muted), 애디티브(Additive) 가 있습니다. |
무비 씬 스크립팅 채널(MovieSceneScriptingChannel) |
섹션 (MovieSceneSection) 아래 있는 오브젝트로서 특정 타입의 프로퍼티나 서브 프로퍼티를 애니메이팅할 모든 키프레임을 포함하고 있습니다. 예를 들어, MovieSceneScriptingFloatChannel > Location.X 가 있습니다. |
무비 씬 스크립팅 키(MovieSceneScriptingKey) |
특정 타입의 채널에서 키프레임을 나타내는 오브젝트입니다. 예를 들어, MovieSceneScriptingFloatKey 가 있습니다. |
프레임 번호(FrameNumber) |
프레임을 나타내는 구조체입니다. |
프레임 레이트(FrameRate) |
정수 2개로 프레임과 초를 정의하는 분수를 나타내는 구조체입니다. 예를 들어, 초당 30프레임은 30/1 이라고 씁니다. |
레벨 시퀀스 액세스
시퀀서에서 Python 스크립팅의 첫 단계는 상호작용할 메인 오브젝트인 레벨 시퀀스(LevelSequence) 에 액세스하는 것입니다. 상황에 따라 몇 가지 방법이 있습니다.
단순 액세스
다음과 같은 예시 스크립트를 사용하여 콘텐츠 브라우저(Content Browser) 에 있는 레벨 시퀀스에 액세스할 수 있습니다. 해당 시퀀스가 현재 레벨에 열려 있거나 존재하지 않아도 됩니다. 이 스크립트에서는 레벨 시퀀스 에셋이 루트 콘텐츠 폴더에 있다고 가정합니다.
import unreal
# 레벨 시퀀스 에셋을 얻습니다.
level_sequence = unreal.load_asset("/Game/LevelSequenceName")
# 그런 다음, 시퀀서에서 엽니다.
unreal.LevelSequenceEditorBlueprintLibrary.open_level_sequence(level_sequence)
현재 레벨 시퀀스 액세스하기
다음 스크립트를 사용하여 현재 열려 있는 레벨 시퀀스에 액세스할 수도 있습니다.
import unreal
# 현재 열려 있는 레벨 시퀀스를 얻습니다.
level_sequence = unreal.LevelSequenceEditorBlueprintLibrary.get_current_level_sequence()
레벨 시퀀스 생성 및 열기
다음 스크립트를 사용하여 새 레벨 시퀀스 에셋을 생성하고 열 수 있습니다.
import unreal
# 에셋 툴을 얻습니다.
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
# 루트 콘텐츠 폴더에서 LevelSequenceName이라는 이름의 레벨 시퀀스를 생성합니다.
level_sequence = unreal.AssetTools.create_asset(asset_tools, asset_name = "LevelSequenceName", package_path = "/Game/", asset_class = unreal.LevelSequence, factory = unreal.LevelSequenceFactoryNew())
레벨 시퀀스 쿼리 및 편집
Python에서 레벨 시퀀스에 액세스한 후에는 레벨 시퀀스를 변경할 수 있습니다. 다양한 방식으로 시퀀스에 영향을 줄 수 있으며, 다음은 그중 일부 예시입니다.
프레임 레이트 변경하기
기본적으로 레벨 시퀀스는 초당 30프레임(fps)의속도로 재생됩니다. 다음 명령을 사용하여 이 재생 속도를 변경할 수 있습니다.
# 프레임 레이트 오브젝트를 생성하고 원하는 fps로 설정합니다.
frame_rate = unreal.FrameRate(numerator = 60, denominator = 1)
# 디스플레이 레이트를 설정합니다.
level_sequence.set_display_rate(frame_rate)
시작 및 끝 시간 변경하기
기본적으로 시퀀스의 재생 범위는 프레임 레이트 30fps를 가정할 때 프레임 0에서 시작하여 프레임 150에서 종료되도록 설정되어 있습니다. 다음 명령으로 시작 및 끝 프레임 모두를 조정할 수 있습니다.
# 재생 범위를 20~200으로 설정합니다.
level_sequence.set_playback_start(20)
level_sequence.set_playback_end(200)
액터 추가하기
다음 명령을 사용하여 현재 레벨에서 시퀀서가 소유할 액터를 추가할 수 있습니다.
# 선택한 액터를 얻기 위해 액터 서브시스템을 가져옵니다.
actor_system = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
# 선택한 액터를 얻습니다.
actor = actor_system.get_selected_level_actors()[0]
# 레벨에 액터를 포제서블로 추가합니다.
actor_binding = level_sequence.add_possessable(actor)
# 새로 추가된 바인딩을 볼 수 있도록 새로 고칩니다.
unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()
레벨의 현재 액터를 소유하는 대신, 시퀀서는 시퀀스가 지속되는 동안 새로운 액터를 스폰할 수 있습니다. 이 경우 add_spawnable_from_instance
를 사용하여 오브젝트 를 받거나, add_spawnable_from_class
를 사용하여 클래스 를 제공할 수 있습니다. 다음 명령으로 시퀀스에 스포너블을 추가할 수 있습니다.
# 선택한 액터를 얻기 위해 액터 서브시스템을 가져옵니다.
actor_system = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
# 선택한 액터를 얻습니다.
actor = actor_system.get_selected_level_actors()[0]
# 레벨에 액터를 스포너블로 추가합니다.
actor_binding = level_sequence.add_spawnable_from_instance(actor)
# 새로 추가된 바인딩을 볼 수 있도록 새로 고칩니다.
unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()
트랙 및 섹션 생성하기
또한, 각 트랙 타입이 섹션 타입을 알려주는 Python 스크립팅을 통해 트랙과 섹션을 추가할 수도 있습니다. 예시는 다음과 같습니다.
트랜스폼 트랙은
unreal.MovieScene3DTransformTrack
으로 정의되며, 해당 섹션은unreal.MovieScene3DTransformSection
을 사용합니다.스켈레탈 메시 애니메이션 트랙은
unreal.MovieSceneSkeletalAnimationTrack
으로 정의되며, 해당 섹션은unreal.MovieSceneSkeletalAnimationSection
을 사용합니다.
다음 명령을 사용하여 트랙과 섹션을 추가할 수 있습니다.
# 바인딩을 사용하여 시퀀서에 트랙 추가 - 트랙 타입에 의해 지정됨
transform_track = actor_binding.add_track(unreal.MovieScene3DTransformTrack)
anim_track = actor_binding.add_track(unreal.MovieSceneSkeletalAnimationTrack)
# 범위, 파라미터 또는 프로퍼티를 조작할 수 있도록 트랙에 섹션을 추가합니다.
transform_section = transform_track.add_section()
anim_section = anim_track.add_section()
# 레벨 시퀀스 시작 프레임 및 끝 프레임을 얻습니다.
start_frame = level_sequence.get_playback_start()
end_frame = level_sequence.get_playback_end()
# 섹션 범위를 레벨 시퀀스 시작 프레임과 끝 프레임으로 설정합니다.
transform_section.set_range(start_frame, end_frame)
anim_section.set_range(start_frame, end_frame)
# 새로 추가된 트랙 및 섹션을 볼 수 있도록 새로 고칩니다.
unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()
섹션에 따라서는 섹션에 프로퍼티를 정의해야 할 수도 있습니다. 애니메이션 트랙 섹션의 경우, 애니메이션 에셋을 정의해야 합니다. 다음 명령을 사용하여 그러한 작업을 수행할 수 있습니다.
# 애니메이션 시퀀스 에셋을 얻습니다.
anim_seq = unreal.load_asset("/Game/Mannequin/Animations/ThirdPersonWalk")
#섹션을 얻고 파라미터를 얻고 애니메이션을 애님 시퀀스 에셋으로 설정합니다.
anim_section.params.animation = anim_seq
트랙 필터링
트랙 필터링 명령은 다음과 같은 용도로 사용할 수도 있습니다.
# 트랙 필터 이름을 얻어 출력합니다.
track_filter_names = unreal.LevelSequenceEditorBlueprintLibrary.get_track_filter_names()
for track_filter_name in track_filter_names:
print(track_filter_name)
# 스켈레탈 메시 및 선택한 컨트롤 릭 컨트롤에 대한 트랙 필터를 설정합니다.
unreal.LevelSequenceEditorBlueprintLibrary.set_track_filter_enabled("Skeletal Mesh", True)
unreal.LevelSequenceEditorBlueprintLibrary.set_track_filter_enabled("Selected Control Rig Controls", True)
# 트랙별 필터 활성화 상태를 봅니다.
print(unreal.LevelSequenceEditorBlueprintLibrary.is_track_filter_enabled("Event"))
print(unreal.LevelSequenceEditorBlueprintLibrary.is_track_filter_enabled("Skeletal Mesh"))
추가 시퀀서 스크립팅 리소스
전반적인 시퀀서 Python 스크립팅에 대한 추가 리소스는 해당 로컬 엔진 경로에 있는 시퀀서 스크립팅 예제를 참조하세요.
…\Engine\Plugins\MovieScene\SequencerScripting\Content\Python