DefaultViewportMouseCaptureMode

DefaultViewportMouseCaptureMode

#Overview

name: DefaultViewportMouseCaptureMode

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 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DefaultViewportMouseCaptureMode is to define the default mouse capture behavior for the game viewport in Unreal Engine 5. It determines how the game viewport handles mouse input and cursor visibility.

This setting variable is primarily used by the Engine module, specifically within the input and viewport systems. It is referenced in the InputSettings and GameViewportClient classes.

The value of this variable is set in multiple places:

1. It is initialized in the UInputSettings constructor with a default value of EMouseCaptureMode::CapturePermanently_IncludingInitialMouseDown.
2. It can be configured through project settings in the Unreal Editor, as indicated by the UPROPERTY(config, EditAnywhere, Category = “ViewportProperties”) decorator in the InputSettings.h file.
3. It can be overridden via command-line arguments using the “DefaultViewportMouseCaptureMode=” parameter.

This variable interacts with the DefaultViewportMouseLockMode variable, which determines the mouse lock behavior when the viewport captures the mouse.

Developers should be aware that:

1. Changing this setting affects the overall mouse behavior in the game viewport.
2. It can impact the player’s ability to interact with the game and the system UI.
3. Different capture modes may be more suitable for different types of games or applications.

Best practices when using this variable include:

1. Choose an appropriate capture mode based on the game’s requirements and genre.
2. Consider the target platform and how different capture modes might affect the user experience.
3. Provide in-game options for players to adjust mouse capture settings if necessary.
4. Test thoroughly with different capture modes to ensure smooth gameplay and UI interactions.
5. Be mindful of how this setting interacts with other input-related configurations in your project.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultInput.ini:27, section: [/Script/Engine.InputSettings]

• INI Section: /Script/Engine.InputSettings
• Raw value: CapturePermanently_IncludingInitialMouseDown
• Is Array: False

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/GameFramework/InputSettings.h:141

Scope (from outer to inner):

file
class        class UInputSettings : public UObject

Source code excerpt:

	/** The default mouse capture mode for the game viewport */
	UPROPERTY(config, EditAnywhere, Category = "ViewportProperties")
	EMouseCaptureMode DefaultViewportMouseCaptureMode;

	/** The default mouse lock state behavior when the viewport acquires capture */
	UPROPERTY(config, EditAnywhere, Category = "ViewportProperties")
	EMouseLockMode DefaultViewportMouseLockMode;

	// The scaling value to multiply the field of view by

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameViewportClient.cpp:489

Scope (from outer to inner):

file
function     void UGameViewportClient::Init

Source code excerpt:

	// Set the projects default viewport mouse capture mode
	MouseCaptureMode = GetDefault<UInputSettings>()->DefaultViewportMouseCaptureMode;
	FString DefaultViewportMouseCaptureMode;
	if (FParse::Value(FCommandLine::Get(), TEXT("DefaultViewportMouseCaptureMode="), DefaultViewportMouseCaptureMode))
	{
		const UEnum* EnumPtr = StaticEnum<EMouseCaptureMode>();
		checkf(EnumPtr, TEXT("Unable to find EMouseCaptureMode enum"));
		if (EnumPtr)
		{
			int64 EnumValue = EnumPtr->GetValueByName(FName(*DefaultViewportMouseCaptureMode));
			if (EnumValue != INDEX_NONE)
			{
				MouseCaptureMode = static_cast<EMouseCaptureMode>(EnumValue);
			}
			else
			{
				UE_LOG(LogInit, Warning, TEXT("Unknown DefaultViewportMouseCaptureMode %s. Command line setting will be ignored."), *DefaultViewportMouseCaptureMode);
			}
		}
	}
	MouseLockMode = GetDefault<UInputSettings>()->DefaultViewportMouseLockMode;

	// Don't capture mouse when headless

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UserInterface/InputSettings.cpp:30

Scope (from outer to inner):

file
function     UInputSettings::UInputSettings

Source code excerpt:

	, bShouldFlushPressedKeysOnViewportFocusLost(true)
	, bEnableDynamicComponentInputBinding(true)
	, DefaultViewportMouseCaptureMode(EMouseCaptureMode::CapturePermanently_IncludingInitialMouseDown)
	, DefaultViewportMouseLockMode(EMouseLockMode::LockOnCapture)
	, DefaultPlayerInputClass(UPlayerInput::StaticClass())
	, DefaultInputComponentClass(UInputComponent::StaticClass())
{
	PlatformSettings.Initialize(UInputPlatformSettings::StaticClass());
}