Sequencer.AddKeepStateDeterminismFences

Sequencer.AddKeepStateDeterminismFences

#Overview

name: Sequencer.AddKeepStateDeterminismFences

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of Sequencer.AddKeepStateDeterminismFences is to control whether the Sequencer compiler should automatically add determinism fences for the last frame of KeepState sections in Unreal Engine 5’s animation sequencing system.

This setting variable is primarily used by the Sequencer subsystem, which is part of Unreal Engine’s animation and cinematics toolkit. It specifically affects the compilation process of movie scenes and tracks.

The value of this variable is set as a console variable (CVar) in the MovieScene module. It is initialized to true by default, meaning the feature is enabled out of the box.

The associated variable CVarAddKeepStateDeterminismFences directly interacts with Sequencer.AddKeepStateDeterminismFences. They share the same value and purpose.

Developers must be aware that enabling this variable (which is the default behavior) ensures consistent evaluation of the last frame of KeepState sections, regardless of framerate. However, this comes at the cost of an extra evaluation on frames that cross over the end time of KeepState sections.

Best practices when using this variable include:

  1. Keep it enabled (default) for most scenarios to ensure deterministic behavior across different framerates.
  2. If performance is a critical concern and you’re willing to sacrifice some consistency in animation playback, you might consider disabling it.
  3. When troubleshooting animation inconsistencies, especially those related to KeepState sections, check if this variable is enabled.

Regarding the associated variable CVarAddKeepStateDeterminismFences:

Its purpose is identical to Sequencer.AddKeepStateDeterminismFences, serving as the actual C++ variable that controls the behavior within the engine code.

It is used in the MovieScene module, specifically in the compilation process of movie scene tracks.

The value is set when the console variable is initialized, and it’s retrieved during the track compilation process using the GetValueOnGameThread() method.

This variable directly interacts with the logic that determines whether to add determinism fences for KeepState sections.

Developers should be aware that this variable is used in performance-sensitive areas of the engine, specifically during the compilation of movie scene tracks.

Best practices for CVarAddKeepStateDeterminismFences align with those of Sequencer.AddKeepStateDeterminismFences, as they are essentially the same setting exposed in different ways.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<bool> CVarAddKeepStateDeterminismFences(
	TEXT("Sequencer.AddKeepStateDeterminismFences"),
	true,
	TEXT("Whether the Sequencer compiler should auto-add determinism fences for the last frame of KeepState sections. "
		 "This ensures that the last possible value of the section is consistently evaluated regardless of framerate, "
		 "at the cost of an extra evaluation on frames that cross over KeepState sections' end time.\n"),
	ECVF_Default);

#Associated Variable and Callsites

This variable is associated with another variable named CVarAddKeepStateDeterminismFences. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:



TAutoConsoleVariable<bool> CVarAddKeepStateDeterminismFences(
	TEXT("Sequencer.AddKeepStateDeterminismFences"),
	true,
	TEXT("Whether the Sequencer compiler should auto-add determinism fences for the last frame of KeepState sections. "
		 "This ensures that the last possible value of the section is consistently evaluated regardless of framerate, "
		 "at the cost of an extra evaluation on frames that cross over KeepState sections' end time.\n"),
	ECVF_Default);

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

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.
			const TRange<FFrameNumber> SectionRange = Entry.Section->GetRange();