UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

博主： glados
发布时间：2022 年 10 月 19 日
567 次浏览
暂无评论
11882字数
分类：技术美术游戏开发

# UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

本文内容可能只能在 UE5 下有用，未在 UE4 环境下实验过。

## 背景

遇到了一个美术需求，需要批量读取一段动画，制作成 UE 中的 Level Sequence，然后给动画添加几个 Event Track。随后，需要在 Event Track 中添加 Trigger Event，设置插件 uDraper 布料的缓存数据路径。总之，最终效果如下：

![20221017111235](https://images-1300215216.cos.ap-guangzhou.myqcloud.com/Blog/20221017111235.png)
_无视上图中红色的报错部分，这是因为我截图的时候没有打开对应的关卡，Sequence 找不到相关的引用。打码部分是动画名字，工程内容不太方便暴露所以打码_

至于为什么非得要用 Event Track 来设置路径，而不是在 Actor 的 Component 相关属性中直接设置路径，然后添加到 Sequence 中，只能说这是 uDraper 插件的问题，直接设置会弹出个弹窗说“路径缺少 xxxx 文件”（因为该路径只有缓存数据而没有布料相关的数据），但是如果在 Event Track 中通过 Event 帧调用函数`Cache(缓存路径)`设置就没这个问题，能够正常读取缓存文件。因此，就只能这么干了。

可能有点绕，其实就是我需要在动画的第一帧调用 uDraper 提供的蓝图函数 `Cache`，并传入`DirectoryPath`类型的对象来指定布料缓存数据路径。

另外，如果读者不太清楚或者没试过在 Level Sequence 中触发 Event，可以看看[官方介绍文档](https://docs.unrealengine.com/5.0/en-US/fire-blueprint-events-during-cinematics-in-unreal-engine/)，里面详细说明了如何在 Sequence 中添加 Event 帧，在指定的帧调用函数，从而实现在某个特定时刻执行某种行为、打开门、生成角色等功能。此文档中的操作流程和我们在代码中相关流程是一致的，因此后面我不会解释代码中为什么会出现某个步骤。

## Python 脚本

直接进入正题，我们先看一眼完整的 Python 脚本：

```Python
def main():
    # 拿到场景编辑 subsystem
    level_editor = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
    # 从关卡中获取 actor，注意获取的时候确认名字就叫这个，最好选中后用指令打印出来名字
    # 因为在编辑器的场景预览中显示的名字不一定就是引擎设置的真名
    actor = unreal.find_object(level_editor.get_current_level(), "guzhuang_C_1")
    camera_actor = unreal.find_object(level_editor.get_current_level(), "Camera_0")
    # 获取组件
    cloth = unreal.find_object(actor, "cloth")

# 这里 asset_list 是一个列表，里面全是 animation 的路径，类似于 /Game/Anim/dance.dance
    for i in asset_list:
        # 取个名字
        cur_anim = i.split("/")[-1].split(".")[0]
        asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
        # 传入参数创建新的 sequence，seq_path 是一个全局变量，配置了 sequence 的保存路径
        lvl_seq = unreal.AssetTools.create_asset(
            asset_tools, asset_name=cur_anim, package_path=seq_path, asset_class=unreal.LevelSequence, factory=unreal.LevelSequenceFactoryNew())
        # _fps 也是全局配置，保存了 sequence 的帧率
        frame_rate = unreal.FrameRate(numerator=_fps, denominator=1)
        lvl_seq.set_display_rate(frame_rate)

# 创建 actor binding
        actor_binding = lvl_seq.add_possessable(actor)

# 添加场景中的 camera，其实可以在脚本中创建新的，但是我发现创建 camera 的话在脚本执行完后新建的
        # Camera 会一直保留在场景中，所以最终还是选择直接用场景中现有的 camera
        cam_cut_track = lvl_seq.add_master_track(
            unreal.MovieSceneCameraCutTrack)
        cam_cut_section = cam_cut_track.add_section()

# 添加 camera section
        cam_binding = lvl_seq.add_possessable(camera_actor)
        cam_binding_id = lvl_seq.make_binding_id(
            cam_binding, unreal.MovieSceneObjectBindingSpace.LOCAL)
        cam_cut_section.set_camera_binding_id(cam_binding_id)

# 添加动画
        loaded_asset = unreal.AnimSequence.cast(
            unreal.EditorAssetLibrary.load_asset(i))
        frame_num = loaded_asset.get_editor_property(
            'number_of_sampled_keys')
        frame_rate = loaded_asset.get_editor_property('target_frame_rate')

# 设置 sequence 有内容的范围
        lvl_seq.set_playback_start(0)
        lvl_seq.set_playback_end(frame_num)
        unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

### 添加动画 track ###
        anim_track = actor_binding.add_track(
            unreal.MovieSceneSkeletalAnimationTrack)
        # 添加动画
        anim_section = anim_track.add_section()
        anim_section.set_range(0, frame_num)
        anim_section.params.animation = loaded_asset

# 设置动画范围
        cam_cut_section.set_range(0, frame_num)

### draper settings ###
        # cloth
        cloth_binding = lvl_seq.add_possessable(cloth)
        cloth_track = cloth_binding.add_track(unreal.MovieSceneEventTrack)
        cloth_section = cloth_track.add_event_trigger_section()
        cloth_section.set_range(0, frame_num)

# 其实今天的重点在这里
        cloth_channel = cloth_section.get_channels()[0]
        cloth_cache_binding = unreal.SequencerTools.create_quick_binding(
            lvl_seq, cloth, "Cache", False)
        cloth_new_event = unreal.SequencerTools.create_event(lvl_seq, cloth_section, cloth_cache_binding, ["(path=\"D:/UGit/XiaoLan_PC/content/XiaoLan/Effects/Character_Effects/BoWuGuan/ZhengChangShuoHua/cloth\")"])
        cloth_channel.add_key(time=unreal.FrameNumber(
            0), new_value=cloth_new_event)

# 此处省略对 skirt 和 waist 的操作，因为和上面 cloth 的步骤一样

# 保存最终生成的 seq
        unreal.EditorAssetLibrary.save_loaded_asset(lvl_seq, False)

unreal.log("=== INFO: Seq Creation is Completed ===")
```

比较简短，但是我们还是来看看具体做了什么，以及涉及到的相关接口、类。

### 查找场景中的 Actor

首先 `level_editor = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)`，这里通过`unreal.get_editor_susystem`函数（[相关文档](https://docs.unrealengine.com/5.0/en-US/PythonAPI/module/unreal.html)）获取了 Subsystem `unreal.LevelEditorSubsystem`（[相关文档](https://docs.unrealengine.om/5.0/en-US/PythonAPI/class/LevelEditorSubsystem.html)）。这里其实就是获取了场景编辑器 Subsystem 后面方便我们通过这个 subsystem 对场景中的 Actor 进行访问甚至修改。

顺带一提，其 Python 调用函数可以想象成在蓝图中调用函数，实际上确实也差不太多，都是通过反射实现的，所以蓝图能调用、访问 Python 都可以调用。

在获得了 Level Editor Subsystem 之后，我们就可以调用 `unreal.find_object` 函数，在当前打开了的场景中寻找到我们需要绑定到 sequence 的 actor 。这里需要注意一下，`find_object`中传入的 actor 名字一定要确认是引擎标识的名字，而不是在 Level Editor 中看到的名字（例如我遇到过在场景中物品名称叫做`guzhuang2`，实际上引擎中记载的名字是`guzhuang_C_1`），最好在场景编辑器中通过 Python(REPL)，选中 actor 并执行：

```Python
actor_system = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
actor = actor_system.get_selected_level_actors()[0]
print(actor)
```

确认 actor 的真实名称以及其是否保存在当前场景中（有些 actor 看起来是在当前场景中实际上可能是别的场景的 actor 的引用，可能是因为直接复制了别的场景的 actor 并粘贴到当前场景下），如果名字不对或者不是保存在当前场景中那么无法通过上面的`unreal.find_object(level_editor.get_current_level(), "guzhuang_C_1")`方法找到需要的 actor。

除了寻找 actor，实际上`find_object`也可以用来获取 actor 身上挂载的组件，例如上方例程中就通过`find_object`来获取名为`cloth`的组件。

在获取到我们需要的 actor 之后就可以开始 sequence 的创建了。

### 创建新的 sequence

其实就这部分：

```python
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
# 传入参数创建新的 sequence，seq_path 是一个全局变量，配置了 sequence 的保存路径
lvl_seq = unreal.AssetTools.create_asset(
    asset_tools, asset_name=cur_anim, package_path=seq_path, asset_class=unreal.LevelSequence, factory=unreal.LevelSequenceFactoryNew())
# _fps 也是全局配置，保存了 sequence 的帧率
frame_rate = unreal.FrameRate(numerator=_fps, denominator=1)
lvl_seq.set_display_rate(frame_rate)
```

先获取到 UE 辅助创建 asset 的工具类，直接`AssetTools.create_asset`并传入对应参数就行，这里没什么坑也没什么可以说的。创建好之后要注意`frame_rate`这块，一定要确保 sequence 的帧率是你想要的帧率。最后通过 LevelSequence 类函数`set_display_rate`设置帧率即可。

### 添加 Binding、Track、动画

然后我们看回到一开始的 sequence 截图，对照着截图来看会更容易理解接下来要做的事情。

![20221017111235](https://images-1300215216.cos.ap-guangzhou.myqcloud.com/Blog/20221017111235.png)

可以看到首先 Sequence 中会有一个对某个 actor 的引用，actor 下面有一个组件的引用（如 cloth 组件的引用），组件引用下面还有一个 Track；或者 actor 的引用下面就是直接一个 Track（如 Animation Track）。

因此对应的代码：

```python
# 创建 actor binding
actor_binding = lvl_seq.add_possessable(actor)

# ... 省略一部分无关代码

for i in asset_list:
    # 取个名字
    cur_anim = i.split("/")[-1].split(".")[0]

# 省略创建 sequence 的代码...
    # 添加动画
    loaded_asset = unreal.AnimSequence.cast(unreal.EditorAssetLibrary.load_asset(i))
    frame_num = loaded_asset.get_editor_property('number_of_sampled_keys')
    frame_rate = loaded_asset.get_editor_property('target_frame_rate')

# 设置 sequence 有内容的范围
    lvl_seq.set_playback_start(0)
    lvl_seq.set_playback_end(frame_num)
    unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

### 添加动画 track ###
    anim_track = actor_binding.add_track(unreal.MovieSceneSkeletalAnimationTrack)
    # 添加动画
    anim_section = anim_track.add_section()
    anim_section.set_range(0, frame_num)
    anim_section.params.animation = loaded_asset
```

还是比较简单明了的，通过`unreal.EditorAssetLibrary.load_asset`加载指定路径`i`的资产，并转换为`AnimSequence`格式，读取动画长度并创建 track，这里需要指定 track 的类型，例如如果是控制动画的 track，那么给 actor binding 创建 track 的时候就要指定是 `unreal.MovieSceneSkeletalAnimationTrack`。创建 track 后给 track 添加 section，最后内容、有效区间都是要在 section 上进行设定。

对于本例子中 `cloth` 等组件过程也是类似的步骤：

```python
# ...
cloth = unreal.find_object(actor, "cloth")

### draper settings ###
for i in asset_list:
    # 取个名字，这里用动画名字，实际上可以用别的名字
    cur_anim = i.split("/")[-1].split(".")[0]

# 省略上面提到过的部分 ...

# cloth
    cloth_binding = lvl_seq.add_possessable(cloth)
    cloth_track = cloth_binding.add_track(unreal.MovieSceneEventTrack)
    cloth_section = cloth_track.add_event_trigger_section()
    cloth_section.set_range(0, frame_num)

# 其实今天的重点在这里
    cloth_channel = cloth_section.get_channels()[0]
    cloth_cache_binding = unreal.SequencerTools.create_quick_binding(
        lvl_seq, cloth, "Cache", False)
    cloth_new_event = unreal.SequencerTools.create_event(lvl_seq, cloth_section, cloth_cache_binding, ["(path=\"D:/UGit/XiaoLan_PC/content/XiaoLan/Effects/Character_Effects/BoWuGuan/ZhengChangShuoHua/cloth\")"])
    cloth_channel.add_key(time=unreal.FrameNumber(
        0), new_value=cloth_new_event)
```

前面解释过的添加绑定、创建 track、section 部分这里跳过。重点主要在创建 `MovieSceneEvent` 帧这里。这里主要通过 `unreal.SequencerTools.create_quick_binding` 创建新的 `MovieSceneEvent` ，并且将此 Event 与传入的成员函数（要能在蓝图中调用的函数，这里也是借助了反射来找到要绑定的函数）进行绑定。顺带一提，这里绑定的是`cloth`的成员函数`Cache`，实际上也可以是其他类的成员函数。例如说我们的 Actor 有一个用来更新状态的成员函数`KillSelf`，那么可以变成`unreal.SequencerTools.create_quick_binding(lvl_seq, actor, "KillSelf", False)`，这里的 `actor` 是指向 Actor 的指针。`create_quick_binding` 函数的用法、参数可以在[官方文档](https://docs.unrealengine.com/5.0/en-US/PythonAPI/class/SequencerTools.html)查看。

创建了函数绑定之后就可以通过 `unreal.SequencerTools.create_event` 创建 `MovieSceneEvent` 了。比较值得注意的是 Payload 传入参数部分 `["(path=\"D:/UGit/XiaoLan_PC/content/XiaoLan/Effects/Character_Effects/BoWuGuan/ZhengChangShuoHua/cloth\")"]`。`Cache` 函数需要的参数是 `unreal.DirectoryPath` 类型的，而这里相当于通过传入 `unreal.DirectoryPath` 成员变量 `path` 的内容构造了一个 `unreal.DirectoryPath` 对象，并传入给 `Cache` 函数。

创建完成 `MovieSceneEvent` 后通过 `channel.add_key` 添加到 Track 中。上面提到的 `Payload` 的部分最终会通过 `ImportText` 函数处理，转换成 `unreal.DirectoryPath` 对象（所以如果你参数输入格式不对的话会提示 `ImportText xxxx 错误`）。最终结果：

![20221019093854](https://images-1300215216.cos.ap-guangzhou.myqcloud.com/Blog/20221019093854.png)

点开这些刚刚创建的帧，就会打开蓝图看到这个帧调用的函数：

![企业微信截图_16660116796034](https://images-1300215216.cos.ap-guangzhou.myqcloud.com/Blog/企业微信截图_16660116796034.png)

上面步骤完成后，`unreal.EditorAssetLibrary.save_loaded_asset(lvl_seq, False)` 保存即可（第二个参数是只有内容被更改后才保存，这里不做这种判断，直接保存。其实 Python 调用的 API 都可以参考蓝图的[文档](https://docs.unrealengine.com/5.0/en-US/BlueprintAPI/EditorScripting/Asset/SaveLoadedAsset/)）。

## 参考

1. [官方文档：Sequencer 概述](https://docs.unrealengine.com/5.0/zh-CN/unreal-engine-sequencer-movie-tool-overview/)
2. [官方文档：Sequencer 中的 Python 脚本](https://docs.unrealengine.com/5.0/zh-CN/python-scripting-in-sequencer-in-unreal-engine/)：这个还是挺有用的，必看
3. [官方文档：Scripting the Unreal Editor Using Python](https://docs.unrealengine.com/5.0/en-US/scripting-the-unreal-editor-using-python/)：必看，关于如何在编辑器中使用 UE
4. 官方例程，在`Engine\Plugins\MovieScene\MovieRenderPipeline\Content\Python`路径下、
5. [官方文档：unreal.MovieSceneEvent](https://docs.unrealengine.com/5.0/en-US/PythonAPI/class/MovieSceneEvent.html#unreal.MovieSceneEvent)
6. [官方文档：unreal 模块的 PythonAPI](https://docs.unrealengine.com/5.0/en-US/PythonAPI/module/unreal.html)
7. [UDN文档：UE4 Sequencer Python Cookbook](https://udn.unrealengine.com/s/article/UE4-Sequencer-Python-Cookbook)：可能需要开发者账号，不过内容不多可以不看
8. [Python in Unreal Engine | Inside Unreal](https://www.youtube.com/watch?v=0guOMTiwmhk&ab_channel=UnrealEngine)
9. [PythonSamples](https://github.com/ue4plugins/PythonSamples)
10. [官方文档：Setting up Autocomplete for Editor Python Scripting](https://docs.unrealengine.com/4.27/en-US/ProductionPipelines/ScriptingAndAutomation/Python/Autocomplete/)

最后修改：2022 年 10 月 21 日

随缘

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

glados • 2022 年 10 月 19 日

# UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

本文内容可能只能在 UE5 下有用，未在 UE4 环境下实验过。

## 背景

可能有点绕，其实就是我需要在动画的第一帧调用 uDraper 提供的蓝图函数 `Cache`，并传入`DirectoryPath`类型的对象来指定布料缓存数据路径。

## Python 脚本

直接进入正题，我们先看一眼完整的 Python 脚本：

# 创建 actor binding
        actor_binding = lvl_seq.add_possessable(actor)

# 设置动画范围
        cam_cut_section.set_range(0, frame_num)

# 此处省略对 skirt 和 waist 的操作，因为和上面 cloth 的步骤一样

# 保存最终生成的 seq
        unreal.EditorAssetLibrary.save_loaded_asset(lvl_seq, False)

unreal.log("=== INFO: Seq Creation is Completed ===")
```

比较简短，但是我们还是来看看具体做了什么，以及涉及到的相关接口、类。

### 查找场景中的 Actor

顺带一提，其 Python 调用函数可以想象成在蓝图中调用函数，实际上确实也差不太多，都是通过反射实现的，所以蓝图能调用、访问 Python 都可以调用。

```Python
actor_system = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
actor = actor_system.get_selected_level_actors()[0]
print(actor)
```

除了寻找 actor，实际上`find_object`也可以用来获取 actor 身上挂载的组件，例如上方例程中就通过`find_object`来获取名为`cloth`的组件。

在获取到我们需要的 actor 之后就可以开始 sequence 的创建了。

### 创建新的 sequence

其实就这部分：

### 添加 Binding、Track、动画

然后我们看回到一开始的 sequence 截图，对照着截图来看会更容易理解接下来要做的事情。

![20221017111235](https://images-1300215216.cos.ap-guangzhou.myqcloud.com/Blog/20221017111235.png)

因此对应的代码：

```python
# 创建 actor binding
actor_binding = lvl_seq.add_possessable(actor)

# ... 省略一部分无关代码

for i in asset_list:
    # 取个名字
    cur_anim = i.split("/")[-1].split(".")[0]

# 设置 sequence 有内容的范围
    lvl_seq.set_playback_start(0)
    lvl_seq.set_playback_end(frame_num)
    unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

### 添加动画 track ###
    anim_track = actor_binding.add_track(unreal.MovieSceneSkeletalAnimationTrack)
    # 添加动画
    anim_section = anim_track.add_section()
    anim_section.set_range(0, frame_num)
    anim_section.params.animation = loaded_asset
```

对于本例子中 `cloth` 等组件过程也是类似的步骤：

```python
# ...
cloth = unreal.find_object(actor, "cloth")

### draper settings ###
for i in asset_list:
    # 取个名字，这里用动画名字，实际上可以用别的名字
    cur_anim = i.split("/")[-1].split(".")[0]

# 省略上面提到过的部分 ...

# 其实今天的重点在这里
    cloth_channel = cloth_section.get_channels()[0]
    cloth_cache_binding = unreal.SequencerTools.create_quick_binding(
        lvl_seq, cloth, "Cache", False)
    cloth_new_event = unreal.SequencerTools.create_event(lvl_seq, cloth_section, cloth_cache_binding, ["(path=\"D:/UGit/XiaoLan_PC/content/XiaoLan/Effects/Character_Effects/BoWuGuan/ZhengChangShuoHua/cloth\")"])
    cloth_channel.add_key(time=unreal.FrameNumber(
        0), new_value=cloth_new_event)
```

![20221019093854](https://images-1300215216.cos.ap-guangzhou.myqcloud.com/Blog/20221019093854.png)

点开这些刚刚创建的帧，就会打开蓝图看到这个帧调用的函数：

![企业微信截图_16660116796034](https://images-1300215216.cos.ap-guangzhou.myqcloud.com/Blog/企业微信截图_16660116796034.png)

## 参考

UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

杂记——游戏最重要的是什么

Typecho隐藏登录入口

Maya 帧率名称备忘录

用VS附带工具来查看dll文件包含的函数

Typecho添加Favicon

N-Cloth 复现——环境相关

UE4工程编译总是返回错误码6

关于使用 Sequence Recorder 无法录制面部 Morph Target 问题的解决方法

GCD最大公约数——辗转相除法实现

UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

UE5 中用 Python 接口创建 Level Sequence 与设置 TriggerEvent

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款