虚幻引擎Sequencer中的Python脚本 | 虚幻引擎 5.0 文档

你可以使用Python脚本自动执行和控制 Sequencer 的不同部分。本文介绍了将Python与Sequencer结合使用的主要方法，以及Sequencer的一些常见脚本示例。

先决条件

你对虚幻引擎中的Python脚本有一定的经验。
你了解如何使用Sequencer。

Sequencer Python术语

Sequencer使用以下术语：

Control Rig Python术语	描述
World	一种表示地图（可能存在并渲染Actor和组件）的对象（也称为 Level）。
LevelSequence	一种作为过场动画场景容器的资产（也称为 Sequence）。关卡序列（Level Sequence）含有可以绑定到不同对象从而为这些对象设置动画的数据和轨迹。
SequencerBindingProxy	一种用于定义由关卡序列绑定的Actor或组件的结构体（也称为 Binding）。
Possessable	一种绑定类型，描述关卡中存在的Actor或组件，其中的关卡序列可以拥有任何可动画化的属性。
Spawnable	一种绑定类型，描述仅当序列播放时才存在的Actor或组件。
MovieSceneTrack	一个位于 Binding（SequencerBindingProxy）下的对象，其中包含特定类型属性的所有编辑分段。例如，MovieScene3DTransformTrack > Actor / Component Transform@@@。
MovieSceneSection	一个位于 Track（MovieSceneTrack）下的对象，其中包含特定类型属性的所有通道、长度和参数。例如，MovieScene3DTransformSection > Pre / Post Roll, When Finished State, Active/Muted, Additive@@@。
MovieSceneScriptingChannel	一个位于 Section（MovieSceneSection）下的对象，其中包含用于为特定类型属性或子属性设置动画的所有关键帧。例如，MovieSceneScriptingFloatChannel > Location.X。
MovieSceneScriptingKey	一个表示特定类型通道中的关键帧的对象。例如，MovieSceneScriptingFloatKey。
FrameNumber	一个表示帧的结构体。
FrameRate	一个表示由2个整数（定义帧和秒）组成的分数的结构体。例如，30帧/秒可写为：30/1.

访问关卡序列

在Sequencer中编写Python脚本的第一步是访问将与你进行交互的主对象：LevelSequence。可通过多种方法来访问此对象，具体取决于你的情况。

简单访问

要访问存在于 内容浏览器（Content Browser） 中的关卡序列（Level Sequence），可以使用以下示例脚本。该序列目前不必处于打开状态，也不必存在于你当前的关卡中。该脚本假定关卡序列资产位于根内容文件夹中。

	import unreal

	# 获取关卡序列资产
	level_sequence = unreal.load_asset("/Game/LevelSequenceName")

	# 然后在Sequencer中将其打开
	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)

更改开始和结束时间

默认情况下，序列的播放范围设置为从第0帧开始，到第150帧结束（假设帧率为30fps）。可使用以下命令调整开始帧和结束帧：

	# 将播放范围设置为20-200
	level_sequence.set_playback_start(20)
	level_sequence.set_playback_end(200)

添加Actor

要从当前关卡中添加一个Actor以供Sequencer占有，请使用以下命令：

	# 获取Actor子系统以抓取选定的Actor
	actor_system = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)

	# 获取选定的Actor
	actor = actor_system.get_selected_level_actors()[0]

	# 将Actor作为可拥有物添加到关卡中
	actor_binding = level_sequence.add_possessable(actor)

	# 刷新以直观地查看添加的新绑定
	unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

Sequencer可以在序列期间生成新的Actor，而不是占有你关卡中的当前Actor。在这种情况下，你可以使用 add_spawnable_from_instance（这将吸纳对象），也可以使用 add_spawnable_from_class 并为其提供一个类。使用以下命令将可生成物添加到你的序列中：

	# 获取Actor子系统以抓取选定的Actor
	actor_system = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)

	# 获取选定的Actor
	actor = actor_system.get_selected_level_actors()[0]

	# 将Actor作为可生成物添加到关卡中
	actor_binding = level_sequence.add_spawnable_from_instance(actor)

	# 刷新以直观地查看添加的新绑定
	unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

创建轨迹和分段

还可以通过Python脚本添加轨迹（Tracks）和分段（Sections），每种轨迹类型都会显示分段类型。例如：

变换轨迹（Transform Tracks）定义为 unreal.MovieScene3DTransformTrack，其分段使用 unreal.MovieScene3DTransformSection。
骨骼网格体动画轨迹（Skeletal Mesh Animation Tracks）定义为 unreal.MovieSceneSkeletalAnimationTrack，其分段使用 unreal.MovieSceneSkeletalAnimationSection。

要添加轨迹和分段，请使用以下命令：

	# 使用绑定将轨迹添加到Sequencer（由轨迹类型指定）
	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()

某些分段可能要求定义属性。如果是动画轨迹（Animation Track）分段，必须定义动画资产。为此，请使用以下命令：

	# 获取动画序列资产
	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)

	# 为骨骼网格体和选定的Control Rig控制点设置轨迹过滤器
	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"))

其他Sequencer脚本资源

有关一般Sequencer Python脚本的更多资源，请参阅位于本地引擎路径中的Sequencer脚本示例：

…\Engine\Plugins\MovieScene\SequencerScripting\Content\Python