Sequencer中的Python脚本

了解与Sequencer一起使用的常见Python脚本命令和功能。

Choose your operating system:

Windows

macOS

Linux

你可以使用Python脚本自动执行和控制 Sequencer 的不同部分。本文介绍了将Python与Sequencer结合使用的主要方法,以及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),每种轨迹类型都会显示分段类型。例如:

要添加轨迹和分段,请使用以下命令:

# 使用绑定将轨迹添加到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