Download

UE4 Sequencer Python Cookbook

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

2 Likes

Hopefully, all of this will make it somewhere in the documentation. More examples and coverage of making/using unreal tools in your documentation and/or learning center would be very useful.