Class InputSettings

Project-wide input settings.

Inheritance

object

Object

ScriptableObject

InputSettings

Inherited Members

ScriptableObject.CreateInstance(string)

ScriptableObject.CreateInstance(Type)

ScriptableObject.CreateInstance<T>()

Object.GetInstanceID()

Object.GetHashCode()

Object.Equals(object)

Object.Instantiate(Object, Vector3, Quaternion)

Object.Instantiate(Object, Vector3, Quaternion, Transform)

Object.Instantiate(Object)

Object.Instantiate(Object, Transform)

Object.Instantiate(Object, Transform, bool)

Object.Instantiate<T>(T)

Object.Instantiate<T>(T, Vector3, Quaternion)

Object.Instantiate<T>(T, Vector3, Quaternion, Transform)

Object.Instantiate<T>(T, Transform)

Object.Instantiate<T>(T, Transform, bool)

Object.Destroy(Object, float)

Object.Destroy(Object)

Object.DestroyImmediate(Object, bool)

Object.DestroyImmediate(Object)

Object.FindObjectsOfType(Type)

Object.DontDestroyOnLoad(Object)

Object.FindObjectsOfType<T>()

Object.FindObjectOfType<T>()

Object.FindObjectOfType(Type)

Object.ToString()

Object.name

Object.hideFlags

Namespace: UnityEngine.InputSystem

Assembly: Unity.InputSystem.dll

Syntax

public class InputSettings : ScriptableObject

Remarks

Several aspects of the input system can be customized to tailor how the system functions to the specific needs of a project. These settings are collected in this class. There is one global settings object active at any one time. It can be accessed and set through settings.

Changing a setting on the object takes effect immediately. It also triggers the onSettingsChange callback.

Properties

backgroundBehavior

When Application.runInBackground is true, this property determines what happens when application focus changes (see Application.isFocused) changes and how we handle input while running the background.

Declaration

public InputSettings.BackgroundBehavior backgroundBehavior { get; set; }

Property Value

Type	Description
InputSettings.BackgroundBehavior	What to do with input while not having focus. Set to ResetAndDisableNonBackgroundDevices by default.

Remarks

If Application.runInBackground is false, the value of this property is ignored. In that case, nothing happens when focus is lost. However, when focus is regained, TrySyncDevice(InputDevice) is called on all devices.

Note that in the editor as well as in development standalone players, Application.runInBackground will effectively always be turned on. The editor keeps the player loop running regardless of Game View focus for as long as the editor is active and in play mode and development players will implicitly turn on the setting during the build process.

See Also

ResetDevice(InputDevice, bool)

EnableDevice(InputDevice)

canRunInBackground

editorInputBehaviorInPlayMode

buttonReleaseThreshold

The percentage of defaultButtonPressPoint at which a button that was pressed is considered released again.

Declaration

public float buttonReleaseThreshold { get; set; }

Property Value

Type	Description
float

Remarks

This setting helps avoid flickering around the button press point by introducing something akin to a "dead zone" below defaultButtonPressPoint. Once a button has been pressed to a magnitude of at least defaultButtonPressPoint, it is considered pressed and keeps being considered pressed until its magnitude falls back to a value of or below buttonReleaseThreshold percent of defaultButtonPressPoint.

This is a percentage rather than a fixed value so it allows computing release points even when the press point has been customized. If, for example, a PressInteraction sets a custom pressPoint, the respective release point can still be computed from the percentage set here.

See Also

settings

onSettingsChange

compensateForScreenOrientation

If true, sensors that deliver rotation values on handheld devices will automatically adjust rotations when the screen orientation changes.

Declaration

public bool compensateForScreenOrientation { get; set; }

Property Value

Type	Description
bool

Remarks

This is enabled by default.

If enabled, rotation values will be rotated around Z. In Portrait, values remain unchanged. In PortraitUpsideDown, they will be rotated by 180 degrees. In LandscapeLeft by 90 degrees, and in LandscapeRight by 270 degrees.

Sensors affected by this setting are Accelerometer, Compass, and Gyroscope.

See Also

CompensateDirectionProcessor

defaultButtonPressPoint

The default value threshold for when a button is considered pressed. Used if no explicit thresholds are set on parameters such as pressPoint or pressPoint.

Declaration

public float defaultButtonPressPoint { get; set; }

Property Value

Type	Description
float	Default button press threshold.

Remarks

In the input system, each button constitutes a full floating-point value. Pure toggle buttons, such as buttonSouth for example, will simply alternate between 0 (not pressed) and 1 (pressed). However, buttons may also have ranges, such as leftTrigger for example. When used in a context where a clear distinction between pressed and not pressed is required, we need a value beyond which we consider the button pressed.

By setting this property, the default value for this can be configured. If a button has a value equal to or greater than the button press point, it is considered pressed.

The default value is 0.5.

Any value will implicitly be clamped to 0.0001f as allowing a value of 0 would cause all buttons in their default state to already be pressed.

Lowering the button press point will make triggers feel more like hair-triggers (akin to using the hair-trigger feature on Xbox Elite controllers). However, it may make using the directional buttons (i.e. up etc) be fickle as solely moving in only one direction with sticks isn't easy. To counteract that, the button press points on the stick buttons can be raised.

Another solution is to simply lower the press points on the triggers specifically.

InputSystem.RegisterLayoutOverride(@"
    {
        ""name"" : ""HairTriggers"",
        ""extend"" : ""Gamepad"",
        ""controls"" [
            { ""name"" : ""leftTrigger"", ""parameters"" : ""pressPoint=0.1"" },
            { ""name"" : ""rightTrigger"", ""parameters"" : ""pressPoint=0.1"" }
        ]
    }
");

See Also

buttonReleaseThreshold

pressPoint

isPressed

pressPoint

pressPoint

pressPoint

ReadValueAsButton(int)

defaultDeadzoneMax

Default value used when nothing is set explicitly on max or max.

Declaration

public float defaultDeadzoneMax { get; set; }

Property Value

Type	Description
float	Default upper limit for deadzones.

Remarks

"Deadzones" refer to limits established for the range of values accepted as input on a control. If the value for the control falls outside the range, i.e. below the given minimum or above the given maximum, the value is clamped to the respective limit.

This property configures the default upper bound of the value range.

Note that deadzones will by default re-normalize values after clamping. This means that inputs at the lower and upper end are dropped and that the range in-between is re-normalized to [0..1].

Note that deadzones preserve the sign of inputs. This means that both the upper and the lower deadzone bound extend to both the positive and the negative range. For example, a deadzone max of 0.95 will clamp values of >0.95 and <-0.95.

The most common example of where deadzones are used are the sticks on gamepads, i.e. leftStick and rightStick. Sticks will usually be wobbly to some extent (just how wobbly varies greatly between different types of controllers -- which means that often deadzones need to be configured on a per-device type basis). Using deadzones, stick motion at the extreme ends of the spectrum can be filtered out and noise in these areas can effectively be eliminated this way.

The default value for this property is 0.925.

See Also

StickDeadzoneProcessor

AxisDeadzoneProcessor

defaultDeadzoneMin

Default value used when nothing is set explicitly on min or min.

Declaration

public float defaultDeadzoneMin { get; set; }

Property Value

Type	Description
float	Default lower limit for deadzones.

Remarks

"Deadzones" refer to limits established for the range of values accepted as input on a control. If the value for the control falls outside the range, i.e. below the given minimum or above the given maximum, the value is clamped to the respective limit.

This property configures the default lower bound of the value range.

Note that deadzones will by default re-normalize values after clamping. This means that inputs at the lower and upper end are dropped and that the range in-between is re-normalized to [0..1].

Note that deadzones preserve the sign of inputs. This means that both the upper and the lower deadzone bound extend to both the positive and the negative range. For example, a deadzone min of 0.1 will clamp values between -0.1 and +0.1.

The most common example of where deadzones are used are the sticks on gamepads, i.e. leftStick and rightStick. Sticks will usually be wobbly to some extent (just how wobbly varies greatly between different types of controllers -- which means that often deadzones need to be configured on a per-device type basis). Using deadzones, stick motion at the extreme ends of the spectrum can be filtered out and noise in these areas can effectively be eliminated this way.

The default value for this property is 0.125.

See Also

StickDeadzoneProcessor

AxisDeadzoneProcessor

defaultHoldTime

Allows you to specify the default minimum duration required of a press-and-release interaction to evaluate to a hold-interaction.

Declaration

public float defaultHoldTime { get; set; }

Property Value

Type	Description
float	The default minimum duration that the button-like input control must remain in pressed state for the interaction to evaluate to a hold-interaction.

Remarks

A hold-interaction is considered as a press-and-release sequence on a button-like input control. This property determines the lower bound of the duration that must elapse between the button being pressed and released again. If the delay between press and release is less than this duration, the input does not qualify as a hold-interaction.

The default hold time is 0.4 seconds.

See Also

HoldInteraction

defaultSlowTapTime

Allows you to specify the default minimum duration required of a press-and-release interaction to evaluate to a slow-tap-interaction.

Declaration

public float defaultSlowTapTime { get; set; }

Property Value

Type	Description
float	The default minimum duration that the button-like input control must remain in pressed state for the interaction to evaluate to a slow-tap-interaction.

Remarks

A slow-tap-interaction is considered as a press-and-release sequence on a button-like input control. This property determines the lower bound of the duration that must elapse between the button being pressed and released again. If the delay between press and release is less than this duration, the input does not qualify as a slow-tap-interaction.

The default slow-tap time is 0.5 seconds.

See Also

SlowTapInteraction

defaultTapTime

Default time (in seconds) within which a press and release has to occur for it to be registered as a "tap".

Declaration

public float defaultTapTime { get; set; }

Property Value

Type	Description
float	Default upper limit on press durations for them to register as taps.

Remarks

A tap is considered as a quick press-and-release on a button-like input control. This property determines just how quick the press-and-release has to be, i.e. what the maximum time is that can elapse between the button being pressed and released again. If the delay between press and release is greater than this time, the input does not qualify as a tap.

The default tap time is 0.2 seconds.

See Also

TapInteraction

disableRedundantEventsMerging

Disables merging of redundant input events (at the moment, only mouse events). Disable it if you want to get all events.

Declaration

public bool disableRedundantEventsMerging { get; set; }

Property Value

Type	Description
bool

Remarks

When using a high frequency mouse, the number of mouse move events in each frame can be very large, which can have a negative effect on performance. To help with this, merging events can be used which coalesces consecutive mouse move events into a single input action update.

For example, if there are one hundred mouse events, but they are all position updates with no clicks, and there is an input action callback handler for the mouse position, that callback handler will only be called one time in the current frame. Delta and scroll values for the mouse will still be accumulated across all mouse events.

See Also

settings

onSettingsChange

editorInputBehaviorInPlayMode

Determines how player focus is handled in the editor with respect to input.

Declaration

public InputSettings.EditorInputBehaviorInPlayMode editorInputBehaviorInPlayMode { get; set; }

Property Value

Type	Description
InputSettings.EditorInputBehaviorInPlayMode

Remarks

This setting only has an effect while in play mode (see Application.isPlaying). While not in play mode, all input is invariably routed to the editor.

The editor generally treats Game View focus as equivalent to application focus (see Application.isFocused). In other words, as long as any Game View has focus, the player is considered to have input focus. As soon as focus is transferred to a non-Game View EditorWindow or the editor as a whole loses focus, the player is considered to have lost input focus.

However, unlike in built players, the editor will keep running the player loop while in play mode regardless of whether a Game View is focused or not. This essentially equates to Application.runInBackground always being true in the editor.

To accommodate this behavior, this setting determines where input is routed while the player loop is running with no Game View being focused. As such, it also dictates which input reaches the editor (if any) while the game is playing.

See Also

backgroundBehavior

iOS

iOS/tvOS-specific settings.

Declaration

public InputSettings.iOSSettings iOS { get; }

Property Value

Type	Description
InputSettings.iOSSettings

Remarks

This is only accessible in the editor or in iOS/tvOS players.

See Also

settings

onSettingsChange

inputActionPropertyDrawerMode

Determines how the Inspector window displays InputActionProperty fields.

Declaration

public InputSettings.InputActionPropertyDrawerMode inputActionPropertyDrawerMode { get; set; }

Property Value

Type	Description
InputSettings.InputActionPropertyDrawerMode

See Also

InputSettings.InputActionPropertyDrawerMode

maxEventBytesPerUpdate

Upper limit on the amount of bytes worth of InputEvents processed in a single Update().

Declaration

public int maxEventBytesPerUpdate { get; set; }

Property Value

Type	Description
int

Remarks

This setting establishes a bound on the amount of input event data processed in a single update and thus limits throughput allowed for input. This prevents long stalls from leading to long delays in input processing.

When the limit is exceeded, all events remaining in the buffer are thrown away (the InputEventBuffer is reset) and an error is logged. After that, the current update will abort and early out.

Setting this property to 0 or a negative value will disable the limit.

The default value is 5MB.

See Also

Update()

maxQueuedEventsPerUpdate

Upper limit on the number of InputEvents that can be queued within one Update(). This settings establishes an upper limit on the number of events that can be queued using QueueEvent(InputEventPtr) during a single update. This prevents infinite loops where an action callback queues an event that causes the action callback to be called again which queues an event...

Note that this limit only applies while the input system is updating. There is no limit on the number of events that can be queued outside of this time, but those will be queued into the next frame where the maxEventBytesPerUpdate setting will apply.

The default value is 1000.

Declaration

public int maxQueuedEventsPerUpdate { get; set; }

Property Value

Type	Description
int

See Also

settings

onSettingsChange

multiTapDelayTime

Allows you to specify the maximum duration that may pass between taps in order to evaluate to a multi-tap-interaction.

Declaration

public float multiTapDelayTime { get; set; }

Property Value

Type	Description
float	The default maximum duration (in seconds) that may pass between taps in order to evaluate to a multi-tap-interaction.

Remarks

A multi-tap interaction is considered as multiple press-and-release sequences. This property defines the maximum duration that may pass between these press-and-release sequences. If consecutive taps (press-and-release sequences) occur with a inter-sequence duration exceeding this property, the interaction do not qualify as a multi-tap-interaction.

The default multi-tap delay time is 0.75 seconds.

See Also

defaultTapTime

scrollDeltaBehavior

Controls how platform-specific input should be converted when returning delta values for scroll wheel input actions.

Declaration

public InputSettings.ScrollDeltaBehavior scrollDeltaBehavior { get; set; }

Property Value

Type	Description
InputSettings.ScrollDeltaBehavior	The conversion behavior.

Remarks

By default, the range used for the delta is normalized to a range of -1 to 1, to be uniform across all platforms. The alternative is that the native platform's scroll wheel range is returned, which is -120 to 120 for windows, and -1 to 1 for most other platforms. You should leave this value as the default uniform range unless you need to support legacy code that relies on the native platform-specific values.

See Also

settings

onSettingsChange

shortcutKeysConsumeInput

Improves shortcut key support by making composite controls consume control input

Declaration

public bool shortcutKeysConsumeInput { get; set; }

Property Value

Type	Description
bool

Remarks

Actions are exclusively triggered and will consume/block other actions sharing the same input. E.g. when pressing the 'Shift+B' keys, the associated action would trigger but any action bound to just the 'B' key would be prevented from triggering at the same time. Please note that enabling this will cause actions with composite bindings to consume input and block any other actions which are enabled and sharing the same controls. Input consumption is performed in priority order, with the action containing the greatest number of bindings checked first. Therefore actions requiring fewer keypresses will not be triggered if an action using more keypresses is triggered and has overlapping controls. This works for shortcut keys, however in other cases this might not give the desired result, especially where there are actions with the exact same number of composite controls, in which case it is non-deterministic which action will be triggered. These conflicts may occur even between actions which belong to different Action Maps e.g. if using an UIInputModule with the Arrow Keys bound to the Navigate Action in the UI Action Map, this would interfere with other Action Maps using those keys. However conflicts would not occur between actions which belong to different Action Assets.

See Also

settings

onSettingsChange

supportedDevices

List of device layouts used by the project.

Declaration

public ReadOnlyArray<string> supportedDevices { get; set; }

Property Value

Type	Description
ReadOnlyArray<string>

Remarks

This would usually be one of the high-level abstract device layouts. For example, for a game that supports touch, gamepad, and keyboard&mouse, the list would be { "Touchscreen", "Gamepad", "Mouse", "Keyboard" }. However, nothing prevents the the user from adding something a lot more specific. A game that can only be played with a DualShock controller could make this list just be { "DualShockGamepad" }, for example.

In the editor, we use the information to filter what we display to the user by automatically filtering out irrelevant controls in the control picker and such.

The information is also used when a new device is discovered. If the device is not listed as supported by the project, it is ignored.

The list is empty by default. An empty list indicates that no restrictions are placed on what devices are supported. In this editor, this means that all possible devices and controls are shown.

See Also

InputControlLayout

tapRadius

Allows you to specify the default maximum radius that a touch contact may be moved from its origin to evaluate to a tap-interaction.

Declaration

public float tapRadius { get; set; }

Property Value

Type	Description
float	The default maximum radius (in pixels) that a touch contact may be moved from its origin to evaluate to a tap-interaction.

Remarks

A tap-interaction or slow-tap-interaction is considered as a press-and-release sequence. If the associated touch contact is moved a distance equal or greater to the value of this setting, the input sequence do not qualify as a tap-interaction.

The default tap-radius is 5 pixels.

See Also

TapInteraction

SlowTapInteraction

MultiTapInteraction

updateMode

Allows you to control how the input system handles updates. In other words, how and when pending input events are processed.

Declaration

public InputSettings.UpdateMode updateMode { get; set; }

Property Value

Type	Description
InputSettings.UpdateMode	When to run input updates.

Remarks

By default, input updates will automatically be triggered as part of the player loop. If updateMode is set to ProcessEventsInDynamicUpdate (the default), then right at the beginning of a dynamic update (i.e. before all MonoBehaviour.Update methods are called), input is processed. And if updateMode is set to ProcessEventsInFixedUpdate, then right at the beginning of each fixed update (i.e. before all MonoBehaviour.FixedUpdate methods are called), input is processed.

Additionally, if there are devices that need updates right before rendering (see updateBeforeRender), an extra update will be run right before rendering. This special update will only consume input on devices that have updateBeforeRender set to true.

You can run updates manually using Update(). Doing so outside of tests is only recommended, however, if updateMode is set to ProcessEventsManually (in which case it is actually required for input to be processed at all).

Note that in the editor, input updates will also run before each editor update (i.e. as part of EditorApplication.update). Player and editor input state are kept separate, though, so any input consumed in editor updates will not be visible in player updates and vice versa.

See Also

Update()

Methods

SetInternalFeatureFlag(string, bool)

Enable or disable an internal feature by its name.

Declaration

public void SetInternalFeatureFlag(string featureName, bool enabled)

Parameters

Type	Name	Description
string	featureName	Name of the feature.
bool	enabled	Whether to enable or disable the feature.

Remarks

This method is intended for experimental features. These must be enabled/disabled from code. Setting or unsetting a feature flag will not be persisted in an .inputsettings file.

Exceptions

Type	Condition
ArgumentNullException	featureName is null or empty.

See Also

settings

onSettingsChange

See Also

settings

onSettingsChange