시퀀서에서 Python 스크립팅

시퀀서와 함께 사용하는 일반 Python 스크립팅 명령 및 기능을 알아봅니다.

Python 스크립팅은 시퀀서(Sequencer) 의 다양한 부분을 자동화하고 제어하는 데 사용할 수 있습니다. 이 문서에서는 시퀀서와 함께 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