MapSkeletalMotionToRoot

MapSkeletalMotionToRoot

#Overview

name: MapSkeletalMotionToRoot

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of MapSkeletalMotionToRoot is to control how skeletal motion is exported in FBX files. Specifically, it determines whether the motion of a skeletal actor should be mapped to the root bone of the skeleton during the export process.

This setting variable is primarily used in the Unreal Engine’s FBX export system, which is part of the UnrealEd module. It’s particularly relevant for the animation export functionality within this system.

The value of this variable is set in the UFbxExportOption class constructor (FbxExportOption.cpp), where it’s initialized to false by default. It can be modified through the Unreal Editor’s export options interface, as it’s declared as an UPROPERTY with EditAnywhere and BlueprintReadWrite specifiers.

MapSkeletalMotionToRoot interacts with other animation and skeletal mesh-related variables in the export process. For example, it’s used in conjunction with SkeletalMeshComponent and bone transform calculations during animation track export.

Developers must be aware that when this variable is set to true, it will change how skeletal motion is exported. Instead of exporting the motion for each bone individually, the entire skeletal motion will be mapped to the root bone. This can be useful in certain scenarios, such as when you want to preserve the overall motion of the character but simplify the skeleton hierarchy in the exported file.

Best practices when using this variable include:

  1. Use it judiciously, as mapping all motion to the root bone can result in loss of detail in the exported animation.
  2. Consider the target application or workflow when deciding whether to enable this option. Some pipelines might prefer root motion, while others might need per-bone animation data.
  3. Test the exported FBX files with this option both enabled and disabled to ensure the desired result is achieved.
  4. Document the use of this option in your team’s export guidelines to ensure consistency across different exports.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEditorPerProjectUserSettings.ini:76, section: [/Script/UnrealEd.FbxExportOption]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Classes/Exporters/FbxExportOption.h:84

Scope (from outer to inner):

file
class        class UFbxExportOption : public UObject

Source code excerpt:

	/** If enable, Map skeletal actor motion to the root bone of the skeleton. */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, config, category = Animation)
	uint32 MapSkeletalMotionToRoot : 1;

	/** If enabled, export sequencer animation in its local time, relative to its sequence. */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, config, category = Animation)
	uint32 bExportLocalTime : 1;

	/** Bake settings for camera and light animation curves. Camera Scale not exported. */

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxAnimationExport.cpp:688

Scope (from outer to inner):

file
namespace    UnFbx
function     void FFbxExporter::ExportAnimTrack

Source code excerpt:

			FTransform BoneTransform = LocalBoneTransforms[BoneIndex];

			if (GetExportOptions()->MapSkeletalMotionToRoot && BoneIndex == 0)
			{
				BoneTransform = InSkeletalMeshComponent->GetSocketTransform(BoneName) * InitialInvParentTransform;
			}

			FbxVector4 Translation = Converter.ConvertToFbxPos(BoneTransform.GetLocation());
			FbxVector4 Rotation = Converter.ConvertToFbxRot(BoneTransform.GetRotation().Euler());

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxExportOption.cpp:26

Scope (from outer to inner):

file
function     UFbxExportOption::UFbxExportOption

Source code excerpt:

	bExportMorphTargets = true;
	VertexColor = true;
	MapSkeletalMotionToRoot = false;
	bExportLocalTime = true;
	BakeCameraAndLightAnimation = EMovieSceneBakeType::BakeTransforms;
	BakeActorAnimation = EMovieSceneBakeType::None;
}

void UFbxExportOption::ResetToDefault()

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxMainExport.cpp:1810

Scope (from outer to inner):

file
namespace    UnFbx
function     bool FFbxExporter::ExportLevelSequenceTracks

Source code excerpt:

	FFrameRate DisplayRate = MovieScene->GetDisplayRate();

	bool bSkip3DTransformTrack = SkeletalMeshComp && GetExportOptions()->MapSkeletalMotionToRoot;

	// Get all the transform tracks that affect this binding
	TArray<TWeakObjectPtr<UMovieScene3DTransformTrack> > TransformTracks;
	if (BoundObject)
	{
		for ( const FMovieSceneBinding& MovieSceneBinding : MovieScene->GetBindings() )