Dec 8, 2021.Knowledge
UE4 Sequencer Python Cookbook
Fundamentals
Sequencer is a cinematic editing tool that uses various specialized tracks which are used to define the makeup of scenes.
This document will be focusing on common practices/examples with general Sequencer Scripting.
Sequencer uses the following terminology:
- World: An object that represents a map in which actors and components can exist and be rendered (commonly referred to as Level)
- LevelSequence: An asset that is a container for cinematics scenes. Level Sequences hold data and tracks that can be bound to manipulate different objects to be animated (commonly referred to as Sequence)
- SequencerBindingProxy: A struct defining the actor or component that is bound by a Level Sequence (commonly referred to as Binding)
- Possessable: A type of binding describing an actor or component that exists in a Level, in which the Level Sequence can own any animatable properties
- Spawnable: A type of binding describing an actor or component that exists only while the Sequence is playing
- MovieSceneTrack: An object that lives under a Binding, which contains all sections of edits for a specific typed property (ex: MovieScene3DTransformTrack → Actor/Component Transform)
- MovieSceneSection: An object that lives under a Track, which contains all channels, length, and parameters for a specific typed property (ex: MovieScene3DTransformSection → Pre/Post Roll, When Finished State, Active/Muted, Additive )
- MovieSceneScriptingChannel: An object that lives under a Section which contains all keys that would animate a specific typed property or sub-property (ex: MovieSceneScriptingFloatChannel → Location.X)
- MovieSceneScriptingKey: An object that represents a keyframe in the specifically typed channel (ex: MovieSceneScriptingFloatKey)
- FrameNumber: A struct that represents a frame
- FrameRate: A struct that represents a fraction of 2 integers: # of frames/seconds (ex: 30 fps = 30/1)
Accessing the Level Sequence
The first step when scripting against any Sequences is to gain access to the main object you’ll interact with: The LevelSequence. There are several ways to do that depending on your situation.
Opening an existing Level Sequence
To access an existing rig you can simply load the asset (an example asset created at the root Content folder).
import unreal
Get a level sequence asset
level_sequence = unreal.load_asset("/Game/Test_LS")
Then open it in sequencer
unreal.LevelSequenceEditorBlueprintLibrary.open_level_sequence(level_sequence)
Getting the currently opened Level Sequence
Luckily there’s a function to access the currently opened sequence.
import unreal
Grab the current level sequence
level_sequence = unreal.LevelSequenceEditorBlueprintLibrary.get_current_level_sequence()
Creating a Level Sequence
To create a level sequence asset from scratch you can get the existing editor AssetTools and the LevelSeqeunceFactoryNew factory.
import unreal
Get asset tools
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
Creates a Level Sequence - /Game/Test_LS
level_sequence = unreal.AssetTools.create_asset(asset_tools, asset_name = “Test_LS”, package_path = “/Game/”, asset_class = unreal.LevelSequence, factory = unreal.LevelSequenceFactoryNew())
Editing the Level Sequence
Once you have access to a Level Sequence in Python, you can perform changes to it. There are a lot of ways to change the Sequence, we’ll focus on the most common ones in the examples below including:
- Changing the frame rate
- Setting the playback range
- Adding a Possessable/Spawnable Actor
- Adding Tracks and Sections
- Adding an Animation Sequence
Change the frame rate
By default, Level Sequences are at 30 fps. Depending on the usage, you may want to change it. To do so, change the display rate.
Create a frame rate object, change the numerator to the desired fps number
frame_rate = unreal.FrameRate(numerator = 60, denominator = 1)
Set the display rate
level_sequence.set_display_rate(frame_rate)
Extending the range of Level Sequence
By default, A Sequence’s playback range is set to start at frame 0 and end at frame 150. This can be easily edited.
Set the playback range to 20-200
level_sequence.set_playback_start(20)
level_sequence.set_playback_end(200)
Adding a Possessable Actor
To add an actor from your current Level for Sequencer to possess, grab the current Sequence, and use add_possesable.
Get the selected actor
actor = unreal.EditorLevelLibrary.get_selected_level_actors()[0]
Add actor to level as a spawnable
actor_binding = level_sequence.add_possessable(actor)
Refresh to visually see the new binding added
unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()
Adding a Spawnable Actor
Instead of possessing a level Actor, you may want to have Sequencer spawn one when a Sequence plays. In that case, you would want to use either add_spawnable_from_instance, which will take in an Object or you can use add_spawnable_from_class and give it a Class.
Get the selected actor
actor = unreal.EditorLevelLibrary.get_selected_level_actors()[0]
Add actor to level as a spawnable
actor_binding = level_sequence.add_spawnable_from_instance(actor)
Refresh to visually see the new binding added
unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()
Adding Tracks and Sections
Now that we have our bindings in bear, let’s add some tracks and sections. Each track and section has a different type. Sections are used to house different parameters and the frame range that would be active.
For Transforms, it will be unreal.MovieScene3DTransformTrack and unreal.MovieScene3DTransformSection.
For Skeletal animations, it will be unreal.MovieSceneSkeletalAnimationTrack and unreal.MovieSceneSkeletalAnimationSection.
Use the binding to add tracks into sequencer - specified by track type
transform_track = actor_binding.add_track(unreal.MovieScene3DTransformTrack)
anim_track = actor_binding.add_track(unreal.MovieSceneSkeletalAnimationTrack)
Add section to track to be able to manipulate range, parameters, or properties
transform_section = transform_track.add_section()
anim_section = anim_track.add_section()
Get level sequence start and end frame
start_frame = level_sequence.get_playback_start()
end_frame = level_sequence.get_playback_end()
Set section range to level sequence start and end frame
transform_section.set_range(start_frame, end_frame)
anim_section.set_range(start_frame, end_frame)
Refresh to visually see the new tracks and sections added
unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()
Adding Animation
Once an animation track and section is created, we can simply add an animation by setting the section’s parameters
Get the animation sequence asset
anim_seq = unreal.load_asset("/Game/Mannequin/Animations/ThirdPersonWalk")
Get the section, get the parameters, set animation to anim sequence asset
anim_section.params.animation = anim_seq
Additional Sequencer Scripting Resources
For more resources on Sequencer Scripting in general, look at the Sequencer Scripting examples located in your local engine path:
\Engine\Plugins\MovieScene\SequencerScripting\Content\Python
UE VERSION