DefaultCompletionMode

DefaultCompletionMode

#Overview

name: DefaultCompletionMode

The value of this variable can be defined or overridden in .ini config files. 3 .ini config files referencing this setting variable.

It is referenced in 16 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DefaultCompletionMode is to define the default behavior for how a sequence or section should handle its state after playback has finished. This setting is used in the MovieScene system, which is responsible for managing cinematic sequences and animations in Unreal Engine 5.

DefaultCompletionMode is primarily used in the MovieScene subsystem, which is a core part of Unreal Engine’s sequencer and cinematics features. It’s referenced in various modules related to sequence compilation, evaluation, and entity management within the MovieScene framework.

The value of this variable is typically set in the UMovieSceneSequence class, which is a configuration property. It can be overridden at the sequence or section level.

This variable interacts with the EMovieSceneCompletionMode enum, which defines the possible completion modes (such as RestoreState, KeepState, or ProjectDefault). It also interacts with individual section completion modes, where if a section’s completion mode is set to ProjectDefault, it will fall back to using the DefaultCompletionMode of its parent sequence.

Developers must be aware that this variable affects how the engine handles the state of objects after a sequence has finished playing. It can impact performance and behavior, especially in complex sequences or when dealing with many animated objects.

Best practices when using this variable include:

  1. Consider the implications of each completion mode on performance and desired behavior.
  2. Use ProjectDefault at the section level to maintain consistency across a sequence, unless specific sections need different behavior.
  3. Be mindful of the hierarchy of completion modes (section-level overrides sequence-level).
  4. When using RestoreState, be aware of the potential performance cost of storing and restoring object states.
  5. Consider using KeepState for better performance when the post-sequence state is not critical.
  6. Ensure that the chosen completion mode aligns with the overall design of your sequence and game logic.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3409, section: [/Script/LevelSequence.LevelSequence]

Location: <Workspace>/Engine/Config/BaseEngine.ini:3412, section: [/Script/TemplateSequence.TemplateSequence]

Location: <Workspace>/Engine/Plugins/Experimental/Avalanche/Config/DefaultAvalanche.ini:278, section: [/Script/Avalanche.AvaAnimation]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/Compilation/IMovieSceneTrackTemplateProducer.cpp:18

Scope (from outer to inner):

file
function     FMovieSceneTrackCompilerArgs::FMovieSceneTrackCompilerArgs

Source code excerpt:

	if (UMovieSceneSequence* OuterSequence = Track->GetTypedOuter<UMovieSceneSequence>())
	{
		DefaultCompletionMode = OuterSequence->DefaultCompletionMode;
	}
	else
	{
		DefaultCompletionMode = EMovieSceneCompletionMode::RestoreState;
	}
}

FMovieSceneEvaluationTrack IMovieSceneTrackTemplateProducer::GenerateTrackTemplate(UMovieSceneTrack* SourceTrack) const
{
	FMovieSceneEvaluationTrack TrackTemplate = FMovieSceneEvaluationTrack(FGuid());

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/Compilation/IMovieSceneTrackTemplateProducer.cpp:83

Scope (from outer to inner):

file
function     EMovieSceneCompileResult IMovieSceneTrackTemplateProducer::Compile

Source code excerpt:

		if (NewTemplate.IsValid())
		{
			NewTemplate->SetCompletionMode(Section->GetCompletionMode() == EMovieSceneCompletionMode::ProjectDefault ? Args.DefaultCompletionMode : Section->GetCompletionMode());
			NewTemplate->SetSourceSection(Section);

			OutTrack.AddChildTemplate(MoveTemp(NewTemplate));
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/Compilation/MovieSceneCompiledDataManager.cpp:1198

Scope (from outer to inner):

file
function     void UMovieSceneCompiledDataManager::CompileTrack

Source code excerpt:

			}

			Args.DefaultCompletionMode = Sequence->DefaultCompletionMode;

			TrackTemplateProducer->GenerateTemplate(Args);

			TrackIdentifier = TrackTemplate->GetLedger().FindTrackIdentifier(Track->GetSignature());
		}

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/Compilation/MovieSceneCompiledDataManager.cpp:1221

Scope (from outer to inner):

file
function     void UMovieSceneCompiledDataManager::CompileTrack

Source code excerpt:


	const FMovieSceneTrackEvaluationField& EvaluationField = Track->GetEvaluationField();
	const EMovieSceneCompletionMode DefaultCompletionMode = Sequence->DefaultCompletionMode;
	const bool bAddKeepStateDeterminismFences = CVarAddKeepStateDeterminismFences.GetValueOnGameThread();
	for (const FMovieSceneTrackEvaluationFieldEntry& Entry : EvaluationField.Entries)
	{
		if (bAddKeepStateDeterminismFences && Entry.Section)
		{
			// If a section is KeepState, we need to make sure to evaluate it on its last frame so that the value that "sticks" is correct.

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/Compilation/MovieSceneCompiledDataManager.cpp:1232

Scope (from outer to inner):

file
function     void UMovieSceneCompiledDataManager::CompileTrack

Source code excerpt:

			if (SectionRange.HasUpperBound() &&
					(SectionCompletionMode == EMovieSceneCompletionMode::KeepState ||
					 (SectionCompletionMode == EMovieSceneCompletionMode::ProjectDefault && DefaultCompletionMode == EMovieSceneCompletionMode::KeepState)))
			{
				// We simply use the end time of the section for the fence, regardless of whether it's inclusive or exclusive.
				// When exclusive, the ECS system will query entities just before that time, but still pass that time for
				// evaluation purposes, so we will get the correct evaluated values.
				const FFrameNumber FenceTime(SectionRange.GetUpperBoundValue());
				OutCompilerData->DeterminismData.Fences.Add(FenceTime);

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneSequenceUpdaters.cpp:297

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     void FSequenceUpdater_Flat::Update

Source code excerpt:

		Params.InstanceHandle = InstanceHandle;
		Params.RootInstanceHandle = InstanceHandle;
		Params.DefaultCompletionMode = Sequence->DefaultCompletionMode;
		Params.HierarchicalBias = 0;
		Params.bDynamicWeighting = bDynamicWeighting.Get(false);

		SequenceInstance.Ledger.UpdateEntities(Linker, Params, ComponentField, EntitiesScratch);
	}

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneSequenceUpdaters.cpp:316

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     void FSequenceUpdater_Flat::Update

Source code excerpt:

			Params.InstanceHandle = InstanceHandle;
			Params.RootInstanceHandle = InstanceHandle;
			Params.DefaultCompletionMode = Sequence->DefaultCompletionMode;
			Params.HierarchicalBias = 0;
			Params.bDynamicWeighting = bDynamicWeighting.Get(false);

			SequenceInstance.Ledger.UpdateOneShotEntities(Linker, Params, ComponentField, EntitiesScratch);
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneSequenceUpdaters.cpp:601

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     void FSequenceUpdater_Hierarchical::Update

Source code excerpt:

				Params.InstanceHandle = RootInstanceHandle;
				Params.RootInstanceHandle = RootInstanceHandle;
				Params.DefaultCompletionMode = RootSequence->DefaultCompletionMode;
				Params.HierarchicalBias = 0;
				Params.bDynamicWeighting = bDynamicWeighting.Get(false);

				RootInstance.Ledger.UpdateEntities(Linker, Params, RootComponentField, EntitiesScratch);
			}

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneSequenceUpdaters.cpp:620

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     void FSequenceUpdater_Hierarchical::Update

Source code excerpt:

					Params.InstanceHandle = RootInstanceHandle;
					Params.RootInstanceHandle = RootInstanceHandle;
					Params.DefaultCompletionMode = RootSequence->DefaultCompletionMode;
					Params.HierarchicalBias = 0;
					Params.bDynamicWeighting = bDynamicWeighting.Get(false);

					RootInstance.Ledger.UpdateOneShotEntities(Linker, Params, RootComponentField, EntitiesScratch);
				}
			}

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneSequenceUpdaters.cpp:705

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     void FSequenceUpdater_Hierarchical::Update

Source code excerpt:

				Params.InstanceHandle = SubSequenceHandle;
				Params.RootInstanceHandle = RootInstanceHandle;
				Params.DefaultCompletionMode = SubSequence->DefaultCompletionMode;
				Params.HierarchicalBias = SubData->HierarchicalBias;
				Params.SubSectionFlags = SubData->AccumulatedFlags;
				Params.bPreRoll  = bIsPreRoll;
				Params.bPostRoll = bIsPostRoll;
				Params.bDynamicWeighting = bDynamicWeighting.Get(false); // Always inherit dynamic weighting flags

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/Evaluation/PreAnimatedState/MovieScenePreAnimatedCaptureSource.cpp:64

Scope (from outer to inner):

file
function     FScopedPreAnimatedCaptureSource::FScopedPreAnimatedCaptureSource

Source code excerpt:

	if (CompletionMode == EMovieSceneCompletionMode::ProjectDefault)
	{
		CompletionMode = TrackInstanceInput.Section->GetTypedOuter<UMovieSceneSequence>()->DefaultCompletionMode;
	}
	bWantsRestoreState = (CompletionMode == EMovieSceneCompletionMode::RestoreState);

	FScopedPreAnimatedCaptureSource*& CaptureSourcePtr = GetCaptureSourcePtr();
	PrevCaptureSource = CaptureSourcePtr;
	CaptureSourcePtr = this;

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/MovieSceneSection.cpp:329

Scope (from outer to inner):

file
function     void UMovieSceneSection::BuildDefaultComponents

Source code excerpt:

			EnumHasAnyFlags(Params.Sequence.SubSectionFlags, EMovieSceneSubSectionFlags::OverrideRestoreState) ||
			(EvalOptions.CompletionMode == EMovieSceneCompletionMode::RestoreState) ||
			(EvalOptions.CompletionMode == EMovieSceneCompletionMode::ProjectDefault && Params.Sequence.DefaultCompletionMode == EMovieSceneCompletionMode::RestoreState)
		);

	TComponentTypeID<FEasingComponentData> EasingComponentID = Components->Easing;
	FComponentTypeID RestoreStateTag = Components->Tags.RestoreState;

	const bool bHasForcedTime      = Params.EntityMetaData && Params.EntityMetaData->ForcedTime != TNumericLimits<int32>::Lowest();

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Public/Compilation/IMovieSceneTrackTemplateProducer.h:31

Scope: file

Source code excerpt:

	FGuid ObjectBindingId;

	EMovieSceneCompletionMode DefaultCompletionMode;

	UMovieSceneTrack* Track;

	/** The generator responsible for generating the template */
	IMovieSceneTemplateGenerator* Generator;

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Public/EntitySystem/IMovieSceneEntityProvider.h:68

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     FEntityImportSequenceParams

Source code excerpt:

		: HierarchicalBias(0)
		, SequenceID(MovieSceneSequenceID::Root)
		, DefaultCompletionMode(EMovieSceneCompletionMode::KeepState)
		, SubSectionFlags(EMovieSceneSubSectionFlags::None)
		, bPreRoll(false)
		, bPostRoll(false)
		, bDynamicWeighting(false)
	{}

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Public/EntitySystem/IMovieSceneEntityProvider.h:81

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene

Source code excerpt:

	FRootInstanceHandle RootInstanceHandle;

	EMovieSceneCompletionMode DefaultCompletionMode;
	EMovieSceneSubSectionFlags SubSectionFlags;

	bool bPreRoll : 1;
	bool bPostRoll : 1;
	bool bDynamicWeighting : 1;
};

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Public/MovieSceneSequence.h:361

Scope (from outer to inner):

file
class        class UMovieSceneSequence : public UMovieSceneSignedObject

Source code excerpt:

	/* The default completion mode for this movie scene when a section's completion mode is set to project default */
	UPROPERTY(config)
	EMovieSceneCompletionMode DefaultCompletionMode;

protected:

	/**
	 * true if the result of GetParentObject is significant in object resolution for LocateBoundObjects.
	 * When true, if GetParentObject returns nullptr, the PlaybackContext will be used for LocateBoundObjects, other wise the object's parent will be used