BackgroundDropDistance

BackgroundDropDistance

#Overview

name: BackgroundDropDistance

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 BackgroundDropDistance is to define the distance from the camera at which actors are placed when dropped into the viewport or positioned in front of the camera in the Unreal Engine editor. This setting is primarily used in the Level Editor’s viewport system.

This setting variable is relied upon by the LevelSequenceEditor plugin and the UnrealEd module, specifically in actor positioning and placement functionalities within the editor viewport.

The value of this variable is set in the ULevelEditorViewportSettings class, which is a configuration class for the Level Editor viewport. It is defined as a UPROPERTY with the ‘config’ specifier, meaning it can be modified and saved in the editor’s configuration files.

BackgroundDropDistance interacts with other variables and functions related to actor placement and camera positioning in the viewport. It’s often used in conjunction with camera direction vectors and snapping utilities.

Developers must be aware that this variable affects the default placement of actors in the viewport when they are created or moved. It’s particularly important for maintaining a consistent and convenient workflow when working with actor placement in the editor.

Best practices when using this variable include:

  1. Adjusting it to a value that makes sense for the scale of your project.
  2. Considering it when implementing custom actor placement tools or overriding default placement behavior.
  3. Being aware of its impact on user experience in the Level Editor, especially for team members who frequently add new actors to scenes.
  4. Documenting any custom values used in your project to maintain consistency across the development team.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/MovieScene/LevelSequenceEditor/Source/LevelSequenceEditor/Private/Misc/LevelSequenceEditorActorSpawner.cpp:177

Scope (from outer to inner):

file
function     static void PlaceActorInFrontOfCamera

Source code excerpt:

			const FVector CameraDirection = CameraRotation.Vector();

			FVector NewLocation = CameraLocation + CameraDirection * (DistanceFromCamera + GetDefault<ULevelEditorViewportSettings>()->BackgroundDropDistance);
			FSnappingUtils::SnapPointToGrid(NewLocation, FVector::ZeroVector);

			CameraRotation.Roll = 0.f;
			CameraRotation.Pitch = 0.f;

			ActorCDO->SetActorRelativeLocation(NewLocation);

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Classes/Settings/LevelEditorViewportSettings.h:545

Scope (from outer to inner):

file
class        class ULevelEditorViewportSettings : public UObject

Source code excerpt:

	/** Distance from the camera to place actors which are dropped on nothing in the view port. */
	UPROPERTY(EditAnywhere, config, Category=LookAndFeel, AdvancedDisplay, meta=(DisplayName = "Background Drop Distance"))
	float BackgroundDropDistance;

	/** A list of meshes that can be used as preview mesh in the editor view port by holding down the backslash key */
	UPROPERTY(EditAnywhere, config, Category=Preview, meta=(AllowedClasses = "/Script/Engine.StaticMesh"))
	TArray<FSoftObjectPath> PreviewMeshes;

	UPROPERTY(EditAnywhere, config, AdvancedDisplay, Category=LookAndFeel, meta=(ClampMin = "0.01", UIMin = "0.01", UIMax = "5"))

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Editor/ActorPositioning.cpp:37

Scope (from outer to inner):

file
function     FActorPositionTraceResult FActorPositioning::TraceWorldForPositionWithDefault

Source code excerpt:


		// And put it in front of the camera
		const float DistanceMultiplier = ( Cursor.GetViewportType() == LVT_Perspective ) ? GetDefault<ULevelEditorViewportSettings>()->BackgroundDropDistance : 0.0f;
		Results.Location = Cursor.GetOrigin() + Cursor.GetDirection() * DistanceMultiplier;
	}
	return Results;
}

FActorPositionTraceResult FActorPositioning::TraceWorldForPosition(const FViewportCursorLocation& Cursor, const FSceneView& View, const TArray<AActor*>* IgnoreActors)

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Editor/ActorPositioning.cpp:262

Scope (from outer to inner):

file
function     FVector FActorPositioning::GetActorPositionInFrontOfCamera

Source code excerpt:


	// The new location the cameras origin offset by the actors bounding cylinder radius down the direction of the cameras view. 
	FVector NewLocation = InCameraOrigin + InCameraDirection * CylRadius + InCameraDirection * GetDefault<ULevelEditorViewportSettings>()->BackgroundDropDistance;

	// Snap the new location if snapping is enabled
	FSnappingUtils::SnapPointToGrid( NewLocation, FVector::ZeroVector );
	return NewLocation;
}