Initial commit
This commit is contained in:
lethanhsonvsp
@@ -0,0 +1,5 @@
|
||||
inputactions
|
||||
playerinput
|
||||
inputsystemuiinputmodule
|
||||
gravitysensor
|
||||
deadzone
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
uid: input-system-action-assets
|
||||
---
|
||||
# Input Action Assets
|
||||
|
||||
- [Creating Input Action Assets](#creating-input-action-assets)
|
||||
- [Editing Input Action Assets](#editing-input-action-assets)
|
||||
- [Using Input Action Assets](#using-input-action-assets)
|
||||
- [Type-safe C# API Generation](#type-safe-c-api-generation)
|
||||
|
||||
An Input Action Asset is an Asset which contains a set of [Input Actions](Actions.md) definitions and their associated [Bindings](ActionBindings.md) and [Control Schemes](ActionBindings.md#control-schemes). These Assets have the `.inputactions` file extension and are stored in a plain JSON format.
|
||||
|
||||
The input system creates an Action Asset when you set up the [default project-wide actions](ProjectWideActions.md), but you can also create new Action Assets directly in the Project window.
|
||||
|
||||
For most common scenarios, you do not need to use more than one Input Action Asset. It is usually simpler to configure your project-wide action definition in the Project Settings window.
|
||||
|
||||
|
||||
## Creating Input Action Assets
|
||||
|
||||
To create an Asset that contains [Input Actions](Actions.md) in Unity, right-click in the __Project__ window or go to __Assets > Create > Input Actions__ from Unity's main menu.
|
||||
|
||||
## Editing Input Action Assets
|
||||
|
||||
To bring up the Action editor, double-click an `.inputactions` Asset in the Project Browser, or select the __Edit Asset__ button in the Inspector for that Asset. You can have more than one editor window open at the same time, but not for the same Asset.
|
||||
|
||||
The Actions Editor which opens is identical to the [Actions Editor in the Project Settings window](ActionsEditor.md).
|
||||
|
||||
|
||||
## Using Input Action Assets
|
||||
|
||||
|
||||
## Type-safe C# API Generation
|
||||
|
||||
Input Action Assets allow you to **generate a C# class** from your action definitions, which allow you to refer to your actions in a type-safe manner from code. This means you can avoid looking up your actions by string.
|
||||
|
||||
### Auto-generating script code for Actions
|
||||
|
||||
One of the most convenient ways to work with `.inputactions` Assets in scripts is to automatically generate a C# wrapper class for them. This removes the need to manually look up Actions and Action Maps using their names, and also provides an easier way to set up callbacks.
|
||||
|
||||
To enable this option, tick the __Generate C# Class__ checkbox in the importer properties in the Inspector of the `.inputactions` Asset, then select __Apply__.
|
||||
|
||||
|
||||
|
||||
You can optionally choose a path name, class name, and namespace for the generated script, or keep the default values.
|
||||
|
||||
This generates a C# script that simplifies working with the Asset.
|
||||
|
||||
```CSharp
|
||||
using UnityEngine;
|
||||
using UnityEngine.InputSystem;
|
||||
|
||||
// IGameplayActions is an interface generated from the "gameplay" action map
|
||||
// we added (note that if you called the action map differently, the name of
|
||||
// the interface will be different). This was triggered by the "Generate Interfaces"
|
||||
// checkbox.
|
||||
public class MyPlayerScript : MonoBehaviour, IGameplayActions
|
||||
{
|
||||
// MyPlayerControls is the C# class that Unity generated.
|
||||
// It encapsulates the data from the .inputactions asset we created
|
||||
// and automatically looks up all the maps and actions for us.
|
||||
MyPlayerControls controls;
|
||||
|
||||
public void OnEnable()
|
||||
{
|
||||
if (controls == null)
|
||||
{
|
||||
controls = new MyPlayerControls();
|
||||
// Tell the "gameplay" action map that we want to get told about
|
||||
// when actions get triggered.
|
||||
controls.gameplay.SetCallbacks(this);
|
||||
}
|
||||
controls.gameplay.Enable();
|
||||
}
|
||||
|
||||
public void OnDisable()
|
||||
{
|
||||
controls.gameplay.Disable();
|
||||
}
|
||||
|
||||
public void OnUse(InputAction.CallbackContext context)
|
||||
{
|
||||
// 'Use' code here.
|
||||
}
|
||||
|
||||
public void OnMove(InputAction.CallbackContext context)
|
||||
{
|
||||
// 'Move' code here.
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
>__Note__: To regenerate the .cs file, right-click the .inputactions asset in the Project Browser and choose "Reimport".
|
||||
|
||||
### Using Action Assets with `PlayerInput`
|
||||
|
||||
The [Player Input](PlayerInput.md) component provides a convenient way to handle input for one or multiple players. You can assign your Action Asset to the Player Input component so that it can then automatically handle activating Action Maps and selecting Control Schemes for you.
|
||||
|
||||
|
||||
|
||||
### Modifying Input Action Assets at runtime
|
||||
There are several ways to modify an Input Action Asset at runtime. Any modifications that you make during Play mode to an Input Action Asset do not persist in the Input Action Asset after you exit Play mode. This means you can test your application in a realistic manner in the Editor without having to worry about inadvertently modifying the asset. For examples on how to modify an Input Action Asset, see the documentation on [Creating Actions in code](Actions.md#creating-actions-in-code) and [Changing Bindings](ActionBindings.md#changing-bindings).
|
||||
|
||||
|
||||
### The Default Actions Asset
|
||||
|
||||
An asset called `DefaultInputActions.inputactions` containing a default setup of Actions comes with the Input System Package. You can reference this asset directly in your projects like any other Unity asset. However, the asset is also available in code form through the [`DefaultInputActions`](../api/UnityEngine.InputSystem.DefaultInputActions.html) class.
|
||||
|
||||
```CSharp
|
||||
void Start()
|
||||
{
|
||||
// Create an instance of the default actions.
|
||||
var actions = new DefaultInputActions();
|
||||
actions.Player.Look.performed += OnLook;
|
||||
actions.Player.Move.performed += OnMove;
|
||||
actions.Enable();
|
||||
}
|
||||
```
|
||||
|
||||
> __Note:__ This default actions asset is older than, and entirely separate from the [default project-wide actions](ProjectWideActions.md). It is a legacy asset that remains included in the package for backward compatibility.
|
||||
@@ -0,0 +1,953 @@
|
||||
---
|
||||
uid: input-system-action-bindings
|
||||
---
|
||||
# Input Bindings
|
||||
|
||||
* [Composite Bindings](#composite-bindings)
|
||||
* [1D Axis](#1d-axis)
|
||||
* [2D Vector](#2d-vector)
|
||||
* [3D Vector](#3d-vector)
|
||||
* [One Modifier](#one-modifier)
|
||||
* [Two Modifiers](#two-modifiers)
|
||||
* [Writing custom Composites](#writing-custom-composites)
|
||||
* [Working with Bindings](#working-with-bindings)
|
||||
* [Looking up Bindings](#looking-up-bindings)
|
||||
* [Changing Bindings](#changing-bindings)
|
||||
* [Applying overrides](#applying-overrides)
|
||||
* [Erasing Bindings](#erasing-bindings)
|
||||
* [Adding Bindings](#adding-bindings)
|
||||
* [Setting parameters](#setting-parameters)
|
||||
* [Interactive rebinding](#interactive-rebinding)
|
||||
* [Saving and loading rebinds](#saving-and-loading-rebinds)
|
||||
* [Restoring original Bindings](#restoring-original-bindings)
|
||||
* [Displaying Bindings](#displaying-bindings)
|
||||
* [Control schemes](#control-schemes)
|
||||
* [Details](#details)
|
||||
* [Binding resolution](#binding-resolution)
|
||||
* [Binding resolution while Actions are enabled](#binding-resolution-while-actions-are-enabled)
|
||||
* [Choosing which Devices to use](#choosing-which-devices-to-use)
|
||||
* [Conflicting inputs](#conflicting-inputs)
|
||||
* [Initial state check](#initial-state-check)
|
||||
|
||||
An [`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html) represents a connection between an [Action](Actions.md) and one or more [Controls](Controls.md) identified by a [Control path](Controls.md#control-paths). For example, the **right trigger** of a gamepad (a control) might be bound to an an action named "accelerate", so that pulling the right trigger causes a car to accelerate in your game.
|
||||
|
||||
You can add multiple bindings to an action, which is generally useful for supporting multiple types of input device. For example, in the default set of actions, the "Move" action has a binding to the left gamepad stick and the WSAD keys, which means input through any of these bindings will perform the action.
|
||||
|
||||
You can also bind multiple controls from the same device to an action. For example, both the left and right trigger of a gamepad could be mapped to the same action, so that pulling either trigger has the same result in your game.
|
||||
|
||||
<br/>
|
||||
_The default "Move" action in the Actions Editor window, displaying the multiple bindings associated with it._
|
||||
|
||||
|
||||
Each Binding has the following properties:
|
||||
|
||||
|Property|Description|
|
||||
|--------|-----------|
|
||||
|[`path`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_path)|[Control path](Controls.md#control-paths) that identifies the control(s) from which the Action should receive input.<br><br>Example: `"<Gamepad>/leftStick"`|
|
||||
|[`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath)|[Control path](Controls.md#control-paths) that overrides `path`. Unlike `path`, `overridePath` is not persistent, so you can use it to non-destructively override the path on a Binding. If it is set to something other than null, it takes effect and overrides `path`. To get the path which is currently in effect (that is, either `path` or `overridePath`), you can query the [`effectivePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_effectivePath) property.|
|
||||
|[`action`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_action)|The name or ID of the Action that the Binding should trigger. Note that this can be null or empty (for instance, for [composites](#composite-bindings)). Not case-sensitive.<br><br>Example: `"fire"`|
|
||||
|[`groups`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_groups)|A semicolon-separated list of Binding groups that the Binding belongs to. Can be null or empty. Binding groups can be anything, but are mostly used for [Control Schemes](#control-schemes). Not case-sensitive.<br><br>Example: `"Keyboard&Mouse;Gamepad"`|
|
||||
|[`interactions`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_interactions)|A semicolon-separated list of [Interactions](Interactions.md) to apply to input on this Binding. Note that Unity appends Interactions applied to the [Action](Actions.md) itself (if any) to this list. Not case-sensitive.<br><br>Example: `"slowTap;hold(duration=0.75)"`|
|
||||
|[`processors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_processors)|A semicolon-separated list of [Processors](Processors.md) to apply to input on this Binding. Note that Unity appends Processors applied to the [Action](Actions.md) itself (if any) to this list. Not case-sensitive.<br><br>Processors on Bindings apply in addition to Processors on Controls that are providing values. For example, if you put a `stickDeadzone` Processor on a Binding and then bind it to `<Gamepad>/leftStick`, you get deadzones applied twice: once from the deadzone Processor sitting on the `leftStick` Control, and once from the Binding.<br><br>Example: `"invert;axisDeadzone(min=0.1,max=0.95)"`|
|
||||
|[`id`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_id)|Unique ID of the Binding. You can use it to identify the Binding when storing Binding overrides in user settings, for example.|
|
||||
|[`name`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_name)|Optional name of the Binding. Identifies part names inside [Composites](#composite-bindings).<br><br>Example: `"Positive"`|
|
||||
|[`isComposite`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_isComposite)|Whether the Binding acts as a [Composite](#composite-bindings).|
|
||||
|[`isPartOfComposite`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_isPartOfComposite)|Whether the Binding is part of a [Composite](#composite-bindings).|
|
||||
|
||||
To query the Bindings to a particular Action, you can use [`InputAction.bindings`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_bindings). To query a flat list of Bindings for all Actions in an Action Map, you can use [`InputActionMap.bindings`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_bindings).
|
||||
|
||||
## Composite Bindings
|
||||
|
||||
Sometimes, you might want to have several Controls act in unison to mimic a different type of Control. The most common example of this is using the W, A, S, and D keys on the keyboard to form a 2D vector Control equivalent to mouse deltas or gamepad sticks. Another example is to use two keys to form a 1D axis equivalent to a mouse scroll axis.
|
||||
|
||||
This is difficult to implement with normal Bindings. You can bind a [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) to an action expecting a `Vector2`, but doing so results in an exception at runtime when the Input System tries to read a `Vector2` from a Control that can deliver only a `float`.
|
||||
|
||||
Composite Bindings (that is, Bindings that are made up of other Bindings) solve this problem. Composites themselves don't bind directly to Controls; instead, they source values from other Bindings that do, and then synthesize input on the fly from those values.
|
||||
|
||||
To see how to create Composites in the editor UI, see documentation on [editing Composite Bindings](ActionsEditor.md#editing-composite-bindings).
|
||||
|
||||
To create composites in code, you can use the [`AddCompositeBinding`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.html#UnityEngine_InputSystem_InputActionSetupExtensions_AddCompositeBinding_UnityEngine_InputSystem_InputAction_System_String_System_String_System_String_) syntax.
|
||||
|
||||
```CSharp
|
||||
myAction.AddCompositeBinding("Axis")
|
||||
.With("Positive", "<Gamepad>/rightTrigger")
|
||||
.With("Negative", "<Gamepad>/leftTrigger");
|
||||
```
|
||||
|
||||
Each Composite consists of one Binding that has [`InputBinding.isComposite`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_isComposite) set to true, followed by one or more Bindings that have [`InputBinding.isPartOfComposiste`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_isPartOfComposite) set to true. In other words, several consecutive entries in [`InputActionMap.bindings`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_bindings) or [`InputAction.bindings`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_bindings) together form a Composite.
|
||||
|
||||
Note that each composite part can be bound arbitrary many times.
|
||||
|
||||
```CSharp
|
||||
// Make both shoulders and triggers pull on the axis.
|
||||
myAction.AddCompositeBinding("Axis")
|
||||
.With("Positive", "<Gamepad>/rightTrigger")
|
||||
.With("Positive", "<Gamepad>/rightShoulder")
|
||||
.With("Negative", "<Gamepad>/leftTrigger");
|
||||
.With("Negative", "<Gamepad>/leftShoulder");
|
||||
```
|
||||
|
||||
Composites can have parameters, just like [Interactions](Interactions.md) and [Processors](Processors.md).
|
||||
|
||||
```CSharp
|
||||
myAction.AddCompositeBinding("Axis(whichSideWins=1)");
|
||||
```
|
||||
|
||||
There are currently five Composite types that come with the system out of the box: [1D-Axis](#1d-axis), [2D-Vector](#2d-vector), [3D-Vector](#3d-vector), [One Modifier](#one-modifier) and [Two Modifiers](#two-modifiers). Additionally, you can [add your own](#writing-custom-composites) types of Composites.
|
||||
|
||||
### 1D axis
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A Composite made of two buttons: one that pulls a 1D axis in its negative direction, and another that pulls it in its positive direction. Implemented in the [`AxisComposite`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html) class. The result is a `float`.
|
||||
|
||||
```CSharp
|
||||
myAction.AddCompositeBinding("1DAxis") // Or just "Axis"
|
||||
.With("Positive", "<Gamepad>/rightTrigger")
|
||||
.With("Negative", "<Gamepad>/leftTrigger");
|
||||
```
|
||||
|
||||
The axis Composite has two part bindings.
|
||||
|
||||
|Part|Type|Description|
|
||||
|----|----|-----------|
|
||||
|[`positive`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_positive)|`Button`|Controls pulling in the positive direction (towards [`maxValue`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_maxValue)).|
|
||||
|[`negative`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_negative)|`Button`|Controls pulling in the negative direction, (towards [`minValue`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_minValue)).|
|
||||
|
||||
You can set the following parameters on an axis Composite:
|
||||
|
||||
|Parameter|Description|
|
||||
|---------|-----------|
|
||||
|[`whichSideWins`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_whichSideWins)|What happens if both [`positive`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_positive) and [`negative`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_negative) are actuated. See table below.|
|
||||
|[`minValue`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_minValue)|The value returned if the [`negative`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_negative) side is actuated. Default is -1.|
|
||||
|[`maxValue`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_maxValue)|The value returned if the [`positive`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_positive) side is actuated. Default is 1.|
|
||||
|
||||
If Controls from both the `positive` and the `negative` side are actuated, then the resulting value of the axis Composite depends on the `whichSideWin` parameter setting.
|
||||
|
||||
|[`WhichSideWins`](../api/UnityEngine.InputSystem.Composites.AxisComposite.WhichSideWins.html)|Description|
|
||||
|---------------|-----------|
|
||||
|(0) `Neither`|Neither side has precedence. The Composite returns the midpoint between `minValue` and `maxValue` as a result. At their default settings, this is 0.<br><br>This is the default value for this setting.|
|
||||
|(1) `Positive`|The positive side has precedence and the Composite returns `maxValue`.|
|
||||
|(2) `Negative`|The negative side has precedence and the Composite returns `minValue`.|
|
||||
|
||||
>__Note__: There is no support yet for interpolating between the positive and negative over time.
|
||||
|
||||
### 2D vector
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A Composite that represents a 4-way button setup like the D-pad on gamepads. Each button represents a cardinal direction. Implemented in the [`Vector2Composite`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html) class. The result is a `Vector2`.
|
||||
|
||||
This Composite is most useful for representing up-down-left-right controls, such as WASD keyboard input.
|
||||
|
||||
```CSharp
|
||||
myAction.AddCompositeBinding("2DVector") // Or "Dpad"
|
||||
.With("Up", "<Keyboard>/w")
|
||||
.With("Down", "<Keyboard>/s")
|
||||
.With("Left", "<Keyboard>/a")
|
||||
.With("Right", "<Keyboard>/d");
|
||||
|
||||
// To set mode (2=analog, 1=digital, 0=digitalNormalized):
|
||||
myAction.AddCompositeBinding("2DVector(mode=2)")
|
||||
.With("Up", "<Gamepad>/leftStick/up")
|
||||
.With("Down", "<Gamepad>/leftStick/down")
|
||||
.With("Left", "<Gamepad>/leftStick/left")
|
||||
.With("Right", "<Gamepad>/leftStick/right");
|
||||
```
|
||||
|
||||
The 2D vector Composite has four part Bindings.
|
||||
|
||||
|Part|Type|Description|
|
||||
|----|----|-----------|
|
||||
|[`up`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_up)|`Button`|Controls representing `(0,1)` (+Y).|
|
||||
|[`down`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_down)|`Button`|Controls representing `(0,-1)` (-Y).|
|
||||
|[`left`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_left)|`Button`|Controls representing `(-1,0)` (-X).|
|
||||
|[`right`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_right)|`Button`|Controls representing `(1,0)` (+X).|
|
||||
|
||||
In addition, you can set the following parameters on a 2D vector Composite:
|
||||
|
||||
|Parameter|Description|
|
||||
|---------|-----------|
|
||||
|[`mode`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_mode)|Whether to treat the inputs as digital or as analog controls.<br><br>If this is set to [`Mode.DigitalNormalized`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector2Composite_Mode_DigitalNormalized), inputs are treated as buttons (off if below [`defaultButtonPressPoint`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint) and on if equal to or greater). Each input is 0 or 1 depending on whether the button is pressed or not. The vector resulting from the up/down/left/right parts is normalized. The result is a diamond-shaped 2D input range.<br><br>If this is set to [`Mode.Digital`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector2Composite_Mode_Digital), the behavior is essentially the same as [`Mode.DigitalNormalized`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector2Composite_Mode_DigitalNormalized) except that the resulting vector is not normalized.<br><br>Finally, if this is set to [`Mode.Analog`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector2Composite_Mode_Analog), inputs are treated as analog (i.e. full floating-point values) and, other than [`down`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_down) and [`left`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_left) being inverted, values will be passed through as is.<br><br>The default is [`Mode.DigitalNormalized`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector2Composite_Mode_DigitalNormalized).|
|
||||
|
||||
>__Note__: There is no support yet for interpolating between the up/down/left/right over time.
|
||||
|
||||
### 3D vector
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A Composite that represents a 6-way button where two combinations each control one axis of a 3D vector. Implemented in the [`Vector3Composite`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html) class. The result is a `Vector3`.
|
||||
|
||||
```CSharp
|
||||
myAction.AddCompositeBinding("3DVector")
|
||||
.With("Up", "<Keyboard>/w")
|
||||
.With("Down", "<Keyboard>/s")
|
||||
.With("Left", "<Keyboard>/a")
|
||||
.With("Right", "<Keyboard>/d");
|
||||
|
||||
// To set mode (2=analog, 1=digital, 0=digitalNormalized):
|
||||
myAction.AddCompositeBinding("3DVector(mode=2)")
|
||||
.With("Up", "<Gamepad>/leftStick/up")
|
||||
.With("Down", "<Gamepad>/leftStick/down")
|
||||
.With("Left", "<Gamepad>/leftStick/left")
|
||||
.With("Right", "<Gamepad>/leftStick/right");
|
||||
```
|
||||
|
||||
The 3D vector Composite has four part Bindings.
|
||||
|
||||
|Part|Type|Description|
|
||||
|----|----|-----------|
|
||||
|[`up`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_up)|`Button`|Controls representing `(0,1,0)` (+Y).|
|
||||
|[`down`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_down)|`Button`|Controls representing `(0,-1,0)` (-Y).|
|
||||
|[`left`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_left)|`Button`|Controls representing `(-1,0,0)` (-X).|
|
||||
|[`right`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_right)|`Button`|Controls representing `(1,0,0)` (+X).|
|
||||
|[`forward`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_forward)|`Button`|Controls representing `(0,0,1)` (+Z).|
|
||||
|[`backward`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_backward)|`Button`|Controls representing `(0,0,-1)` (-Z).|
|
||||
|
||||
In addition, you can set the following parameters on a 3D vector Composite:
|
||||
|
||||
|Parameter|Description|
|
||||
|---------|-----------|
|
||||
|[`mode`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_mode)|Whether to treat the inputs as digital or as analog controls.<br><br>If this is set to [`Mode.DigitalNormalized`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector3Composite_Mode_DigitalNormalized), inputs are treated as buttons (off if below [`defaultButtonPressPoint`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint) and on if equal to or greater). Each input is 0 or 1 depending on whether the button is pressed or not. The vector resulting from the up/down/left/right/forward/backward parts is normalized.<br><br>If this is set to [`Mode.Digital`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector3Composite_Mode_Digital), the behavior is essentially the same as [`Mode.DigitalNormalized`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector3Composite_Mode_DigitalNormalized) except that the resulting vector is not normalized.<br><br>Finally, if this is set to [`Mode.Analog`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector3Composite_Mode_Analog), inputs are treated as analog (that is, full floating-point values) and, other than [`down`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_down), [`left`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_left), and [`backward`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.html#UnityEngine_InputSystem_Composites_Vector3Composite_backward) being inverted, values will be passed through as they are.<br><br>The default is [`Analog`](../api/UnityEngine.InputSystem.Composites.Vector3Composite.Mode.html#UnityEngine_InputSystem_Composites_Vector3Composite_Mode_Analog).|
|
||||
|
||||
### One Modifier
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A Composite that requires the user to hold down a "modifier" button in addition to another control from which the actual value of the Binding is determined. This can be used, for example, for Bindings such as "SHIFT+1". Implemented in the [`OneModifierComposite`](../api/UnityEngine.InputSystem.Composites.OneModifierComposite.html) class. The buttons can be on any Device, and can be toggle buttons or full-range buttons such as gamepad triggers.
|
||||
|
||||
The result is a value of the same type as the controls bound to the [`binding`](../api/UnityEngine.InputSystem.Composites.OneModifierComposite.html#UnityEngine_InputSystem_Composites_OneModifierComposite_binding) part.
|
||||
|
||||
```CSharp
|
||||
// Add binding for "CTRL+1".
|
||||
myAction.AddCompositeBinding("OneModifier")
|
||||
.With("Binding", "<Keyboard>/1")
|
||||
.With("Modifier", "<Keyboard>/ctrl")
|
||||
|
||||
// Add binding to mouse delta such that it only takes effect
|
||||
// while the ALT key is down.
|
||||
myAction.AddCompositeBinding("OneModifier")
|
||||
.With("Binding", "<Mouse>/delta")
|
||||
.With("Modifier", "<Keyboard>/alt");
|
||||
```
|
||||
|
||||
The button with one modifier Composite has two part Bindings.
|
||||
|
||||
|Part|Type|Description|
|
||||
|----|----|-----------|
|
||||
|[`modifier`](../api/UnityEngine.InputSystem.Composites.OneModifierComposite.html#UnityEngine_InputSystem_Composites_OneModifierComposite_modifier)|`Button`|Modifier that has to be held for `binding` to come through. If the user holds any of the buttons bound to the `modifier` at the same time as the button that triggers the action, the Composite assumes the value of the `modifier` Binding. If the user does not press any button bound to the `modifier`, the Composite remains at default value.|
|
||||
|[`binding`](../api/UnityEngine.InputSystem.Composites.OneModifierComposite.html#UnityEngine_InputSystem_Composites_OneModifierComposite_binding)|Any|The control(s) whose value the Composite assumes while the user holds down the `modifier` button.|
|
||||
|
||||
This Composite has no parameters.
|
||||
|
||||
### Two Modifiers
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A Composite that requires the user to hold down two "modifier" buttons in addition to another control from which the actual value of the Binding is determined. This can be used, for example, for Bindings such as "SHIFT+CTRL+1". Implemented in the [`TwoModifiersComposite`](../api/UnityEngine.InputSystem.Composites.TwoModifiersComposite.html) class. The buttons can be on any Device, and can be toggle buttons or full-range buttons such as gamepad triggers.
|
||||
|
||||
The result is a value of the same type as the controls bound to the [`binding`](../api/UnityEngine.InputSystem.Composites.TwoModifiersComposite.html#UnityEngine_InputSystem_Composites_TwoModifiersComposite_binding) part.
|
||||
|
||||
```CSharp
|
||||
myAction.AddCompositeBinding("TwoModifiers")
|
||||
.With("Button", "<Keyboard>/1")
|
||||
.With("Modifier1", "<Keyboard>/leftCtrl")
|
||||
.With("Modifier1", "<Keyboard>/rightCtrl")
|
||||
.With("Modifier2", "<Keyboard>/leftShift")
|
||||
.With("Modifier2", "<Keyboard>/rightShift");
|
||||
```
|
||||
|
||||
The button with two modifiers Composite has three part Bindings.
|
||||
|
||||
|Part|Type|Description|
|
||||
|----|----|-----------|
|
||||
|[`modifier1`](../api/UnityEngine.InputSystem.Composites.TwoModifiersComposite.html#UnityEngine_InputSystem_Composites_TwoModifiersComposite_modifier1)|`Button`|The first modifier the user must hold alongside `modifier2`, for `binding` to come through. If the user does not press any button bound to the `modifier1`, the Composite remains at default value.|
|
||||
|[`modifier2`](../api/UnityEngine.InputSystem.Composites.TwoModifiersComposite.html#UnityEngine_InputSystem_Composites_TwoModifiersComposite_modifier2)|`Button`|The second modifier the user must hold alongside `modifier1`, for `binding` to come through. If the user does not press any button bound to the `modifier2`, the Composite remains at default value.|
|
||||
|[`binding`](../api/UnityEngine.InputSystem.Composites.TwoModifiersComposite.html#UnityEngine_InputSystem_Composites_TwoModifiersComposite_binding)|Any|The control(s) whose value the Composite assumes while the user presses both `modifier1` and `modifier2` at the same time.|
|
||||
|
||||
This Composite has no parameters.
|
||||
|
||||
### Writing custom Composites
|
||||
|
||||
You can define new types of Composites, and register them with the API. Unity treats these the same as predefined types, which the Input System internally defines and registers in the same way.
|
||||
|
||||
To define a new type of Composite, create a class based on [`InputBindingComposite<TValue>`](../api/UnityEngine.InputSystem.InputBindingComposite-1.html).
|
||||
|
||||
> __IMPORTANT__: Composites must be __stateless__. This means that you cannot store local state that changes depending on the input being processed. For __stateful__ processing on Bindings, see [interactions](./Interactions.md#writing-custom-interactions).
|
||||
|
||||
```CSharp
|
||||
// Use InputBindingComposite<TValue> as a base class for a composite that returns
|
||||
// values of type TValue.
|
||||
// NOTE: It is possible to define a composite that returns different kinds of values
|
||||
// but doing so requires deriving directly from InputBindingComposite.
|
||||
#if UNITY_EDITOR
|
||||
[InitializeOnLoad] // Automatically register in editor.
|
||||
#endif
|
||||
// Determine how GetBindingDisplayString() formats the composite by applying
|
||||
// the DisplayStringFormat attribute.
|
||||
[DisplayStringFormat("{firstPart}+{secondPart}")]
|
||||
public class CustomComposite : InputBindingComposite<float>
|
||||
{
|
||||
// Each part binding is represented as a field of type int and annotated with
|
||||
// InputControlAttribute. Setting "layout" restricts the controls that
|
||||
// are made available for picking in the UI.
|
||||
//
|
||||
// On creation, the int value is set to an integer identifier for the binding
|
||||
// part. This identifier can read values from InputBindingCompositeContext.
|
||||
// See ReadValue() below.
|
||||
[InputControl(layout = "Button")]
|
||||
public int firstPart;
|
||||
|
||||
[InputControl(layout = "Button")]
|
||||
public int secondPart;
|
||||
|
||||
// Any public field that is not annotated with InputControlAttribute is considered
|
||||
// a parameter of the composite. This can be set graphically in the UI and also
|
||||
// in the data (e.g. "custom(floatParameter=2.0)").
|
||||
public float floatParameter;
|
||||
public bool boolParameter;
|
||||
|
||||
// This method computes the resulting input value of the composite based
|
||||
// on the input from its part bindings.
|
||||
public override float ReadValue(ref InputBindingCompositeContext context)
|
||||
{
|
||||
var firstPartValue = context.ReadValue<float>(firstPart);
|
||||
var secondPartValue = context.ReadValue<float>(secondPart);
|
||||
|
||||
//... do some processing and return value
|
||||
}
|
||||
|
||||
// This method computes the current actuation of the binding as a whole.
|
||||
public override float EvaluateMagnitude(ref InputBindingCompositeContext context)
|
||||
{
|
||||
// Compute normalized [0..1] magnitude value for current actuation level.
|
||||
}
|
||||
|
||||
static CustomComposite()
|
||||
{
|
||||
// Can give custom name or use default (type name with "Composite" clipped off).
|
||||
// Same composite can be registered multiple times with different names to introduce
|
||||
// aliases.
|
||||
//
|
||||
// NOTE: Registering from the static constructor using InitializeOnLoad and
|
||||
// RuntimeInitializeOnLoadMethod is only one way. You can register the
|
||||
// composite from wherever it works best for you. Note, however, that
|
||||
// the registration has to take place before the composite is first used
|
||||
// in a binding. Also, for the composite to show in the editor, it has
|
||||
// to be registered from code that runs in edit mode.
|
||||
InputSystem.RegisterBindingComposite<CustomComposite>();
|
||||
}
|
||||
|
||||
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
|
||||
static void Init() {} // Trigger static constructor.
|
||||
}
|
||||
```
|
||||
|
||||
The Composite should now appear in the editor UI when you add a Binding, and you can now use it in scripts.
|
||||
|
||||
```CSharp
|
||||
myAction.AddCompositeBinding("custom(floatParameter=2.0)")
|
||||
.With("firstpart", "<Gamepad>/buttonSouth")
|
||||
.With("secondpart", "<Gamepad>/buttonNorth");
|
||||
```
|
||||
|
||||
To define a custom parameter editor for the Composite, you can derive from [`InputParameterEditor<TObject>`](../api/UnityEngine.InputSystem.Editor.InputParameterEditor-1.html).
|
||||
|
||||
```CSharp
|
||||
#if UNITY_EDITOR
|
||||
public class CustomParameterEditor : InputParameterEditor<CustomComposite>
|
||||
{
|
||||
public override void OnGUI()
|
||||
{
|
||||
EditorGUILayout.Label("Custom stuff");
|
||||
target.floatParameter = EditorGUILayout.FloatField("Some Parameter", target.floatParameter);
|
||||
}
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
## Working with Bindings
|
||||
|
||||
## Looking up Bindings
|
||||
|
||||
You can retrieve the bindings of an action using its [`InputAction.bindings`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_bindings) property which returns a read-only array of [`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html) structs.
|
||||
|
||||
```CSharp
|
||||
// Get bindings of "fire" action.
|
||||
var fireBindings = playerInput.actions["fire"].bindings;
|
||||
```
|
||||
|
||||
Also, all the bindings for all actions in an [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) are made available through the [`InputActionMap.bindings`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_bindings) property. The bindings are associated with actions through an [action ID](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id) or [action name](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_name) stored in the [`InputBinding.action`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_action) property.
|
||||
|
||||
```CSharp
|
||||
// Get all bindings in "gameplay" action map.
|
||||
var gameplayBindings = playerInput.actions.FindActionMap("gameplay").bindings;
|
||||
```
|
||||
|
||||
You can also look up specific the indices of specific bindings in [`InputAction.bindings`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_bindings) using the [`InputActionRebindingExtensions.GetBindingIndex`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_GetBindingIndex_UnityEngine_InputSystem_InputAction_UnityEngine_InputSystem_InputBinding_) method.
|
||||
|
||||
```CSharp
|
||||
// Find the binding in the "Keyboard" control scheme.
|
||||
playerInput.actions["fire"].GetBindingIndex(group: "Keyboard");
|
||||
|
||||
// Find the first binding to the space key in the "gameplay" action map.
|
||||
playerInput.FindActionMap("gameplay").GetBindingIndex(
|
||||
new InputBinding { path = "<Keyboard>/space" });
|
||||
```
|
||||
|
||||
Finally, you can look up the binding that corresponds to a specific control through [`GetBindingIndexForControl`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_GetBindingIndexForControl_). This way, you can, for example, map a control found in the [`controls`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_controls) array of an [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) back to an [`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html).
|
||||
|
||||
```CSharp
|
||||
// Find the binding that binds LMB to "fire". If there is no such binding,
|
||||
// bindingIndex will be -1.
|
||||
var fireAction = playerInput.actions["fire"];
|
||||
var bindingIndex = fireAction.GetBindingIndexForControl(Mouse.current.leftButton);
|
||||
if (binding == -1)
|
||||
Debug.Log("Fire is not bound to LMB of the current mouse.");
|
||||
```
|
||||
|
||||
## Changing Bindings
|
||||
|
||||
In general, you can change existing bindings via the [`InputActionSetupExtensions.ChangeBinding`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.html#UnityEngine_InputSystem_InputActionSetupExtensions_ChangeBinding_UnityEngine_InputSystem_InputAction_System_Int32_) method. This returns an accessor that can be used to modify the properties of the targeted [`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html). Note that most of the write operations of the accessor are destructive. For non-destructive changes to bindings, see [Applying Overrides](#applying-overrides).
|
||||
|
||||
```CSharp
|
||||
// Get write access to the second binding of the 'fire' action.
|
||||
var accessor = playerInput.actions['fire'].ChangeBinding(1);
|
||||
|
||||
// You can also gain access through the InputActionMap. Each
|
||||
// map contains an array of all its bindings (see InputActionMap.bindings).
|
||||
// Here we gain access to the third binding in the map.
|
||||
accessor = playerInput.actions.FindActionMap("gameplay").ChangeBinding(2);
|
||||
```
|
||||
|
||||
You can use the resulting accessor to modify properties through methods such as [`WithPath`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.BindingSyntax.html#UnityEngine_InputSystem_InputActionSetupExtensions_BindingSyntax_WithPath_) or [`WithProcessors`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.BindingSyntax.html#UnityEngine_InputSystem_InputActionSetupExtensions_BindingSyntax_WithProcessors_).
|
||||
|
||||
```CSharp
|
||||
playerInput.actions["fire"].ChangeBinding(1)
|
||||
// Change path to space key.
|
||||
.WithPath("<Keyboard>/space");
|
||||
```
|
||||
|
||||
You can also use the accessor to iterate through bindings using [`PreviousBinding`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.BindingSyntax.html#UnityEngine_InputSystem_InputActionSetupExtensions_BindingSyntax_PreviousBinding_) and [`NextBinding`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.BindingSyntax.html#UnityEngine_InputSystem_InputActionSetupExtensions_BindingSyntax_NextBinding_).
|
||||
|
||||
```CSharp
|
||||
// Move accessor to previous binding.
|
||||
accessor = accessor.PreviousBinding();
|
||||
|
||||
// Move accessor to next binding.
|
||||
accessor = accessor.NextBinding();
|
||||
```
|
||||
|
||||
If the given binding is a [composite](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_isComposite), you can address it by its name rather than by index.
|
||||
|
||||
```CSharp
|
||||
// Change the 2DVector composite of the "move" action.
|
||||
playerInput.actions["move"].ChangeCompositeBinding("2DVector")
|
||||
|
||||
|
||||
//
|
||||
playerInput.actions["move"].ChangeBinding("WASD")
|
||||
```
|
||||
|
||||
### Applying overrides
|
||||
|
||||
You can override aspects of any Binding at run-time non-destructively. Specific properties of [`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html) have an `override` variant that, if set, will take precedent over the property that they shadow. All `override` properties are of type `String`.
|
||||
|
||||
|Property|Override|Description|
|
||||
|--------|--------|-----------|
|
||||
|[`path`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_path)|[`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath)|Replaces the [Control path](./Controls.md#control-paths) that determines which Control(s) are referenced in the binding. If [`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath) is set to an empty string, the binding is effectively disabled.<br><br>Example: `"<Gamepad>/leftStick"`|
|
||||
|[`processors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_processors)|[`overrideProcessors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overrideProcessors)|Replaces the [processors](./Processors.md) applied to the binding.<br><br>Example: `"invert,normalize(min=0,max=10)"`|
|
||||
|[`interactions`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_interactions)|[`overrideInteractions`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overrideInteractions)|Replaces the [interactions](./Interactions.md) applied to the binding.<br><br>Example: `"tap(duration=0.5)"`|
|
||||
|
||||
>NOTE: The `override` property values will not be saved along with the Actions (for example, when calling [`InputActionAsset.ToJson()`](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_ToJson)). See [Saving and loading rebinds](#saving-and-loading-rebinds) for details about how to persist user rebinds.
|
||||
|
||||
To set the various `override` properties, you can use the [`ApplyBindingOverride`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_ApplyBindingOverride_UnityEngine_InputSystem_InputAction_UnityEngine_InputSystem_InputBinding_) APIs.
|
||||
|
||||
```CSharp
|
||||
// Rebind the "fire" action to the left trigger on the gamepad.
|
||||
playerInput.actions["fire"].ApplyBindingOverride("<Gamepad>/leftTrigger");
|
||||
```
|
||||
|
||||
In most cases, it is best to locate specific bindings using APIs such as [`GetBindingIndexForControl`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_GetBindingIndexForControl_) and to then apply the override to that specific binding.
|
||||
|
||||
```CSharp
|
||||
// Find the "Jump" binding for the space key.
|
||||
var jumpAction = playerInput.actions["Jump"];
|
||||
var bindingIndex = jumpAction.GetBindingIndexForControl(Keyboard.current.spaceKey);
|
||||
|
||||
// And change it to the enter key.
|
||||
jumpAction.ApplyBindingOverride(bindingIndex, "<Keyboard>/enter");
|
||||
```
|
||||
|
||||
### Erasing Bindings
|
||||
|
||||
You can erase a binding by calling [`Erase`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.BindingSyntax.html#UnityEngine_InputSystem_InputActionSetupExtensions_BindingSyntax_Erase_) on the [binding accessor](../api/UnityEngine.InputSystem.InputActionSetupExtensions.BindingSyntax.html).
|
||||
|
||||
```CSharp
|
||||
// Erase first binding on "fire" action.
|
||||
playerInput.actions["fire"].ChangeBinding(0).Erase();
|
||||
|
||||
// Erase "2DVector" composite. This will also erase the part
|
||||
// bindings of the composite.
|
||||
playerInput.actions["move"].ChangeCompositeBinding("2DVector").Erase();
|
||||
|
||||
// Can also do this by using the name given to the composite binding.
|
||||
playerInput.actions["move"].ChangeCompositeBinding("WASD").Erase();
|
||||
|
||||
// Erase first binding in "gameplay" action map.
|
||||
playerInput.actions.FindActionMap("gameplay").ChangeBinding(0).Erase();
|
||||
```
|
||||
|
||||
### Adding Bindings
|
||||
|
||||
New bindings can be added to an Action using [`AddAction`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.html#UnityEngine_InputSystem_InputActionSetupExtensions_AddBinding_UnityEngine_InputSystem_InputAction_System_String_System_String_System_String_System_String_) or [`AddCompositeBinding`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.html#UnityEngine_InputSystem_InputActionSetupExtensions_AddCompositeBinding_UnityEngine_InputSystem_InputAction_System_String_System_String_System_String_).
|
||||
|
||||
```CSharp
|
||||
// Add a binding for the left mouse button to the "fire" action.
|
||||
playerInput.actions["fire"].AddBinding("<Mouse>/leftButton");
|
||||
|
||||
// Add a WASD composite binding to the "move" action.
|
||||
playerInput.actions["move"]
|
||||
.AddCompositeBinding("2DVector")
|
||||
.With("Up", "<Keyboard>/w")
|
||||
.With("Left", "<Keyboard>/a")
|
||||
.With("Down", "<Keyboard>/s")
|
||||
.With("Right", "<Keyboard>/d");
|
||||
```
|
||||
|
||||
### Setting parameters
|
||||
|
||||
A Binding may, either through itself or through its associated Action, lead to [processor](Processors.md), [interaction](Interactions.md), and/or [composite](#composite-bindings) objects being created. These objects can have parameters you can configure through in the [Binding properties view](ActionsEditor.md#bindings) of the Action editor or through the API. This configuration will give parameters their default value.
|
||||
|
||||
```CSharp
|
||||
// Create an action with a "Hold" interaction on it.
|
||||
// Set the "duration" parameter to 4 seconds.
|
||||
var action = new InputAction(interactions: "hold(duration=4)");
|
||||
```
|
||||
|
||||
You can query the current value of any such parameter using the [`GetParameterValue`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_GetParameterValue_UnityEngine_InputSystem_InputAction_System_String_UnityEngine_InputSystem_InputBinding_) API.
|
||||
|
||||
```CSharp
|
||||
// This returns a PrimitiveValue?. It will be null if the
|
||||
// parameter is not found. Otherwise, it is a PrimitiveValue
|
||||
// which can be converted to a number or boolean.
|
||||
var p = action.GetParameterValue("duration");
|
||||
Debug.Log("'duration' is set to: " + p.Value);
|
||||
```
|
||||
|
||||
The above looks for the parameter on any object found on any of the bindings on the action. You can restrict either or both to a more narrow set.
|
||||
|
||||
```CSharp
|
||||
// Retrieve the value of the "duration" parameter specifically of a
|
||||
// "Hold" interaction and only look on bindings in the "Gamepad" group.
|
||||
action.GetParameterValue("hold:duration", InputBinding.MaskByGroup("Gamepad"));
|
||||
```
|
||||
|
||||
Alternatively, you can use an expression parameter to encapsulate both the type and the name of the parameter you want to get the value of. This has the advantage of not needing a string parameter but rather references both the type and the name of the parameter in a typesafe way.
|
||||
|
||||
```CSharp
|
||||
// Retrieve the value of the "duration" parameter of TapInteraction.
|
||||
// This version returns a float? instead of a PrimitiveValue? as it
|
||||
// sees the type of "duration" at compile-time.
|
||||
action.GetParameterValue((TapInteraction x) => x.duration);
|
||||
```
|
||||
|
||||
To alter the current value of a parameter, you can use what is referred to as a "parameter override". You can apply these at the level of an individual [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html), or at the level of an entire [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html), or even at the level of an entire [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html). Such overrides are stored internally and applied automatically even on bindings added later.
|
||||
|
||||
To add an override, use the [`ApplyParameterOverride`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_ApplyParameterOverride_UnityEngine_InputSystem_InputAction_System_String_UnityEngine_InputSystem_Utilities_PrimitiveValue_UnityEngine_InputSystem_InputBinding_) API or any of its overloads.
|
||||
|
||||
```CSharp
|
||||
// Set the "duration" parameter on all bindings of the action to 4.
|
||||
action.ApplyParameterOverride("duration", 4f);
|
||||
|
||||
// Set the "duration" parameter specifically for "tap" interactions only.
|
||||
action.ApplyParameterOverride("tap:duration", 0.5f);
|
||||
|
||||
// Set the "duration" parameter on tap interactions but only for bindings
|
||||
// in the "Gamepad" group.
|
||||
action.ApplyParameterOverride("tap:duration", 0.5f, InputBinding.MaskByGroup("Gamepad");
|
||||
|
||||
// Set tap duration for all bindings in an action map.
|
||||
map.ApplyParameterOverride("tap:duration", 0.5f);
|
||||
|
||||
// Set tap duration for all bindings in an entire asset.
|
||||
asset.ApplyParameterOverride("tap:duration", 0.5f);
|
||||
|
||||
// Like for GetParameterValue, overloads are available that take
|
||||
// an expression instead.
|
||||
action.ApplyParameterOverride((TapInteraction x) => x.duration, 0.4f);
|
||||
map.ApplyParameterOverride((TapInteraction x) => x.duration, 0.4f);
|
||||
asset.ApplyParameterOverride((TapInteraction x) => x.duration, 0.4f);
|
||||
```
|
||||
|
||||
The new value will be applied immediately and affect all composites, processors, and interactions already in use and targeted by the override.
|
||||
|
||||
Note that if multiple parameter overrides are applied – especially when applying some directly to actions and some to maps or assets –, there may be conflicts between which override to apply. In this case, an attempt is made to chose the "most specific" override to apply.
|
||||
|
||||
```CSharp
|
||||
// Let's say you have an InputAction `action` that is part of an InputActionAsset asset.
|
||||
var map = action.actionMap;
|
||||
var asset = map.asset;
|
||||
|
||||
// And you apply a "tap:duration" override to the action.
|
||||
action.ApplyParameterOverride("tap:duration", 0.6f);
|
||||
|
||||
// But also apply a "tap:duration" override to the action specifically
|
||||
// for bindings in the "Gamepad" group.
|
||||
action.ApplyParameterOverride("tap:duration", 1f, InputBinding.MaskByGroup("Gamepad"));
|
||||
|
||||
// And finally also apply a "tap:duration" override to the entire asset.
|
||||
asset.ApplyParameterOverride("tap:duration", 0.3f);
|
||||
|
||||
// Now, bindings on `action` in the "Gamepad" group will use a value of 1 for tap durations,
|
||||
// other bindings on `action` will use 0.6, and every other binding in the asset will use 0.3.
|
||||
```
|
||||
|
||||
You can use parameter overrides, for example, to scale mouse delta values on a "Look" action.
|
||||
|
||||
```CSharp
|
||||
// Set up an example "Look" action.
|
||||
var look = new InputAction("look", type: InputActionType.Value);
|
||||
look.AddBinding("<Mouse>/delta", groups: "KeyboardMouse", processors: "scaleVector2");
|
||||
look.AddBinding("<Gamepad>/rightStick", groups: "Gamepad", processors: "scaleVector2");
|
||||
|
||||
// Now you can adjust stick sensitivity separately from mouse sensitivity.
|
||||
look.ApplyParameterOverride("scaleVector2:x", 0.5f, InputBinding.MaskByGroup("KeyboardMouse"));
|
||||
look.ApplyParameterOverride("scaleVector2:y", 0.5f, InputBinding.MaskByGroup("KeyboardMouse"));
|
||||
|
||||
look.ApplyParameterOverride("scaleVector2:x", 2f, InputBinding.MaskByGroup("Gamepad"));
|
||||
look.ApplyParameterOverride("scaleVector2:y", 2f, InputBinding.MaskByGroup("Gamepad"));
|
||||
|
||||
// Alternative to using groups, you can also apply overrides directly to specific binding paths.
|
||||
look.ApplyParameterOverride("scaleVector2:x", 0.5f, new InputBinding("<Mouse>/delta"));
|
||||
look.ApplyParameterOverride("scaleVector2:y", 0.5f, new InputBinding("<Mouse>/delta"));
|
||||
```
|
||||
|
||||
>NOTE: Parameter overrides are *not* persisted along with an asset.
|
||||
|
||||
## Interactive rebinding
|
||||
|
||||
>__Note:__ To download a sample project which demonstrates how to set up a rebinding user interface with Input System APIs, open the Package Manager, select the Input System Package, and choose the sample project "Rebinding UI" to download.
|
||||
|
||||
Runtime rebinding allows users of your application to set their own Bindings.
|
||||
|
||||
To allow users to choose their own Bindings interactively, use the [`InputActionRebindingExtensions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) class. Call the [`PerformInteractiveRebinding()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_PerformInteractiveRebinding_UnityEngine_InputSystem_InputAction_System_Int32_) method on an Action to create a rebinding operation. This operation waits for the Input System to register any input from any Device which matches the Action's expected Control type, then uses [`InputBinding.overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath) to assign the Control path for that Control to the Action's Bindings. If the user actuates multiple Controls, the rebinding operation chooses the Control with the highest [magnitude](Controls.md#control-actuation).
|
||||
|
||||
>IMPORTANT: You must dispose of [`InputActionRebindingExtensions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) instances via `Dispose()`, so that they don't leak memory on the unmanaged memory heap.
|
||||
|
||||
```C#
|
||||
void RemapButtonClicked(InputAction actionToRebind)
|
||||
{
|
||||
var rebindOperation = actionToRebind
|
||||
.PerformInteractiveRebinding().Start();
|
||||
}
|
||||
```
|
||||
|
||||
The [`InputActionRebindingExtensions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) API is highly configurable to match your needs. For example, you can:
|
||||
|
||||
* Choose expected Control types ([`WithExpectedControlType()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithExpectedControlType_System_Type_)).
|
||||
|
||||
* Exclude certain Controls ([`WithControlsExcluding()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithControlsExcluding_System_String_)).
|
||||
|
||||
* Set a Control to cancel the operation ([`WithCancelingThrough()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithCancelingThrough_UnityEngine_InputSystem_InputControl_)).
|
||||
|
||||
* Choose which Bindings to apply the operation on if the Action has multiple Bindings ([`WithTargetBinding()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithTargetBinding_System_Int32_), [`WithBindingGroup()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithBindingGroup_System_String_), [`WithBindingMask()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithBindingMask_System_Nullable_UnityEngine_InputSystem_InputBinding__)).
|
||||
|
||||
Refer to the scripting API reference for [`InputActionRebindingExtensions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) for a full overview.
|
||||
|
||||
Note that [`PerformInteractiveRebinding()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_PerformInteractiveRebinding_UnityEngine_InputSystem_InputAction_System_Int32_) automatically applies a set of default configurations based on the given action and targeted binding.
|
||||
|
||||
## Saving and loading rebinds
|
||||
|
||||
You can serialize override properties of [Bindings](../api/UnityEngine.InputSystem.InputBinding.html) by serializing them as JSON strings and restoring them from these. Use [`SaveBindingOverridesAsJson`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_SaveBindingOverridesAsJson_UnityEngine_InputSystem_IInputActionCollection2_) to create these strings and [`LoadBindingOverridesFromJson`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_LoadBindingOverridesFromJson_UnityEngine_InputSystem_IInputActionCollection2_System_String_System_Boolean_) to restore overrides from them.
|
||||
|
||||
```CSharp
|
||||
// Store player rebinds in PlayerPrefs.
|
||||
var rebinds = playerInput.actions.SaveBindingOverridesAsJson();
|
||||
PlayerPrefs.SetString("rebinds", rebinds);
|
||||
|
||||
// Restore player rebinds from PlayerPrefs (removes all existing
|
||||
// overrides on the actions; pass `false` for second argument
|
||||
// in case you want to prevent that).
|
||||
var rebinds = PlayerPrefs.GetString("rebinds");
|
||||
playerInput.actions.LoadBindingOverridesFromJson(rebinds);
|
||||
```
|
||||
|
||||
### Restoring original Bindings
|
||||
|
||||
You can remove Binding overrides and thus restore defaults by using [`RemoveBindingOverride`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RemoveBindingOverride_UnityEngine_InputSystem_InputAction_System_Int32_) or [`RemoveAllBindingOverrides`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RemoveAllBindingOverrides_UnityEngine_InputSystem_IInputActionCollection2_).
|
||||
|
||||
```CSharp
|
||||
// Remove binding overrides from the first binding of the "fire" action.
|
||||
playerInput.actions["fire"].RemoveBindingOverride(0);
|
||||
|
||||
// Remove all binding overrides from the "fire" action.
|
||||
playerInput.actions["fire"].RemoveAllBindingOverrides();
|
||||
|
||||
// Remove all binding overrides from a player's actions.
|
||||
playerInput.actions.RemoveAllBindingOverrides();
|
||||
```
|
||||
|
||||
### Displaying Bindings
|
||||
|
||||
It can be useful for the user to know what an Action is currently bound to (taking any potentially active rebindings into account) while rebinding UIs, and for on-screen hints while the app is running. You can use [`InputBinding.effectivePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_effectivePath) to get the currently active path for a Binding (which returns [`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath) if set, or otherwise returns [`path`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_path)).
|
||||
|
||||
The easiest way to retrieve a display string for an action is to call [`InputActionRebindingExtensions.GetBindingDisplayString`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_GetBindingDisplayString_) which is an extension method for [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html).
|
||||
|
||||
```CSharp
|
||||
// Get a binding string for the action as a whole. This takes into account which
|
||||
// bindings are currently active and the actual controls bound to the action.
|
||||
m_RebindButton.GetComponentInChildren<Text>().text = action.GetBindingDisplayString();
|
||||
|
||||
// Get a binding string for a specific binding on an action by index.
|
||||
m_RebindButton.GetComponentInChildren<Text>().text = action.GetBindingDisplayString(1);
|
||||
|
||||
// Look up binding indices with GetBindingIndex.
|
||||
var bindingIndex = action.GetBindingIndex(InputBinding.MaskByGroup("Gamepad"));
|
||||
m_RebindButton.GetComponentInChildren<Text>().text =
|
||||
action.GetBindingDisplayString(bindingIndex);
|
||||
```
|
||||
|
||||
You can also use this method to replace the text string with images.
|
||||
|
||||
```CSharp
|
||||
// Call GetBindingDisplayString() such that it also returns information about the
|
||||
// name of the device layout and path of the control on the device. This information
|
||||
// is useful for reliably associating imagery with individual controls.
|
||||
// NOTE: The first argument is the index of the binding within InputAction.bindings.
|
||||
var bindingString = action.GetBindingDisplayString(0, out deviceLayout, out controlPath);
|
||||
|
||||
// If it's a gamepad, look up an icon for the control.
|
||||
Sprite icon = null;
|
||||
if (!string.IsNullOrEmpty(deviceLayout)
|
||||
&& !string.IsNullOrEmpty(controlPath)
|
||||
&& InputSystem.IsFirstLayoutBasedOnSecond(deviceLayout, "Gamepad"))
|
||||
{
|
||||
switch (controlPath)
|
||||
{
|
||||
case "buttonSouth": icon = aButtonIcon; break;
|
||||
case "dpad/up": icon = dpadUpIcon; break;
|
||||
//...
|
||||
}
|
||||
}
|
||||
|
||||
// If you have an icon, display it instead of the text.
|
||||
var text = m_RebindButton.GetComponentInChildren<Text>();
|
||||
var image = m_RebindButton.GetComponentInChildren<Image>();
|
||||
if (icon != null)
|
||||
{
|
||||
// Display icon.
|
||||
text.gameObject.SetActive(false);
|
||||
image.gameObject.SetActive(true);
|
||||
image.sprite = icon;
|
||||
}
|
||||
else
|
||||
{
|
||||
// Display text.
|
||||
text.gameObject.SetActive(true);
|
||||
image.gameObject.SetActive(false);
|
||||
text.text = bindingString;
|
||||
}
|
||||
```
|
||||
|
||||
Additionally, each Binding has a [`ToDisplayString`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_ToDisplayString_UnityEngine_InputSystem_InputBinding_DisplayStringOptions_UnityEngine_InputSystem_InputControl_) method, which you can use to turn individual Bindings into display strings. There is also a generic formatting method for Control paths, [`InputControlPath.ToHumanReadableString`](../api/UnityEngine.InputSystem.InputControlPath.html#UnityEngine_InputSystem_InputControlPath_ToHumanReadableString_System_String_UnityEngine_InputSystem_InputControlPath_HumanReadableStringOptions_UnityEngine_InputSystem_InputControl_), which you can use with arbitrary Control path strings.
|
||||
|
||||
Note that the Controls a Binding resolves to can change at any time, and the display strings for controls might change dynamically. For example, if the user switches the currently active keyboard layout, the display string for each individual key on the [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html) might change.
|
||||
|
||||
## Control Schemes
|
||||
|
||||
A Binding can belong to any number of Binding groups. Unity stores these on the [`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html) class as a semicolon-separated string in the [`InputBinding.groups`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_groups) property, and you can use them for any arbitrary grouping of bindings. To enable different sets of binding groups for an [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) or [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html), you can use the [`InputActionMap.bindingMask`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_bindingMask)/[`InputActionAsset.bindingMask`](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_bindingMask) property. The Input System uses this to implement the concept of grouping Bindings into different [`InputControlSchemes`](../api/UnityEngine.InputSystem.InputControlScheme.html).
|
||||
|
||||
Control Schemes use Binding groups to map Bindings in an [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) or [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html) to different types of Devices. The [`PlayerInput`](PlayerInput.md) class uses these to enable a matching Control Scheme for a new [user](UserManagement.md) joining the game, based on the Device they are playing on.
|
||||
|
||||
## Details
|
||||
|
||||
### Binding resolution
|
||||
|
||||
When the Input System accesses the [Controls](Controls.md) bound to an Action for the first time, the Action resolves its Bindings to match them to existing Controls on existing Devices. In this process, the Action calls [`InputSystem.FindControls<>()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_FindControls__1_System_String_UnityEngine_InputSystem_InputControlList___0___) (filtering for devices assigned to the InputActionMap, if there are any) for the Binding path of each of the Action's bindings. This creates a list of resolved Controls that are now bound to the Action.
|
||||
|
||||
Note that a single [Binding path](Controls.md#control-paths) can match multiple Controls:
|
||||
|
||||
* A specific Device path such as `<DualShockGamepad>/buttonEast` matches the "Circle" button on a [PlayStation controller](Gamepad.md#playstation-controllers). If you have multiple PlayStation controllers connected, it resolves to the "Circle" button on each of these controllers.
|
||||
|
||||
* An abstract Device path such as `<Gamepad>/buttonEast` matches the right action button on any connected gamepad. If you have a PlayStation controller and an [Xbox controller](Gamepad.md#xbox-controllers) connected, it resolves to the "Circle" button on the PlayStation controller, and to the "B" button on the Xbox controller.
|
||||
|
||||
* A Binding path can also contain wildcards, such as `<Gamepad>/button*`. This matches any Control on any gamepad with a name starting with "button", which matches all the four action buttons on any connected gamepad. A different example: `*/{Submit}` matches any Control tagged with the "Submit" [usage](Controls.md#control-usages) on any Device.
|
||||
|
||||
If there are multiple Bindings on the same Action that all reference the same Control(s), the Control will effectively feed into the Action multiple times. This is to allow, for example, a single Control to produce different input on the same Action by virtue of being bound in a different fashion (composites, processors, interactions, etc). However, regardless of how many times a Control is bound on any given action, it will only be mentioned once in the Action's [array of `controls`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_controls).
|
||||
|
||||
To query the Controls that an Action resolves to, you can use [`InputAction.controls`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_controls). You can also run this query if the Action is disabled.
|
||||
|
||||
To be notified when binding resolution happens, you can listen to [`InputSystem.onActionChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onActionChange) which triggers [`InputActionChange.BoundControlsAboutToChange`](../api/UnityEngine.InputSystem.InputActionChange.html#UnityEngine_InputSystem_InputActionChange_BoundControlsAboutToChange) before modifying Control lists and triggers [`InputActionChange.BoundControlsChanged`](../api/UnityEngine.InputSystem.InputActionChange.html#UnityEngine_InputSystem_InputActionChange_BoundControlsChanged) after having updated them.
|
||||
|
||||
#### Binding resolution while Actions are enabled
|
||||
|
||||
In certain situations, the [Controls](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_controls) bound to an Action have to be updated more than once. For example, if a new [Device](Devices.md) becomes usable with an Action, the Action may now pick up input from additional controls. Also, if Bindings are added, removed, or modified, Control lists will need to be updated.
|
||||
|
||||
This updating of Controls usually happens transparently in the background. However, when an Action is [enabled](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_enabled) and especially when it is [in progress](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_IsInProgress_), there may be a noticeable effect on the Action.
|
||||
|
||||
Adding or removing a device – either [globally](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_devices) or to/from the [device list](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_devices) of an Action – will remain transparent __except__ if an Action is in progress and it is the device of its [active Control](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_activeControl) that is being removed. In this case, the Action will automatically be [cancelled](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_canceled).
|
||||
|
||||
Modifying the [binding mask](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_bindingMask) or modifying any of the Bindings (such as through [rebinding](#interactive-rebinding) or by adding or removing bindings) will, however, lead to all enabled Actions being temporarily disabled and then re-enabled and resumed.
|
||||
|
||||
#### Choosing which Devices to use
|
||||
|
||||
>__Note__: [`InputUser`](UserManagement.md) and [`PlayerInput`](PlayerInput.md) make use of this facility automatically. They set [`InputActionMap.devices`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_devices) automatically based on the Devices that are paired to the user.
|
||||
|
||||
By default, Actions resolve their Bindings against all Devices present in the Input System (that is, [`InputSystem.devices`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_devices)). For example, if there are two gamepads present in the system, a Binding to `<Gamepad>/buttonSouth` picks up both gamepads and allows the Action to be used from either.
|
||||
|
||||
You can override this behavior by restricting [`InputActionAssets`](../api/UnityEngine.InputSystem.InputActionAsset.html) or individual [`InputActionMaps`](../api/UnityEngine.InputSystem.InputActionMap.html) to a specific set of Devices. If you do this, Binding resolution only takes the Controls of the given Devices into account.
|
||||
|
||||
```
|
||||
var actionMap = new InputActionMap();
|
||||
|
||||
// Restrict the action map to just the first gamepad.
|
||||
actionMap.devices = new[] { Gamepad.all[0] };
|
||||
```
|
||||
|
||||
### Conflicting inputs
|
||||
|
||||
There are two situations where a given input may lead to ambiguity:
|
||||
|
||||
1. Several Controls are bound to the same Action and more than one is feeding input into the Action at the same time. Example: an Action that is bound to both the left and right trigger on a Gamepad and both triggers are pressed.
|
||||
2. The input is part of a sequence of inputs and there are several possible such sequences. Example: one Action is bound to the `B` key and another Action is bound to `Shift-B`.
|
||||
|
||||
#### Multiple, concurrently used Controls
|
||||
|
||||
>__Note:__ This section does not apply to [`PassThrough`](RespondingToActions.md#pass-through) Actions as they are by design meant to allow multiple concurrent inputs.
|
||||
|
||||
For a [`Button`](RespondingToActions.md#button) or [`Value`](RespondingToActions.md#value) Action, there can only be one Control at any time that is "driving" the Action. This Control is considered the [`activeControl`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_activeControl).
|
||||
|
||||
When an Action is bound to multiple Controls, the [`activeControl`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_activeControl) at any point is the one with the greatest level of ["actuation"](Controls.md#control-actuation), that is, the largest value returned from [`EvaluateMagnitude`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude_). If a Control exceeds the actuation level of the current [`activeControl`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_activeControl), it will itself become the active Control.
|
||||
|
||||
The following example demonstrates this mechanism with a [`Button`](RespondingToActions.md#button) Action and also demonstrates the difference to a [`PassThrough`](RespondingToActions.md#pass-through) Action.
|
||||
|
||||
```CSharp
|
||||
// Create a button and a pass-through action and bind each of them
|
||||
// to both triggers on the gamepad.
|
||||
var buttonAction = new InputAction(type: InputActionType.Button,
|
||||
binding: "<Gamepad>/*Trigger");
|
||||
var passThroughAction = new InputAction(type: InputActionType.PassThrough,
|
||||
binding: "<Gamepad>/*Trigger");
|
||||
|
||||
buttonAction.performed += c => Debug.Log("${c.control.name} pressed (Button)");
|
||||
passThroughAction.performed += c => Debug.Log("${c.control.name} changed (Pass-Through)");
|
||||
|
||||
buttonAction.Enable();
|
||||
passThroughAction.Enable();
|
||||
|
||||
// Press the left trigger all the way down.
|
||||
// This will trigger both buttonAction and passThroughAction. Both will
|
||||
// see leftTrigger becoming the activeControl.
|
||||
Set(gamepad.leftTrigger, 1f);
|
||||
|
||||
// Will log
|
||||
// "leftTrigger pressed (Button)" and
|
||||
// "leftTrigger changed (Pass-Through)"
|
||||
|
||||
// Press the right trigger halfway down.
|
||||
// This will *not* trigger or otherwise change buttonAction as the right trigger
|
||||
// is actuated *less* than the left one that is already driving action.
|
||||
// However, passThrough action is not performing such tracking and will thus respond
|
||||
// directly to the value change. It will perform and make rightTrigger its activeControl.
|
||||
Set(gamepad.rightTrigger, 0.5f);
|
||||
|
||||
// Will log
|
||||
// "rightTrigger changed (Pass-Through)"
|
||||
|
||||
// Release the left trigger.
|
||||
// For buttonAction, this will mean that now all controls feeding into the action have
|
||||
// been released and thus the button releases. activeControl will go back to null.
|
||||
// For passThrough action, this is just another value change. So, the action performs
|
||||
// and its active control changes to leftTrigger.
|
||||
Set(gamepad.leftTrigger, 0f);
|
||||
|
||||
// Will log
|
||||
// "leftTrigger changed (Pass-Through)"
|
||||
```
|
||||
|
||||
For [composite bindings](#composite-bindings), magnitudes of the composite as a whole rather than for individual Controls are tracked. However, [`activeControl`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_activeControl) will stick track individual Controls from the composite.
|
||||
|
||||
##### Disabling Conflict Resolution
|
||||
|
||||
Conflict resolution is always applied to [Button](RespondingToActions.md#button) and [Value](RespondingToActions.md#value) type Actions. However, it can be undesirable in situations when an Action is simply used to gather any and all inputs from bound Controls. For example, the following Action would monitor the A button of all available gamepads:
|
||||
|
||||
```CSharp
|
||||
var action = new InputAction(type: InputActionType.PassThrough, binding: "<Gamepad>/buttonSouth");
|
||||
action.Enable();
|
||||
```
|
||||
|
||||
By using the [Pass-Through](RespondingToActions.md#pass-through) Action type, conflict resolution is bypassed and thus, pressing the A button on one gamepad will not result in a press on a different gamepad being ignored.
|
||||
|
||||
#### Multiple input sequences (such as keyboard shortcuts)
|
||||
|
||||
>__Note__: The mechanism described here only applies to Actions that are part of the same [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) or [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html).
|
||||
|
||||
Inputs that are used in combinations with other inputs may also lead to ambiguities. If, for example, the `b` key on the Keyboard is bound both on its own as well as in combination with the `shift` key, then if you first press `shift` and then `b`, the latter key press would be a valid input for either of the Actions.
|
||||
|
||||
The way this is handled is that Bindings will be processed in the order of decreasing "complexity". This metric is derived automatically from the Binding:
|
||||
|
||||
* A binding that is *not* part of a [composite](#composite-bindings) is assigned a complexity of 1.
|
||||
* A binding that *is* part of a [composite](#composite-bindings) is assigned a complexity equal to the number of part bindings in the composite.
|
||||
|
||||
In our example, this means that a [`OneModifier`](#one-modifier) composite Binding to `Shift+B` has a higher "complexity" than a Binding to `B` and thus is processed first.
|
||||
|
||||
Additionally, the first Binding that results in the Action changing [phase](RespondingToActions.md#action-callbacks) will "consume" the input. This consuming will result in other Bindings to the same input not being processed. So in our example, when `Shift+B` "consumes" the `B` input, the Binding to `B` will be skipped.
|
||||
|
||||
The following example illustrates how this works at the API level.
|
||||
|
||||
```CSharp
|
||||
// Create two actions in the same map.
|
||||
var map = new InputActionMap();
|
||||
var bAction = map.AddAction("B");
|
||||
var shiftbAction = map.AddAction("ShiftB");
|
||||
|
||||
// Bind one of the actions to 'B' and the other to 'SHIFT+B'.
|
||||
bAction.AddBinding("<Keyboard>/b");
|
||||
shiftbAction.AddCompositeBinding("OneModifier")
|
||||
.With("Modifier", "<Keyboard>/shift")
|
||||
.With("Binding", "<Keyboard>/b");
|
||||
|
||||
// Print something to the console when the actions are triggered.
|
||||
bAction.performed += _ => Debug.Log("B action performed");
|
||||
shiftbAction.performed += _ => Debug.Log("SHIFT+B action performed");
|
||||
|
||||
// Start listening to input.
|
||||
map.Enable();
|
||||
|
||||
// Now, let's assume the left shift key on the keyboard is pressed (here, we manually
|
||||
// press it with the InputTestFixture API).
|
||||
Press(Keyboard.current.leftShiftKey);
|
||||
|
||||
// And then the B is pressed. This is a valid input for both
|
||||
// bAction as well as shiftbAction.
|
||||
//
|
||||
// What will happen now is that shiftbAction will do its processing first. In response,
|
||||
// it will *perform* the action (i.e. we see the `performed` callback being invoked) and
|
||||
// thus "consume" the input. bAction will stay silent as it will in turn be skipped over.
|
||||
Press(keyboard.bKey);
|
||||
```
|
||||
|
||||
### Initial state check
|
||||
|
||||
After an Action is [enabled](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_enabled), it will start reacting to input as it comes in. However, at the time the Action is enabled, one or more of the Controls that are [bound](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_controls) to an action may already have a non-default state at that point.
|
||||
x
|
||||
Using what is referred to as an "initial state check", an Action can be made to respond to such a non-default state as if the state change happened *after* the Action was enabled. The way this works is that in the first input [update](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update_) after the Action was enabled, all its bound controls are checked in turn. If any of them has a non-default state, the Action responds right away.
|
||||
|
||||
This check is implicitly enabled for [Value](RespondingToActions.md#value) actions. If, for example, you have a `Move` Action bound to the left stick on the gamepad and the stick is already pushed in a direction when `Move` is enabled, the character will immediately start walking.
|
||||
|
||||
By default, [Button](RespondingToActions.md#button) and [Pass-Through](RespondingToActions.md#pass-through) type Actions, do not perform this check. A button that is pressed when its respective Action is enabled first needs to be released and then pressed again for it to trigger the Action.
|
||||
|
||||
However, you can manually enable initial state checks on these types of Actions using the checkbox in the editor:
|
||||
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
uid: input-system-actions
|
||||
---
|
||||
# Actions
|
||||
|
||||
**Actions** are an important concept in the Input System. They allow you to separate the purpose of an input from the device controls which perform that input. Actions allow you to associate the purpose and device controls together in a flexible way.
|
||||
|
||||
For example, the purpose of an input in a game might be to make the player's character move around. The device control associated with that action might be the motion of the left gamepad stick.
|
||||
|
||||
The association between an Action and the device controls which perform that input is a **binding**, and you can set up bindings in the [Input Actions editor](ActionsEditor.md). When you use Actions in your code, you do not need to refer to specific devices because the binding defines which device's controls are used to perform the action.
|
||||
|
||||
To use actions in your code, you must use the [Input Actions editor](ActionsEditor.md) to establish the mapping between the Action and one or more device controls. For example in this screenshot, the "Move" action is displayed, showing its bindings the left gamepad stick, and the keyboard's arrow keys.
|
||||
|
||||
<br/>
|
||||
*The Actions panel of the Input Actions Editor in Project Settings*
|
||||
|
||||
You can then get a reference to this action in your code, and check its value, or attach a callback method to be notified when it is performed. See the [Actions Workflow page](Workflow-Actions.md) for a simple example script demonstrating this.
|
||||
|
||||
Actions also make it simpler to create a system that lets your players [customize their bindings at runtime](ActionBindings.md#interactive-rebinding), which is a common requirement for games.
|
||||
|
||||
>**Notes:**
|
||||
> - Actions are a runtime only feature. You can't use them in [Editor window code](https://docs.unity3d.com/ScriptReference/EditorWindow.html).
|
||||
>
|
||||
> - You can read input without using Actions and Bindings by directly reading specific device controls. This is less flexible, but can be quicker to implement for certain situations. Read more about [directly reading devices from script](Workflow-Direct.md).
|
||||
>
|
||||
> - Although you can reorder actions in this window, the ordering is for visual convenience only, and does not affect the order in which the actions are triggered in your code. If multiple actions are performed in the same frame, the order in which they are reported by the input system is undefined. To avoid problems, you should not write code that assumes they will be reported in a particular order.
|
||||
> <br/>
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
When scripting with Actions in the Input System, there are number of important API you can use, which are described here:
|
||||
|
||||
|API name|Description|
|
||||
|-----|-----------|
|
||||
|[`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html)|A reference to the set of actions assigned as the [project-wide Actions](./ProjectWideActions.md).|
|
||||
|[`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html)|A named collection of Actions. The API equivalent to an entry in the "Action Maps" column of the [Input Actions editor](ActionsEditor.md).|
|
||||
|[`InputAction`](../api/UnityEngine.InputSystem.InputAction.html)|A named Action that can return the current value of the controls that it is bound to, or can trigger callbacks in response to input. The API equivalent to an entry in the "Actions" column of the [Input Actions editor](ActionsEditor.md).|
|
||||
|[`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html)|The relationship between an Action and the specific device controls for which it receives input. For more information about Bindings and how to use them, see [Action Bindings](ActionBindings.md).|
|
||||
|
||||
Each Action has a name ([`InputAction.name`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_name)), which must be unique within the Action Map that the Action belongs to, if any (see [`InputAction.actionMap`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_actionMap)). Each Action also has a unique ID ([`InputAction.id`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id)), which you can use to reference the Action. The ID remains the same even if you rename the Action.
|
||||
|
||||
Each Action Map has a name ([`InputActionMap.name`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_name)), which must also be unique with respect to the other Action Maps present, if any. Each Action Map also has a unique ID ([`InputActionMap.id`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_id)), which you can use to reference the Action Map. The ID remains the same even if you rename the Action Map.
|
||||
|
||||
## Creating Actions
|
||||
|
||||
The simplest way to create actions is to use the [Input Actions editor](ActionsEditor.md) in the Project Settings window. This is the primary recommended workflow and suitable for most scenarios.
|
||||
|
||||
However, because the input system API is very open, there are many other ways to create actions which may suit less common scenarios. For example, by loading actions from JSON data, or creating actions entirely in code.
|
||||
|
||||
### Creating Actions using the Action editor
|
||||
|
||||
For information on how to create and edit Input Actions in the editor, see the [Input Actions editor](ActionsEditor.md). This is the recommended workflow if you want to organise all your input actions and bindings in one place, which applies across the whole of your project. This often the case for most types of game or app.
|
||||
|
||||
|
||||
*The Input Actions Editor in the Project Settings window*
|
||||
|
||||
|
||||
# Other ways to create Actions
|
||||
|
||||
The simplest way to create actions is to use the [Input Actions editor](ActionsEditor.md) to configure a set of actions in an asset, as described above. However, because the Input System package API is open and flexible, you can create actions using alternative techniques. These alternatives might be more suitable if you want to customize your project beyond the standard workflow.
|
||||
|
||||
### Creating Actions by declaring them in MonoBehaviours
|
||||
|
||||
As an alternative workflow, you can declare individual [Input Action](../api/UnityEngine.InputSystem.InputAction.html) and [Input Action Maps](../api/UnityEngine.InputSystem.InputActionMap.html) as fields directly inside `MonoBehaviour` components.
|
||||
|
||||
```CSharp
|
||||
using UnityEngine;
|
||||
using UnityEngine.InputSystem;
|
||||
|
||||
public class ExampleScript : MonoBehaviour
|
||||
{
|
||||
public InputAction move;
|
||||
public InputAction jump;
|
||||
}
|
||||
```
|
||||
|
||||
The result is similar to using an Actions defined in the Input Actions editor, except the Actions are defined in the GameObject's properties and saved as Scene or Prefab data, instead of in a dedicated Asset.
|
||||
|
||||
When you embed actions like this, by defining serialized InputAction fields in a MonoBehaviour, the GameObject's Inspector window displays an interface similar to the Actions column of the [Actions Editor](./ActionsEditor.md), which allows you to set up the bindings for those actions. For example:
|
||||
|
||||
|
||||
|
||||
* To add or remove Actions or Bindings, click the Add (+) or Remove (-) icon in the header.
|
||||
* To edit Bindings, double-click them.<br>
|
||||
* To edit Actions, double-click them in an Action Map, or click the gear icon on individual Action properties.<br>
|
||||
* You can also right-click entries to bring up a context menu, and you can drag them. Hold the Alt key and drag an entry to duplicate it.
|
||||
|
||||
Unlike the project-wide actions in the Project Settings window, you must manually enable and disable Actions and Action Maps that are embedded in MonoBehaviour components.
|
||||
|
||||
When you use this workflow, the serialised action configurations are stored with the parent GameObject as part of the scene, opposite to being serialised with an Action Asset. This can be useful if you want to bundle the control bindings and behaviour together in a single monobehaviour or prefab, so it can be distributed together. However, this can also make it harder to organize your full set of control bindings if they are distributed across multiple prefabs or scenes.
|
||||
|
||||
### Loading Actions from JSON
|
||||
|
||||
You can load Actions as JSON in the form of a set of Action Maps or as a full [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html). This also works at runtime in the Player.
|
||||
|
||||
```CSharp
|
||||
// Load a set of action maps from JSON.
|
||||
var maps = InputActionMap.FromJson(json);
|
||||
|
||||
// Load an entire InputActionAsset from JSON.
|
||||
var asset = InputActionAsset.FromJson(json);
|
||||
```
|
||||
|
||||
### Creating Actions in code
|
||||
|
||||
You can manually create and configure Actions entirely in code, including assigning the bindings. This also works at runtime in the Player. For example:
|
||||
|
||||
```CSharp
|
||||
// Create free-standing Actions.
|
||||
var lookAction = new InputAction("look", binding: "<Gamepad>/leftStick");
|
||||
var moveAction = new InputAction("move", binding: "<Gamepad>/rightStick");
|
||||
|
||||
lookAction.AddBinding("<Mouse>/delta");
|
||||
moveAction.AddCompositeBinding("Dpad")
|
||||
.With("Up", "<Keyboard>/w")
|
||||
.With("Down", "<Keyboard>/s")
|
||||
.With("Left", "<Keyboard>/a")
|
||||
.With("Right", "<Keyboard>/d");
|
||||
|
||||
// Create an Action Map with Actions.
|
||||
var map = new InputActionMap("Gameplay");
|
||||
var lookAction = map.AddAction("look");
|
||||
lookAction.AddBinding("<Gamepad>/leftStick");
|
||||
|
||||
// Create an Action Asset.
|
||||
var asset = ScriptableObject.CreateInstance<InputActionAsset>();
|
||||
var gameplayMap = new InputActionMap("gameplay");
|
||||
asset.AddActionMap(gameplayMap);
|
||||
var lookAction = gameplayMap.AddAction("look", "<Gamepad>/leftStick");
|
||||
```
|
||||
|
||||
Any action that you create in this way during Play mode do not persist in the Input Action Asset after you exit Play mode. This means you can test your application in a realistic manner in the Editor without having to worry about inadvertently modifying the asset.
|
||||
|
||||
|
||||
## Enabling actions
|
||||
|
||||
Actions have an **enabled** state, meaning you can enable or disable them to suit different situations.
|
||||
|
||||
If you have an Action Asset assigned as [project-wide](./ProjectWideActions.md), the actions it contains are enabled by default and ready to use.
|
||||
|
||||
For actions defined elsewhere, such as in an Action Asset not assigned as project-wide, or defined your own code, they begin in a disabled state, and you must enable them before they will respond to input.
|
||||
|
||||
You can enable actions individually, or as a group by enabling the Action Map which contains them.
|
||||
|
||||
```CSharp
|
||||
// Enable a single action.
|
||||
lookAction.Enable();
|
||||
|
||||
// Enable an en entire action map.
|
||||
gameplayActions.Enable();
|
||||
```
|
||||
|
||||
When you enable an Action, the Input System resolves its bindings, unless it has done so already, or if the set of devices that the Action can use has not changed. For more details about this process, see the documentation on [binding resolution](ActionBindings.md#binding-resolution).
|
||||
|
||||
You can't change certain aspects of the configuration, such Action Bindings, while an Action is enabled. To stop Actions or Action Maps from responding to input, call [`Disable`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_Disable).
|
||||
|
||||
While enabled, an Action actively monitors the [Control(s)](Controls.md) it's bound to. If a bound Control changes state, the Action processes the change. If the Control's change represents an [Interaction](Interactions.md) change, the Action creates a response. All of this happens during the Input System update logic. Depending on the [update mode](Settings.md#update-mode) selected in the input settings, this happens once every frame, once every fixed update, or manually if updates are set to manual.
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
uid: input-system-configuring-input
|
||||
---
|
||||
# Configuring Input with the Actions Editor
|
||||
|
||||
The **Input Actions Editor** allows you to edit [Action Assets](ActionAssets.md), which contain a saved configuration of [Input Actions](Actions.md) and their associated [Bindings](ActionBindings.md).
|
||||
|
||||
It allows you to group collections of Actions into [Action Maps](ActionsEditor.html#configure-action-maps), which represent different input scenarios in your project (such as UI navigation, gameplay, etc.)
|
||||
|
||||
It also alows you to define [Control Schemes](ActionBindings.md#control-schemes) which are a way to enable or disable a set of devices, or respond to which type of device is being used. This is often useful if you want to customise your UI based on whether your users are using mouse, keyboard, or gamepad as their chosen input.
|
||||
|
||||
### Action Assets and Project-Wide Actions
|
||||
|
||||
The typical workflow for most projects is to have a single Action Asset, which is assigned as the **project-wide actions**. If you have not yet created and assigned an Actions Asset as the project-wide actions, the recommended workflow is to do this first. Read more about [project-wide actions](ProjectWideActions.md).
|
||||
|
||||
### Opening the Actions Editor
|
||||
|
||||
The **Input Actions Editor** is an editor window displayed when you open an Action Asset by double-clicking it.
|
||||
|
||||
It is also displayed in the Project Settings window under **Edit** > **Project Settings** > **Input System Package** if you have an Action Asset assigned as project-wide.
|
||||
|
||||
|
||||
*The Input Actions editor, displaying the default actions*
|
||||
|
||||
### The Actions Editor panels
|
||||
|
||||
The Input Actions editor is divided into three panels (marked A, B & C above).
|
||||
|
||||
|Name|Description|
|
||||
|-|-|
|
||||
|**(A) Action Maps**|Displays the list of currently defined Action Maps. Each Action Map is a collection of Actions that you can enable or disable together as a group.|
|
||||
|**(B) Actions**|Displays all the actions defined in the currently selected Action Map, and the bindings associated with each Action.|
|
||||
|**(C) Properties**|Displays the properties of the currently selected Action or Binding from the Actions panel. The title of this panel changes depending on whether you have an Action or a Binding selected in the Actions panel.|
|
||||
|
||||
### Configure Action Maps
|
||||
|
||||
* To add a new Action Map, select the Add (+) icon in the header of the Action Map panel.
|
||||
* To rename an existing Action Map, either long-click the name, or right-click the Action Map and select __Rename__ from the context menu. Note that Action Map names can't contain slashes (`/`).
|
||||
* To delete an existing Action Map, right-click it and select __Delete__ from the context menu.
|
||||
* To duplicate an existing Action Map, right-click it and select __Duplicate__ from the context menu.
|
||||
|
||||
### Configure Actions
|
||||
|
||||
* To add a new Action, select the Add (+) icon in the header of the Action column.
|
||||
* To rename an existing Action, either long-click the name, or right-click the Action Map and select __Rename__ from the context menu.
|
||||
* To delete an existing Action, either right-click it and select __Delete__ from the context menu.
|
||||
* To duplicate an existing Action, either right-click it and select __Duplicate__ from the context menu.
|
||||
*
|
||||
|
||||
|
||||
## Action type and Control type
|
||||
|
||||
If you select an Action, you can edit its properties in the right-hand pane of the window:
|
||||
|
||||
|
||||
|
||||
#### Action Type
|
||||
|
||||
The Action Type setting allows to to select between **Button**, **Value** or **PassThrough**.
|
||||
|
||||
These options relate to whether this action should represent a discrete on/off button-style interaction or a value that can change over time while the control is being used.
|
||||
|
||||
For device controls such as keyboard keys, mouse clicks, or gamepad buttons, select **Button**. For device controls such as mouse movement, a joystick or gamepad stick, or device orientation that provide continuously changing input over a period of time, select **Value**.
|
||||
|
||||
The Button and Value types of action also provides data about the action such as whether it has started and stopped, and conflict resolution in situations where multiple bindings are mapped to the same action.
|
||||
|
||||
The third option, **PassThrough**, is also a value type, and as such is suitable for the same types of device controls as value. The difference is that actions set to PassThrough only provide basic information about the values incoming from the device controls bound to it, and does not provide the extra data relating to the phase of the action, nor does it perform conflict resolution in the case of multiple controls mapped to the same action.
|
||||
|
||||
For more detail about how these types work, see [action types](RespondingToActions.html#action-types) and [default interactions](Interactions.html#default-interaction).
|
||||
|
||||
#### Control Type
|
||||
|
||||
The Control Type setting allows you to select the type of control expected by the action. This limits the controls shown when setting up bindings in the UI and also limits which contols can be bound interactively to the action.
|
||||
|
||||
For example, if you select **2D axis**, only those controls that can supply a 2D vector as value are available as options for the binding control path.
|
||||
|
||||
There are more specific control types available which futher filter the available bindings, such as "Stick", "Dpad" or "Touch". If you select one of these control types, the list of available controls is further limited to only those controls of those specific types when you select a binding for your action (see directly below).
|
||||
|
||||
### Bindings
|
||||
|
||||
* To add a new Binding, select the Add (+) icon on the action you want to add it to, and select the binding type from the menu that appears.
|
||||
* To delete an existing Binding, either right-click it and select __Delete__ from the context menu.
|
||||
* To duplicate an existing Binding, either right-click it and select __Duplicate__ from the context menu.
|
||||
|
||||
You can add multiple bindings to an action, which is generally useful for supporting multiple types of input device. For example, in the default set of actions, the "Move" action has a binding to the left gamepad stick and the WSAD keys, which means input through any of these bindings will perform the action.
|
||||
|
||||
<br/>
|
||||
_The default "Move" action in the Actions Editor window, displaying the multiple bindings associated with it._
|
||||
|
||||
If you select a Binding, you can edit its properties in the right-hand pane of the window:
|
||||
|
||||
|
||||
|
||||
#### Picking Controls
|
||||
|
||||
The most important property of any Binding is the [control path](Controls.md#control-paths) it's bound to. To edit it, open the __Path__ drop-down list. This displays a Control picker window.
|
||||
|
||||
|
||||
|
||||
In the Control picker window, you can explore a tree of Input Devices and Controls that the Input System recognizes, and bind to these Controls. Unity filters this list by the Action's [`Control Type`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_expectedControlType) property. For example, if the Control type is `Vector2`, you can only select a Control that generates two-dimensional values, like a stick.
|
||||
|
||||
The Device and Control tree is organized hierarchically from generic to specific. For example, the __Gamepad__ Control path `<Gamepad>/buttonSouth` matches the lower action button on any gamepad. Alternatively, if you navigate to __Gamepad__ > __More Specific Gamepads__ and select __PS4 Controller__, and then choose the Control path `<DualShockGamepad>/buttonSouth`, this only matches the "Cross" button on PlayStation gamepads, and doesn't match any other gamepads.
|
||||
|
||||
Instead of browsing the tree to find the Control you want, it's easier to let the Input System listen for input. To do that, select the __Listen__ button. At first, the list of Controls is empty. Once you start pressing buttons or actuating Controls on the Devices you want to bind to, the Control picker window starts listing any Bindings that match the controls you pressed. Select any of these Bindings to view them.
|
||||
|
||||
Finally, you can choose to manually edit the Binding path, instead of using the Control picker. To do that, select the __T__ button next to the Control path popup. This changes the popup to a text field, where you can enter any Binding string. This also allows you to use wildcard (`*`) characters in your Bindings. For example, you can use a Binding path such as `<Touchscreen>/touch*/press` to bind to any finger being pressed on the touchscreen, instead of manually binding to `<Touchscreen>/touch0/press`, `<Touchscreen>/touch1/press` and so on.
|
||||
|
||||
#### Editing Composite Bindings
|
||||
|
||||
Composite Bindings are Bindings consisting of multiple parts, which form a Control together. For instance, a [2D Vector Composite](ActionBindings.md#2d-vector) uses four buttons (left, right, up, down) to simulate a 2D stick input. See the [Composite Bindings](ActionBindings.md#composite-bindings) documentation to learn more.
|
||||
|
||||
|
||||
|
||||
To create a Composite Binding, in the Input Action Asset editor window, select the Add (+) icon on the Action you want to add it to, and select the Composite Binding type from the popup menu.
|
||||
|
||||
|
||||
|
||||
This creates multiple Binding entries for the Action: one for the Composite as a whole, and then, one level below that, one for each Composite part. The Composite itself doesn't have a Binding path property, but its individual parts do, and you can edit these parts like any other Binding. Once you bind all the Composite's parts, the Composite can work together as if you bound a single control to the Action.
|
||||
|
||||
**Note**: The set of Composites displayed in the menu is depends on the value type of the Action. This means that, for example, if the Action is set to type "Button", then only Composites able to return values of type `float` will be shown.
|
||||
|
||||
To change the type of a Composite retroactively, select the Composite, then select the new type from the **Composite Type** drop-down in the **Properties** pane.
|
||||
|
||||
|
||||
|
||||
To change the part of the Composite to which a particular Binding is assigned, use the **Composite Part** drop-down in the Binding's properties.
|
||||
|
||||
|
||||
|
||||
You can assign multiple Bindings to the same part. You can also duplicate individual part Bindings: right-click the Binding, then select **Duplicate** to create new part Bindings for the Composite. This can be used, for example, to create a single Composite for both "WASD" style controls and arrow keys.
|
||||
|
||||
|
||||
|
||||
### Editing Control Schemes
|
||||
|
||||
Input Action Assets can have multiple [Control Schemes](ActionBindings.md#control-schemes), which let you enable or disable different sets of Bindings for your Actions for different types of Devices.
|
||||
|
||||
|
||||
|
||||
To see the Control Schemes in the Input Action Asset editor window, open the Control Scheme drop-down list in the top left of the window. This menu lets you add or remove Control Schemes to your Actions Asset. If the Actions Asset contains any Control Schemes, you can select a Control Scheme, and then the window only shows bindings that are associated with that Scheme. If you select a binding, you can now pick the Control Schemes for which this binding should be active in the __Properties__ view to the left of the window.
|
||||
|
||||
When you add a new Control Scheme, or select an existing Control Scheme, and then select __Edit Control Scheme__, you can edit the name of the Control Scheme and which devices the Scheme should be active for. When you add a new Control Scheme, the "Device Type" list is empty by default (as shown above). You must add at least one type of device to this list for the Control Scheme to be functional.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
uid: input-system-architecture
|
||||
---
|
||||
# Architecture
|
||||
|
||||
The Input System has a layered architecture that consists of a low-level layer and a high-level layer.
|
||||
|
||||
# Native backend
|
||||
|
||||
The foundation of the Input System is the native backend code. This is platform-specific code which collects information about available Devices and input data from Devices. This code is not part of the Input System package, but is included with Unity itself. It has implementations for each runtime platform supported by Unity. This is why some platform-specific input bugs can only be fixed by an update to Unity, rather than a new version of the Input System package.
|
||||
|
||||
The Input System interfaces with the native backend using [events](Events.md) that the native backend sends. These events notify the system of the creation and removal of [Input Devices](Devices.md), as well as any updates to the Device states. For efficiency and to avoid creating any garbage, the native backend reports these events as a simple buffer of raw, unmanaged memory containing a stream of events.
|
||||
|
||||
The Input System can also send data back to the native backend in the form of [commands](Devices.md#device-commands) sent to Devices, which are also buffers of memory that the native backend interprets. These commands can have different meanings for different Device types and platforms.
|
||||
|
||||
# Input System (low-level)
|
||||
|
||||
|
||||
|
||||
The low-level Input System code processes and interprets the memory from the event stream that the native backend provides, and dispatches individual events.
|
||||
|
||||
The Input System creates Device representations for any newly discovered Device in the event stream. The low-level code sees a Device as a block of raw, unmanaged memory. If it receives a state event for a Device, it writes the data from the state event into the Device's [state representation](Controls.md#control-state) in memory, so that the state always contains an up-to-date representation of the Device and all its Controls.
|
||||
|
||||
The low-level system code also contains structs which describe the data layout of commonly known Devices.
|
||||
|
||||
# Input System (high-level)
|
||||
|
||||
|
||||
|
||||
The high-level Input System code interprets the data in a Device's state buffers by using [layouts](Layouts.md), which describe the data layout of a Device and its Controls in memory. The Input System creates layouts from either the pre-defined structs of commonly known Devices supplied by the low level system, or dynamically at runtime, as in the case of [generic HIDs](HID.md#auto-generated-layouts).
|
||||
|
||||
Based on the information in the layouts, the Input System then creates [Control](Controls.md) representations for each of the Device's controls, which let you read the state of each individual Control in a Device.
|
||||
|
||||
As part of the high-level system, you can also build another abstraction layer to map Input Controls to your application mechanics. Use [Actions](Actions.md) to [bind](ActionBindings.md) one or more Controls to an input in your application. The Input System then monitors these Controls for state changes, and notifies your game logic using [callbacks](RespondingToActions.md#responding-to-actions-using-callbacks). You can also specify more complex behaviors for your Actions using [Processors](Processors.md) (which perform processing on the input data before sending it to you) and [Interactions](Interactions.md) (which let you specify patterns of input on a Control to listen to, such as multi-taps).
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
uid: basic-concepts
|
||||
---
|
||||
# Basic Concepts
|
||||
|
||||
This page introduces the basic concepts that relate to working with the Input System. They relate to the steps in the sequence of events that occur when a user sends input to your game or app. The Input System provides features which implement these steps, or you can choose to implement some of them yourself.
|
||||
|
||||
|
||||
|
||||
|Concept|Description|
|
||||
|-------|-----------|
|
||||
|[**User**](UserManagement.html)| The person playing your game or using your app, by holding or touching the input device and providing input.|
|
||||
|[**Input Device**](SupportedDevices.html)| Often referred to just as a "**device**" within the context of input. A physical piece of hardware, such as a keyboard, gamepad, mouse, or touchscreen which allows the user to send input into Unity.|
|
||||
|[**Control**](Controls.html)|The separate individual parts of an input device which each send input values into Unity. For example, a gamepad’s **controls** comprise multiple buttons, sticks and triggers, and a mouse’s controls include the two X and Y sensors on the underside, and the various buttons and scroll wheels on the top side.|
|
||||
|[**Action**](Actions.html)| Actions are a high-level concept that describe individual things that a user might want to do in your game or app, such as "Jump" within a game, or "Select" in an on-screen UI. They are things a user can do in your game or app as a result of input, regardless of what device or control they use to perform it. Actions generally have conceptual names that you choose to suit your project, and should usually be verbs. For example "Run", "Jump" "Crouch", "Use", "Start", "Quit".|
|
||||
|[**Action Map**](ActionsEditor.html#configure-action-maps) | Action Maps allow you to organise Actions into groups which represent specific situations where a set of actions make sense together. You can simultaneously enable or disable all Actions in an action map, so it is useful to group Actions in Action Maps by the context in which they are relevant. For example, you might have one action map for controlling a player, and another for interacting with your game's UI.|
|
||||
|[**Binding**](ActionBindings.html)| A connection defined between an **Action** and specific device controls. For example, your "Move" action might have bindings to the arrow keys and WSAD keys on the keyboard, and the left stick on a joypad, and the primary 2D axis on a VR controller. Multiple bindings like this means your game can accept cross-platform input. |
|
||||
|[**Your Action Code**](RespondingToActions.md)| The part of your script which is executed based on the actions you have configured. In your code, you can use references to actions to either read the current value or state of the action (also known as "polling"), or set up a callback to call your own method when actions are performed.|
|
||||
|[**Action Asset**](ActionAssets.md) | An asset type which contains a saved configuration of Action Maps, Actions and Bindings. You can specify one Action Asset in your project as the [project-wide actions](ProjectWideActions.md), which allows you to easily reference those actions in code by using [`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html). |
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
uid: input-system-contributing
|
||||
---
|
||||
# Contributing
|
||||
|
||||
The [full source code](https://github.com/Unity-Technologies/InputSystem) for the Input System is available on GitHub. This is also where most of the Input System's development happens.
|
||||
|
||||
>__Note__: This includes the full source code for the managed/C# part of the system. At this point, the native, platform-specific C++ backends are still closed-source and require a source code license.
|
||||
|
||||
## Reporting bugs
|
||||
|
||||
To report documentation problems, please use the feedback section at the bottom of the page containing the problem.
|
||||
|
||||
To report bugs related to the Input System Please follow Unity's standard [bug reporting guidelines](https://unity3d.com/unity/qa/bug-reporting). Don't forget to submit a Project that the developer who picks up your report can use to reproduce the issue. Be sure to mention that the bug is specific to the Input System package in the description, so it gets forwarded to the correct team at Unity.
|
||||
|
||||
## Discussion
|
||||
|
||||
To ask questions or discuss the Input System, see the [dedicated section on Unity's forum](https://forum.unity.com/forums/new-input-system.103/). This is also the best place to post feature requests.
|
||||
@@ -0,0 +1,285 @@
|
||||
---
|
||||
uid: input-system-controls
|
||||
---
|
||||
# Controls
|
||||
|
||||
* [Hierarchies](#control-hierarchies)
|
||||
* [Types](#control-types)
|
||||
* [Usages](#control-usages)
|
||||
* [Paths](#control-paths)
|
||||
* [State](#control-state)
|
||||
* [Actuation](#control-actuation)
|
||||
* [Noisy Controls](#noisy-controls)
|
||||
* [Synthetic Controls](#synthetic-controls)
|
||||
* [Performance Optimization](#performance-optimization)
|
||||
|
||||
An Input Control represents a source of values. These values can be of any structured or primitive type. The only requirement is that the type is [blittable](https://docs.microsoft.com/en-us/dotnet/framework/interop/blittable-and-non-blittable-types).
|
||||
|
||||
>__Note__: Controls are for input only. Output and configuration items on Input Devices are not represented as Controls.
|
||||
|
||||
Each Control is identified by a name ([`InputControl.name`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_name)) and can optionally have a display name ([`InputControl.displayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_displayName)) that differs from the Control name. For example, the right-hand face button closest to the touchpad on a PlayStation DualShock 4 controller has the control name "buttonWest" and the display name "Square".
|
||||
|
||||
Additionally, a Control might have one or more aliases which provide alternative names for the Control. You can access the aliases for a specific Control through its [`InputControl.aliases`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_aliases) property.
|
||||
|
||||
Finally, a Control might also have a short display name which can be accessed through the [`InputControl.shortDisplayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_shortDisplayName) property. For example, the short display name for the left mouse button is "LMB".
|
||||
|
||||
## Control hierarchies
|
||||
|
||||
Controls can form hierarchies. The root of a Control hierarchy is always a [Device](Devices.md).
|
||||
|
||||
The setup of hierarchies is exclusively controlled through [layouts](Layouts.md).
|
||||
|
||||
You can access the parent of a Control using [`InputControl.parent`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_parent), and its children using [`InputControl.children`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_children). To access the flattened hierarchy of all Controls on a Device, use [`InputDevice.allControls`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_allControls).
|
||||
|
||||
## Control types
|
||||
|
||||
All controls are based on the [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html) base class. Most concrete implementations are based on [`InputControl<TValue>`](../api/UnityEngine.InputSystem.InputControl-1.html).
|
||||
|
||||
The Input System provides the following types of controls out of the box:
|
||||
|
||||
|Control Type|Description|Example|
|
||||
|------------|-----------|-------|
|
||||
|[`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html)|A 1D floating-point axis.|[`Gamepad.leftStick.x`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html#UnityEngine_InputSystem_Controls_Vector2Control_x)|
|
||||
|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|A button expressed as a floating-point value. Whether the button can have a value other than 0 or 1 depends on the underlying representation. For example, gamepad trigger buttons can have values other than 0 and 1, but gamepad face buttons generally can't.|[`Mouse.leftButton`](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_leftButton)|
|
||||
|[`KeyControl`](../api/UnityEngine.InputSystem.Controls.KeyControl.html)|A specialized button that represents a key on a [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html). Keys have an associated [`keyCode`](../api/UnityEngine.InputSystem.Controls.KeyControl.html#UnityEngine_InputSystem_Controls_KeyControl_keyCode) and, unlike other types of Controls, change their display name in accordance to the currently active system-wide keyboard layout. See the [Keyboard](Keyboard.md) documentation for details.|[`Keyboard.aKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_aKey)|
|
||||
|[`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html)|A 2D floating-point vector.|[`Pointer.position`](../api/UnityEngine.InputSystem.Pointer.html#UnityEngine_InputSystem_Pointer_position)|
|
||||
|[`Vector3Control`](../api/UnityEngine.InputSystem.Controls.Vector3Control.html)|A 3D floating-point vector.|[`Accelerometer.acceleration`](../api/UnityEngine.InputSystem.Accelerometer.html#UnityEngine_InputSystem_Accelerometer_acceleration)|
|
||||
|[`QuaternionControl`](../api/UnityEngine.InputSystem.Controls.QuaternionControl.html)|A 3D rotation.|[`AttitudeSensor.attitude`](../api/UnityEngine.InputSystem.AttitudeSensor.html#UnityEngine_InputSystem_AttitudeSensor_attitude)|
|
||||
|[`IntegerControl`](../api/UnityEngine.InputSystem.Controls.IntegerControl.html)|An integer value.|[`Touchscreen.primaryTouch.touchId`](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId)|
|
||||
|[`StickControl`](../api/UnityEngine.InputSystem.Controls.StickControl.html)|A 2D stick control like the thumbsticks on gamepads or the stick control of a joystick.|[`Gamepad.rightStick`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightStick)|
|
||||
|[`DpadControl`](../api/UnityEngine.InputSystem.Controls.DpadControl.html)|A 4-way button control like the D-pad on gamepads or hatswitches on joysticks.|[`Gamepad.dpad`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_dpad)|
|
||||
|[`TouchControl`](../api/UnityEngine.InputSystem.Controls.TouchControl.html)|A control that represents all the properties of a touch on a [touch screen](Touch.md).|[`Touchscreen.primaryTouch`](../api/UnityEngine.InputSystem.Touchscreen.html#UnityEngine_InputSystem_Touchscreen_primaryTouch)|
|
||||
|
||||
You can browse the set of all registered control layouts in the [input debugger](Debugging.md#debugging-layouts).
|
||||
|
||||
## Control usages
|
||||
|
||||
A Control can have one or more associated usages. A usage is a string that denotes the Control's intended use. An example of a Control usage is `Submit`, which labels a Control that is commonly used to confirm a selection in the UI. On a gamepad, this usage is commonly found on the `buttonSouth` Control.
|
||||
|
||||
You can access a Control's usages using the [`InputControl.usages`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_usages) property.
|
||||
|
||||
Usages can be arbitrary strings. However, a certain set of usages is very commonly used and comes predefined in the API in the form of the [`CommonUsages`](../api/UnityEngine.InputSystem.CommonUsages.html) static class. Check out the [`CommonUsages` scripting API page](../api/UnityEngine.InputSystem.CommonUsages.html) for an overview.
|
||||
|
||||
## Control paths
|
||||
|
||||
>Example: `<Gamepad>/leftStick/x` means "X Control on left stick of gamepad".
|
||||
|
||||
The Input System can look up Controls using textual paths. [Bindings](ActionBindings.md) on Input Actions rely on this feature to identify the Control(s) they read input from. However, you can also use them for lookup directly on Controls and Devices, or to let the Input System search for Controls among all devices using [`InputSystem.FindControls`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_FindControls_System_String_).
|
||||
|
||||
```CSharp
|
||||
var gamepad = Gamepad.all[0];
|
||||
var leftStickX = gamepad["leftStick/x"];
|
||||
var submitButton = gamepad["{Submit}"];
|
||||
var allSubmitButtons = InputSystem.FindControls("*/{Submit}");
|
||||
```
|
||||
|
||||
Control paths resemble file system paths. Each path consists of one or more components separated by a forward slash:
|
||||
|
||||
component/component...
|
||||
|
||||
Each component uses a similar syntax made up of multiple fields. Each field is optional, but at least one field must be present. All fields are case-insensitive.
|
||||
|
||||
<layoutName>{usageName}controlName#(displayName)
|
||||
|
||||
The following table explains the use of each field:
|
||||
|
||||
|Field|Description|Example|
|
||||
|-----|-----------|-------|
|
||||
|`<layoutName>`|Requires the Control at the current level to be based on the given layout. The actual layout of the Control may be the same or a layout *based* on the given layout.|`<Gamepad>/buttonSouth`|
|
||||
|`{usageName}`|Works differently for Controls and Devices.<br><br>When used on a Device (the first component of a path), it requires the device to have the given usage. See [Device usages](Devices.md#device-usages) for more details.<br><br>For looking up a Control, the usage field is currently restricted to the path component immediately following the Device (the second component in the path). It finds the Control on the Device that has the given usage. The Control can be anywhere in the Control hierarchy of the Device.|Device:<br><br>`<XRController>{LeftHand}/trigger`<br><br>Control:<br><br>`<Gamepad>/{Submit}`|
|
||||
|`controlName`|Requires the Control at the current level to have the given name. Takes both "proper" names ([`InputControl.name`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_name)) and aliases ([`InputControl.aliases`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_aliases)) into account.<br><br>This field can also be a wildcard (`*`) to match any name.|`MyGamepad/buttonSouth`<br><br>`*/{PrimaryAction}` (match `PrimaryAction` usage on Devices with any name)|
|
||||
|`#(displayName)`|Requires the Control at the current level to have the given display name (i.e. [`InputControl.displayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_displayName)). The display name may contain whitespace and symbols.|`<Keyboard>/#(a)` (matches the key that generates the "a" character, if any, according to the current keyboard layout).<br><br>`<Gamepad>/#(Cross)`|
|
||||
|
||||
You can access the literal path of a given control via its [`InputControl.path`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_path) property.
|
||||
|
||||
If needed, you can manually parse a control path into its components using the [`InputControlPath.Parse(path)`](../api/UnityEngine.InputSystem.InputControlPath.html#UnityEngine_InputSystem_InputControlPath_Parse_System_String_) API.
|
||||
|
||||
```CSharp
|
||||
var parsed = InputControlPath.Parse("<XRController>{LeftHand}/trigger").ToArray();
|
||||
|
||||
Debug.Log(parsed.Length); // Prints 2.
|
||||
Debug.Log(parsed[0].layout); // Prints "XRController".
|
||||
Debug.Log(parsed[0].name); // Prints an empty string.
|
||||
Debug.Log(parsed[0].usages.First()); // Prints "LeftHand".
|
||||
Debug.Log(parsed[1].layout); // Prints null.
|
||||
Debug.Log(parsed[1].name); // Prints "trigger".
|
||||
```
|
||||
|
||||
## Control state
|
||||
|
||||
Each Control is connected to a block of memory that is considered the Control's "state". You can query the size, format, and location of this block of memory from a Control through the [`InputControl.stateBlock`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_stateBlock) property.
|
||||
|
||||
The state of Controls is stored in unmanaged memory that the Input System handles internally. All Devices added to the system share one block of unmanaged memory that contains the state of all the Controls on the Devices.
|
||||
|
||||
A Control's state might not be stored in the natural format for that Control. For example, the system often represents buttons as bitfields, and axis controls as 8-bit or 16-bit integer values. This format is determined by the combination of platform, hardware, and drivers. Each Control knows the format of its storage and how to translate the values as needed. The Input System uses [layouts](Layouts.md) to understand this representation.
|
||||
|
||||
You can access the current state of a Control through its [`ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) method.
|
||||
|
||||
```CSharp
|
||||
Gamepad.current.leftStick.x.ReadValue();
|
||||
```
|
||||
|
||||
Each type of Control has a specific type of values that it returns, regardless of how many different types of formats it supports for its state. You can access this value type through the [`InputControl.valueType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_valueType) property.
|
||||
|
||||
Reading a value from a Control might apply one or more value Processors. See documentation on [Processors](Processors.md) for more information.
|
||||
|
||||
[//]: # (#### Default State - TODO)
|
||||
|
||||
[//]: # (#### Reading State vs Reading Values - TODO)
|
||||
|
||||
#### Recording state history
|
||||
|
||||
You might want to access the history of value changes on a Control (for example, in order to compute exit velocity on a touch release).
|
||||
|
||||
To record state changes over time, you can use [`InputStateHistory`](../api/UnityEngine.InputSystem.LowLevel.InputStateHistory.html) or [`InputStateHistory<TValue>`](../api/UnityEngine.InputSystem.LowLevel.InputStateHistory-1.html). The latter restricts Controls to those of a specific value type, which in turn simplifies some of the API.
|
||||
|
||||
```CSharp
|
||||
// Create history that records Vector2 control value changes.
|
||||
// NOTE: You can also pass controls directly or use paths that match multiple
|
||||
// controls (e.g. "<Gamepad>/<Button>").
|
||||
// NOTE: The unconstrained InputStateHistory class can record changes on controls
|
||||
// of different value types.
|
||||
var history = new InputStateHistory<Vector2>("<Touchscreen>/primaryTouch/position");
|
||||
|
||||
// To start recording state changes of the controls to which the history
|
||||
// is attached, call StartRecording.
|
||||
history.StartRecording();
|
||||
|
||||
// To stop recording state changes, call StopRecording.
|
||||
history.StopRecording();
|
||||
|
||||
// Recorded history can be accessed like an array.
|
||||
for (var i = 0; i < history.Count; ++i)
|
||||
{
|
||||
// Each recorded value provides information about which control changed
|
||||
// value (in cases state from multiple controls is recorded concurrently
|
||||
// by the same InputStateHistory) and when it did so.
|
||||
|
||||
var time = history[i].time;
|
||||
var control = history[i].control;
|
||||
var value = history[i].ReadValue();
|
||||
}
|
||||
|
||||
// Recorded history can also be iterated over.
|
||||
foreach (var record in history)
|
||||
Debug.Log(record.ReadValue());
|
||||
Debug.Log(string.Join(",\n", history));
|
||||
|
||||
// You can also record state changes manually, which allows
|
||||
// storing arbitrary histories in InputStateHistory.
|
||||
// NOTE: This records a value change that didn't actually happen on the control.
|
||||
history.RecordStateChange(Touchscreen.current.primaryTouch.position,
|
||||
new Vector2(0.123f, 0.234f));
|
||||
|
||||
// State histories allocate unmanaged memory and need to be disposed.
|
||||
history.Dispose();
|
||||
```
|
||||
|
||||
For example, if you want to have the last 100 samples of the left stick on the gamepad available, you can use this code:
|
||||
|
||||
```CSharp
|
||||
var history = new InputStateHistory<Vector2>(Gamepad.current.leftStick);
|
||||
history.historyDepth = 100;
|
||||
history.StartRecording();
|
||||
```
|
||||
|
||||
## Control actuation
|
||||
|
||||
A Control is considered actuated when it has moved away from its default state in such a way that it affects the actual value of the Control. You can query whether a Control is currently actuated using [`IsActuated`](../api/UnityEngine.InputSystem.InputControlExtensions.html#UnityEngine_InputSystem_InputControlExtensions_IsActuated_UnityEngine_InputSystem_InputControl_System_Single_).
|
||||
|
||||
```CSharp
|
||||
// Check if leftStick is currently actuated.
|
||||
if (Gamepad.current.leftStick.IsActuated())
|
||||
Debug.Log("Left Stick is actuated");
|
||||
```
|
||||
|
||||
It can be useful to determine not just whether a Control is actuated at all, but also the amount by which it is actuated (that is, its magnitude). For example, for a [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) this would be the length of the vector, whereas for a button it is the raw, absolute floating-point value.
|
||||
|
||||
In general, the current magnitude of a Control is always >= 0. However, a Control might not have a meaningful magnitude, in which case it returns -1. Any negative value should be considered an invalid magnitude.
|
||||
|
||||
You can query the current amount of actuation using [`EvaluateMagnitude`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude).
|
||||
|
||||
```CSharp
|
||||
// Check if left stick is actuated more than a quarter of its motion range.
|
||||
if (Gamepad.current.leftStick.EvaluateMagnitude() > 0.25f)
|
||||
Debug.Log("Left Stick actuated past 25%");
|
||||
```
|
||||
|
||||
There are two mechanisms that most notably make use of Control actuation:
|
||||
|
||||
- [Interactive rebinding](ActionBindings.md#interactive-rebinding) (`InputActionRebindingExceptions.RebindOperation`) uses it to select between multiple suitable Controls to find the one that is actuated the most.
|
||||
- [Conflict resolution](ActionBindings.md#conflicting-inputs) between multiple Controls that are bound to the same action uses it to decide which Control gets to drive the action.
|
||||
|
||||
## Noisy Controls
|
||||
|
||||
The Input System can label a Control as "noisy". You can query this using the [`InputControl.noisy`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_noisy) property.
|
||||
|
||||
Noisy Controls are those that can change value without any actual or intentional user interaction required. A good example of this is a gravity sensor in a cellphone. Even if the cellphone is perfectly still, there are usually fluctuations in gravity readings. Another example are orientation readings from an HMD.
|
||||
|
||||
If a Control is marked as noisy, it means that:
|
||||
|
||||
1. The Control is not considered for [interactive rebinding](ActionBindings.md#interactive-rebinding). [`InputActionRebindingExceptions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) ignores the Control by default (you can bypass this using [`WithoutIgnoringNoisyControls`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithoutIgnoringNoisyControls)).
|
||||
2. If enabled in the Project Settings, the system performs additional event filtering, then calls [`InputDevice.MakeCurrent`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_MakeCurrent). If an input event for a Device contains no state change on a Control that is not marked noisy, then the Device will not be made current based on the event. This avoids, for example, a plugged in PS4 controller constantly making itself the current gamepad ([`Gamepad.current`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_current)) due to its sensors constantly feeding data into the system.
|
||||
3. When the application loses focus and Devices are [reset](Devices.md#device-resets) as a result, the state of noisy Controls will be preserved as is. This ensures that sensor readinds will remain at their last value rather than being reset to default values.
|
||||
|
||||
>**Note**: If any Control on a Device is noisy, the Device itself is flagged as noisy.
|
||||
|
||||
Parallel to the [`input state`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_currentStatePtr) and the [`default state`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_defaultStatePtr) that the Input System keeps for all Devices currently present, it also maintains a [`noise mask`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_noiseMaskPtr) in which only bits for state that is __not__ noise are set. This can be used to very efficiently mask out noise in input.
|
||||
|
||||
## Synthetic Controls
|
||||
|
||||
A synthetic Control is a Control that doesn't correspond to an actual physical control on a device (for example the `left`, `right`, `up`, and `down` child Controls on a [`StickControl`](../api/UnityEngine.InputSystem.Controls.StickControl.html)). These Controls synthesize input from other, actual physical Controls and present it in a different way (in this example, they allow you to treat the individual directions of a stick as buttons).
|
||||
|
||||
Whether a given Control is synthetic is indicated by its [`InputControl.synthetic`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_synthetic) property.
|
||||
|
||||
The system considers synthetic Controls for [interactive rebinding](ActionBindings.md#interactive-rebinding) but always favors non-synthetic Controls. If both a synthetic and a non-synthetic Control that are a potential match exist, the non-synthetic Control wins by default. This makes it possible to interactively bind to `<Gamepad>/leftStick/left`, for example, but also makes it possible to bind to `<Gamepad>/leftStickPress` without getting interference from the synthetic buttons on the stick.
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Avoiding defensive copies
|
||||
|
||||
Use [`InputControl<T>.value`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_value) instead of [`InputControl<T>.ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) to avoid creating a copy of the control state on every call, as the former returns the value as `ref readonly` while the latter always makes a copy. Note that this optimization only applies if the call site assigns the return value to a variable that has been declared 'ref readonly'. Otherwise a copy will be made as before. Additionally, be aware of defensive copies that can be allocated by the compiler when it is unable to determine that it can safely use the readonly reference i.e. if it can't determine that the reference won't be changed, it will create a defensive copy for you. For more details, see https://learn.microsoft.com/en-us/dotnet/csharp/write-safe-efficient-code#use-ref-readonly-return-statements.
|
||||
|
||||
|
||||
### Control Value Caching
|
||||
|
||||
When the `'USE_READ_VALUE_CACHING'` internal feature flag is set, the Input System will switch to an optimized path for reading control values. This path efficiently marks controls as 'stale' when they have been actuated. Subsequent calls to [`InputControl<T>.ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) will only apply control processing when there have been changes to that control or in case of control processing. Control processing in this case can mean any hard-coded processing that might exist on the control, such as with [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) which has built-in inversion, normalisation, scaling etc, or any processors that have been applied to the controls' [processor stack](Processors.md#processors-on-controls).
|
||||
> Note: Performance improvements **are currently not guaranteed** for all use cases. Even though this performance path marks controls as "stale" in an efficient way, it still has an overhead which can degrade performance in some cases.
|
||||
|
||||
A positive performance impact has been seen when:
|
||||
- Reading from controls that do not change frequently.
|
||||
- In case the controls change every frame, are being read and have actions bound to them as well, e.g. on a Gamepad, reading `leftStick`, `leftStick.x` and `leftStick.left` for example when there's a action with composite bindings setup.
|
||||
|
||||
On the other hand, it is likely to have a negative performance impact when:
|
||||
- No control reads are performed for a control, and there are a lot of changes for that particular control.
|
||||
- Reading from controls that change frequently that have no actions bound to those controls.
|
||||
|
||||
Moreover, this feature is not enabled by default as it can result in the following minor behavioural changes:
|
||||
* Some control processors use global state. Without cached value optimizations, it is possible to read the control value, change the global state, read the control value again, and get a new value due to the fact that the control processor runs on every call. With cached value optimizations, reading the control value will only ever return a new value if the physical control has been actuated. Changing the global state of a control processor will have no effect otherwise.
|
||||
* Writing to device state using low-level APIs like [`InputControl<T>.WriteValueIntoState`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_WriteValueIntoState__0_System_Void__) does not set the stale flag and subsequent calls to [`InputControl<T>.value`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_value) will not reflect those changes.
|
||||
* After changing properties on [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) the [`ApplyParameterChanges`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_ApplyParameterChanges) has to be called to invalidate cached value.
|
||||
|
||||
Processors that need to run on every read can set their respective caching policy to EvaluateOnEveryRead. That will disable caching on controls that are using such processor.
|
||||
|
||||
If there are any non-obvious inconsistencies, 'PARANOID_READ_VALUE_CACHING_CHECKS' internal feature flag can be enabled to compare cached and uncached value on every read and log an error if they don't match.
|
||||
|
||||
### Optimized control read value
|
||||
|
||||
When the `'USE_OPTIMIZED_CONTROLS'` internal feature flag is set, the Input System will use faster way to use state memory for some controls instances. This is very specific optimization and should be used with caution.
|
||||
|
||||
> __Please note__: This optimization has a performance impact on `PlayMode` as we do extra checks to ensure that the controls have the correct memory representation during development. Don't be alarmed if you see a performance drop in `PlayMode` when using this optimization as it's expected at this stage.
|
||||
|
||||
Most controls are flexible with regards to memory representation, like [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) can be one bit, multiple bits, a float, etc, or in [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) where x and y can have different memory representation.
|
||||
Yet for most controls there are common memory representation patterns, for example [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) are floats or single bytes. Or some [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) are two consequitive floats in memory.
|
||||
If a control matches a common representation we can bypass reading its children control and cast the memory directly to the common representation. For example if [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) is two consecutive floats in memory we can bypass reading `x` and `y` separately and just cast the state memory to `Vector2`.
|
||||
|
||||
> __Please note__: This optimization only works if the controls don't need any processing applied to them, such as `invert`, `clamp`, `normalize`, `scale` or any other processor. If any of these are applied to the control, **there won't be any optimization applied** and the control will be read as usual.
|
||||
|
||||
Also, [`InputControl.ApplyParameterChanges()`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_ApplyParameterChanges) **must be explicitly called** in specific changes to ensure [`InputControl.optimizedControlDataType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_optimizedControlDataType) is updated to the correct memory representation. Make sure to call it when:
|
||||
* Configuration changes after [`InputControl.FinishSetup()`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_FinishSetup_) is called.
|
||||
* Changing parameters such [`AxisControl.invert`](../api/UnityEngine.InputSystem.Controls.AxisControl.html#UnityEngine_InputSystem_Controls_AxisControl_invert), [`AxisControl.clamp`](../api/UnityEngine.InputSystem.Controls.AxisControl.html#UnityEngine_InputSystem_Controls_AxisControl_clamp), [`AxisControl.normalize`](../api/UnityEngine.InputSystem.Controls.AxisControl.html#UnityEngine_InputSystem_Controls_AxisControl_normalize), [`AxisControl.scale`](../api/UnityEngine.InputSystem.Controls.AxisControl.html#UnityEngine_InputSystem_Controls_AxisControl_scale) or changing processors. The memory representation needs to be recalculated after these changes so that we know that the control is not optimized anymore. Otherwise, the control will be read with wrong values.
|
||||
|
||||
The optimized controls work as follows:
|
||||
* A potential memory representation is set using [`InputControl.CalculateOptimizedControlDataType()`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_CalculateOptimizedControlDataType)
|
||||
* Its memory representation is stored in [`InputControl.optimizedControlDataType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_optimizedControlDataType)
|
||||
* Finally, [`ReadUnprocessedValueFromState`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValueFromState_) uses the optimized memory representation to decide if it should cast to memory directly instead of reading every children control on it's own to reconstruct the controls state.
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
uid: input-system-debugging
|
||||
---
|
||||
# Debugging
|
||||
|
||||
- [Debugging](#debugging)
|
||||
- [Input Debugger](#input-debugger)
|
||||
- [Debugging Devices](#debugging-devices)
|
||||
- [Debugging Actions](#debugging-actions)
|
||||
- [Debugging users and PlayerInput](#debugging-users-and-playerinput)
|
||||
- [Debugging layouts](#debugging-layouts)
|
||||
- [Debugging remotely](#debugging-remotely)
|
||||
- [Input visualizers](#input-visualizers)
|
||||
- [`InputControlVisualizer`](#inputcontrolvisualizer)
|
||||
- [`InputActionVisualizer`](#inputactionvisualizer)
|
||||
- [Device Simulator](#device-simulator)
|
||||
- [Unity Remote (iOS, Android)](#unity-remote)
|
||||
- [Other tips:](#other-tips)
|
||||
|
||||
When something isn't working as expected, the quickest way to troubleshoot what's wrong is the Input Debugger in the Unity Editor. The Input Debugger provides access to the activity of the Input System in both the Editor and the connected Players.
|
||||
|
||||
To open the Input Debugger, go to __Window > Analysis > Input Debugger__ from Unity's main menu.
|
||||
|
||||
## Input Debugger
|
||||
|
||||
|
||||
|
||||
The Input Debugger displays a tree breakdown of the state of the Input System.
|
||||
|
||||
|Item|Description|
|
||||
|----|-----------|
|
||||
|Devices|A list of all [Input Devices](Devices.md) that are currently in the system, and a list of unsupported/unrecognized Devices.|
|
||||
|Layouts|A list of all registered Control and Device layouts. This is the database of supported hardware, and information on how to represent a given piece of input hardware.|
|
||||
|Actions|Only visible in Play mode, and only if at least one [Action](Actions.md) is enabled.<br><br>A list of all currently enabled Actions, and the Controls they are bound to.<br><br>See [Debugging Actions](#debugging-actions).|
|
||||
|Users|Only visible when one or more `InputUser` instances exist. See documentation on [user management](UserManagement.md).<br><br>A list of all currently active users, along with their active Control Schemes and Devices, all their associated Actions, and the Controls these Actions are bound to.<br><br>Note that `PlayerInput` uses `InputUser` to run. When using `PlayerInput` components, each player has an entry in this list.<br><br>See [Debugging users and PlayerInput](#debugging-users-and-playerinput).|
|
||||
|Settings|The currently active Input System [settings](Settings.md).|
|
||||
|Metrics|Statistics about Input System resource usage.|
|
||||
|
||||
### Debugging Devices
|
||||
|
||||
In the Input Debugger window, navigate to the __Devices__ list and double-click any [Input Device](Devices.md). This opens a window that displays information about the Device, including real-time state information for its Controls.
|
||||
|
||||
|
||||
|
||||
The top of the Device window displays general information about the specific Device, such as name, manufacturer, and serial number.
|
||||
|
||||
The __Controls__ section lists the Device's Controls and their individual states. This is useful when debugging input issues, because you can verify whether the data that the Input System receives from the Input Device is what you expect it to be. There are two buttons at the top of this panel:
|
||||
|
||||
* __HID Descriptor__: Only displayed for devices that use the HID protocol to connect. This opens a window that displays the detailed [HID](HID.md) specifications for the Device and each of it's logical controls.
|
||||
|
||||
* __State__: Display the current state of the Device in a new window. This is identical to the information displayed in this view, but doesn't update in real time, so you can take a snapshot of input state data and take the time to inspect it as needed.
|
||||
|
||||
The __Events__ section lists all [input events](Events.md) generated by the Device. You can double-click any event in the list to inspect the full Device state at the time the event occurred. To get a side-by-side difference between the state of the Device at different points in time, select multiple events, right-click them, and click __Compare__ from the context menu.
|
||||
|
||||
### Debugging Actions
|
||||
|
||||
The Input Debugger window lists all enabled [Actions](Actions.md) in the __Actions__ list. This list only appears if at least one Action is active and the Editor is in Play mode. If an Action has actively bound Controls, you can click the arrow next to the Action to see a list of the Controls. This is useful to debug whether your Bindings correctly map to the Controls you want them to bind to. See documentation on [Binding resolution](ActionBindings.md#binding-resolution) for more information about how Unity maps Bindings to Controls.
|
||||
|
||||
>__Note__: Actions that belong to [`InputUsers`](UserManagement.md) don't appear here. They appear in the [__Users__](#debugging-users-and-playerinput) list instead.
|
||||
|
||||
### Debugging users and PlayerInput
|
||||
|
||||
When there are [`InputUser`](UserManagement.md) instances (if you use `PlayerInput`, each `PlayerInput` instance implicitly creates one), the Input Debugger's __Users__ list displays each instance along with its paired Devices and active Actions. The listed Devices and Actions work the same way as those displayed in the [__Devices__](#debugging-devices) and [__Actions__](#debugging-actions) lists in the debugging window.
|
||||
|
||||
|
||||
|
||||
### Debugging layouts
|
||||
|
||||
The [__Layouts__](Layouts.md) list in the Input Debugger window displays a breakdown of all registered [Control and Device layouts](Layouts.md). This is the database of supported hardware and the knowledge of how to represent a given piece of input hardware. It's useful when you want to [create a new Device mapping](HID.md#creating-a-custom-device-layout) and see how the Input System represents it.
|
||||
|
||||
|
||||
|
||||
### Debugging remotely
|
||||
|
||||
You can connect the Input Debugger to a Player that runs on a remote computer or device. This makes it possible to observe input activity from the Player in the Editor. This connection uses the `PlayerConnection` mechanism, which is the same one the Unity profiler uses to connect to a Player.
|
||||
|
||||
>__Note__: At the moment, debugging input in Players is restricted to seeing Devices and events from connected Players. There is no support for seeing other input-related data such as Actions and input users from Players.
|
||||
|
||||
To see remote Devices from built Players, open the Input Debugger window's __Remote Devices__ drop-down list. This list displays the remote Player instance you can connect to (if there are any). The same list appears in the Profiler and Console windows, and any connections are shared between those windows. If any Player(s) are connected, you can enable __Show remote devices__ in the same drop-down list. If Players are connected, and __Show remote devices__ is enabled, the [__Devices__](#debugging-devices) list in the Input Debugger window splits into a __Local__ section and a __Remote__ section. The __Remote__ section displays any Input Device from any connected Player, and lets you inspect Device state and events in real time, as if it were a local Device.
|
||||
|
||||
## Input visualizers
|
||||
|
||||
The Input System package comes with a __Visualizers__ sample, which provides various components which let you monitor the state of various Input System elements in real time using on-screen visualizers.
|
||||
|
||||
To install the sample, navigate to the Input System package in the Package Manager window (see [Installation](Installation.md)), and next to the __Visualizers__ sample, click __Import in project__.
|
||||
|
||||
The sample provides two visualizer components:
|
||||
|
||||
### `InputControlVisualizer`
|
||||
|
||||
Visualizes the current state of a single Control in real time. You can have multiple Control visualizers to visualize the state of multiple Controls. Check the `GamepadVisualizer`, `MouseVisualizer`, or `PenVisualizer` Scenes in the sample for examples.
|
||||
|
||||
|
||||
|
||||
### `InputActionVisualizer`
|
||||
|
||||
Visualizes the current state of a single Action in real time. You can have multiple Action visualizers to visualize the state of multiple Actions. This can also display the current value of the Action and the Control currently driving the Action, and track the state of [Interactions](Interactions.md) over time. Check the `SimpleControlsVisualizer` Scene in the sample for examples.
|
||||
|
||||
|
||||
|
||||
## Device Simulator
|
||||
|
||||
When Device Simulator window is in use, mouse and pen inputs on the simulated device screen are turned into touchscreen inputs. Device Simulator uses its own touchscreen device, which it creates and destroys together with the Device Simulator window.
|
||||
|
||||
To prevent conflicts between simulated touchscreen inputs and native mouse and pen inputs, Device Simulator disables all native mouse and pen devices.
|
||||
|
||||
## Unity Remote
|
||||
|
||||
The Unity Remote is an app available for iOS and Android which allows using a mobile device for input while running in the Unity Editor. You can find details about the app and how to install it in the [Unity manual](https://docs.unity3d.com/Manual/UnityRemote5.html).
|
||||
|
||||
If you would like to try out the Unity Remote app, you can [install](Installation.md#installing-samples) the "Unity Remote" sample that is provided with the Input System package.
|
||||
|
||||
>__Note__: Joysticks/gamepads are not yet supported over the Unity Remote. No joystick/gamepad input from the mobile device will come through in the editor.
|
||||
|
||||
>__Note__: This requires Unity 2021.2.18 or later.
|
||||
|
||||
When in play mode in the Editor and connected to the Unity Remote app, you will see a number of Devices have been added with the [`InputDevice.remote`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_remote) flag set to true:
|
||||
|
||||
- [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html)
|
||||
- [`Accelerometer`](../api/UnityEngine.InputSystem.Accelerometer.html)
|
||||
|
||||
If a gyro is present on the mobile device:
|
||||
|
||||
- [`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html)
|
||||
- [`AttitudeSensor`](../api/UnityEngine.InputSystem.AttitudeSensor.html)
|
||||
- [`LinearAccelerationSensor`](../api/UnityEngine.InputSystem.LinearAccelerationSensor.html)
|
||||
- [`GravitySensor`](../api/UnityEngine.InputSystem.GravitySensor.html)
|
||||
|
||||
These Devices can be used just like local Devices. They will receive input from the connected mobile device which in turn will receive the rendered output of the game running in the editor.
|
||||
|
||||
The [`Accelerometer`](../api/UnityEngine.InputSystem.Accelerometer.html) device will automatically be enabled and will not need you to call [`InputSystem.EnableDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_EnableDevice_UnityEngine_InputSystem_InputDevice_) explicitly. Setting the sampling frequency on the accelerometer from the Unity Remote using [`Sensor.samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency) has no effect.
|
||||
|
||||
The remaining sensors listed above will need to be explicitly enabled via [`InputSystem.EnableDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_EnableDevice_UnityEngine_InputSystem_InputDevice_) just like local sensors. Setting the sampling frequency on these sensors from the Unity Remote using [`Sensor.samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency) will be relayed to the device but note that setting the frequency on one of them will set it for all of them.
|
||||
|
||||
Touch coordinates from the device will be translated to the screen coordinates of the Game View inside the Editor.
|
||||
|
||||
## Other tips:
|
||||
|
||||
To record events flowing through the system, use this code:
|
||||
|
||||
```C#
|
||||
|
||||
// You can also provide a device ID to only
|
||||
// trace events for a specific device.
|
||||
var trace = new InputEventTrace();
|
||||
|
||||
trace.Enable();
|
||||
|
||||
var current = new InputEventPtr();
|
||||
while (trace.GetNextEvent(ref current))
|
||||
{
|
||||
Debug.Log("Got some event: " + current);
|
||||
}
|
||||
|
||||
// Also supports IEnumerable.
|
||||
foreach (var eventPtr in trace)
|
||||
Debug.Log("Got some event: " + eventPtr);
|
||||
|
||||
// Trace consumes unmanaged resources. Make sure you dispose it correctly to avoid memory leaks.
|
||||
trace.Dispose();
|
||||
|
||||
```
|
||||
|
||||
To see events as they're processed, use this code:
|
||||
|
||||
```C#
|
||||
|
||||
InputSystem.onEvent +=
|
||||
(eventPtr, device) =>
|
||||
{
|
||||
// Can handle events yourself, for example, and then stop them
|
||||
// from further processing by marking them as handled.
|
||||
eventPtr.handled = true;
|
||||
};
|
||||
|
||||
```
|
||||
@@ -0,0 +1,625 @@
|
||||
---
|
||||
uid: input-system-devices
|
||||
---
|
||||
# Devices
|
||||
|
||||
- [Devices](#devices)
|
||||
- [Device descriptions](#device-descriptions)
|
||||
- [Capabilities](#capabilities)
|
||||
- [Matching](#matching)
|
||||
- [Hijacking the matching process](#hijacking-the-matching-process)
|
||||
- [Device lifecycle](#device-lifecycle)
|
||||
- [Device creation](#device-creation)
|
||||
- [Device removal](#device-removal)
|
||||
- [Device resets](#device-resets)
|
||||
- [Device syncs](#device-syncs)
|
||||
- [Device enabling and disabling](#device-enabling-and-disabling)
|
||||
- [Background and focus change behavior](#background-and-focus-change-behavior)
|
||||
- [Domain reloads in the Editor](#domain-reloads-in-the-editor)
|
||||
- [Native Devices](#native-devices)
|
||||
- [Disconnected Devices](#disconnected-devices)
|
||||
- [Device IDs](#device-ids)
|
||||
- [Device usages](#device-usages)
|
||||
- [Device commands](#device-commands)
|
||||
- [Sending commands to Devices](#sending-commands-to-devices)
|
||||
- [Adding custom device Commands](#adding-custom-device-commands)
|
||||
- [Device state](#device-state)
|
||||
- [State changes](#state-changes)
|
||||
- [Monitoring state changes](#monitoring-state-changes)
|
||||
- [Synthesizing state](#synthesizing-state)
|
||||
- [Working with Devices](#working-with-devices)
|
||||
- [Monitoring Devices](#monitoring-devices)
|
||||
- [Adding and removing Devices](#adding-and-removing-devices)
|
||||
- [Creating custom Devices](#creating-custom-devices)
|
||||
- [Step 1: The state struct](#step-1-the-state-struct)
|
||||
- [Step 2: The Device class](#step-2-the-device-class)
|
||||
- [Step 3: The Update method](#step-3-the-update-method)
|
||||
- [Step 4: Device registration and creation](#step-4-device-registration-and-creation)
|
||||
- [Step 5: `current` and `all` (optional)](#step-5-current-and-all-optional)
|
||||
- [Step 6: Device Commands (Optional)](#step-6-device-commands-optional)
|
||||
|
||||
Physically, Input Devices represent devices attached to the computer, which a user can use to control the app. Logically, Input Devices are the top-level container for [Controls](Controls.md). The [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) class is itself a specialization of [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html). See [supported Devices](SupportedDevices.md) to see what kind of Devices the Input System currently supports.
|
||||
|
||||
To query the set of all currently present Devices, you can use [`InputSystem.devices`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_devices).
|
||||
|
||||
## Device descriptions
|
||||
|
||||
An [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) describes a Device. The Input System uses this primarily during the Device discovery process. When a new Device is reported (by the runtime or by the user), the report contains a Device description. Based on the description, the system then attempts to find a Device [layout](Layouts.md) that matches the description. This process is based on [Device matchers](#matching).
|
||||
|
||||
After a Device has been created, you can retrieve the description it was created from through the [`InputDevice.description`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_description) property.
|
||||
|
||||
Every description has a set of standard fields:
|
||||
|
||||
|Field|Description|
|
||||
|-----|-----------|
|
||||
|[`interfaceName`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_interfaceName)|Identifier for the interface/API that is making the Device available. In many cases, this corresponds to the name of the platform, but there are several more specific interfaces that are commonly used: [HID](https://www.usb.org/hid), [RawInput](https://docs.microsoft.com/en-us/windows/desktop/inputdev/raw-input), [XInput](https://docs.microsoft.com/en-us/windows/desktop/xinput/xinput-game-controller-apis-portal).<br>This field is required.|
|
||||
|[`deviceClass`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_deviceClass)|A broad categorization of the Device. For example, "Gamepad" or "Keyboard".|
|
||||
|[`product`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_product)|Name of the product as reported by the Device/driver itself.|
|
||||
|[`manufacturer`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_manufacturer)|Name of the manufacturer as reported by the Device/driver itself.|
|
||||
|[`version`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_version)|If available, provides the version of the driver or hardware for the Device.|
|
||||
|[`serial`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_serial)|If available, provides the serial number for the Device.|
|
||||
|[`capabilities`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_capabilities)|A string in JSON format that describes Device/interface-specific capabilities. See the [section on capabilities](#capabilities).|
|
||||
|
||||
### Capabilities
|
||||
|
||||
Aside from a number of standardized fields, such as `product` and `manufacturer`, a Device description can contain a [`capabilities`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_capabilities) string in JSON format. This string describes characteristics which help the Input System to interpret the data from a Device, and map it to Control representations. Not all Device interfaces report Device capabilities. Examples of interface-specific Device capabilities are [HID descriptors](HID.md). WebGL, Android, and Linux use similar mechanisms to report available Controls on connected gamepads.
|
||||
|
||||
### Matching
|
||||
|
||||
[`InputDeviceMatcher`](../api/UnityEngine.InputSystem.Layouts.InputDeviceMatcher.html) instances handle matching an [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) to a registered layout. Each matcher loosely functions as a kind of regular expression. Each field in the description can be independently matched with either a plain string or regular expression. Matching is not case-sensitive. For a matcher to apply, all of its individual expressions have to match.
|
||||
|
||||
To matchers to any layout, call [`InputSystem.RegisterLayoutMatcher`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterLayoutMatcher_System_String_UnityEngine_InputSystem_Layouts_InputDeviceMatcher_). You can also supply them when you register a layout.
|
||||
|
||||
```CSharp
|
||||
// Register a new layout and supply a matcher for it.
|
||||
InputSystem.RegisterLayoutMatcher<MyDevice>(
|
||||
matches: new InputDeviceMatcher()
|
||||
.WithInterface("HID")
|
||||
.WithProduct("MyDevice.*")
|
||||
.WithManufacturer("MyBrand");
|
||||
|
||||
// Register an alternate matcher for an already registered layout.
|
||||
InputSystem.RegisterLayoutMatcher<MyDevice>(
|
||||
new InputDeviceMatcher()
|
||||
.WithInterface("HID")
|
||||
|
||||
```
|
||||
|
||||
If multiple matchers are matching the same [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html), the Input System chooses the matcher that has the larger number of properties to match against.
|
||||
|
||||
#### Hijacking the matching process
|
||||
|
||||
You can overrule the internal matching process from outside to select a different layout for a Device than the system would normally choose. This also makes it possible to quickly build new layouts. To do this, add a custom handler to the [`InputSystem.onFindControlLayoutForDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onFindLayoutForDevice) event. If your handler returns a non-null layout string, then the Input System uses this layout.
|
||||
|
||||
### Device lifecycle
|
||||
|
||||
#### Device creation
|
||||
|
||||
Once the system has chosen a [layout](Layouts.md) for a device, it instantiates an [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) and populates it with [`InputControls`](../api/UnityEngine.InputSystem.InputControl.html) as the layout dictates. This process is internal and happens automatically.
|
||||
|
||||
>__Note__: You can't create valid [`InputDevices`](../api/UnityEngine.InputSystem.InputDevice.html) and [`InputControls`](../api/UnityEngine.InputSystem.InputControl.html) by manually instantiating them with `new`. To guide the creation process, you must use [layouts](Layouts.md).
|
||||
|
||||
After the Input System assembles the [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html), it calls [`FinishSetup`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_FinishSetup_) on each control of the device and on the device itself. Use this to finalize the setup of the Controls.
|
||||
|
||||
After an [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) is fully assembled, the Input System adds it to the system. As part of this process, the Input System calls [`MakeCurrent`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_MakeCurrent_) on the Device, and signals [`InputDeviceChange.Added`](../api/UnityEngine.InputSystem.InputDeviceChange.html#UnityEngine_InputSystem_InputDeviceChange_Added) on [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange). The Input System also calls [`InputDevice.OnAdded`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_OnAdded_).
|
||||
|
||||
Once added, the [`InputDevice.added`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_added) flag is set to true.
|
||||
|
||||
To add devices manually, you can call one of the `InputSystem.AddDevice` methods such as [`InputSystem.AddDevice(layout)`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_AddDevice_System_String_System_String_System_String_).
|
||||
|
||||
```CSharp
|
||||
// Add a gamepad. This bypasses the matching process and creates a device directly
|
||||
// with the Gamepad layout.
|
||||
InputSystem.AddDevice<Gamepad>();
|
||||
|
||||
// Add a device such that the matching process is employed:
|
||||
InputSystem.AddDevice(new InputDeviceDescription
|
||||
{
|
||||
interfaceName = "XInput",
|
||||
product = "Xbox Controller",
|
||||
});
|
||||
```
|
||||
|
||||
When a device is added, the Input System automatically issues a [sync request](../api/UnityEngine.InputSystem.LowLevel.RequestSyncCommand.html) on the device. This instructs the device to send an event representing its current state. Whether this request succeeds depends on the whether the given device supports the sync command.
|
||||
|
||||
#### Device removal
|
||||
|
||||
When a Device is disconnected, it is removed from the system. A notification appears for [`InputDeviceChange.Removed`](../api/UnityEngine.InputSystem.InputDeviceChange.html) (sent via [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange)) and the Devices are removed from the [`devices`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange) list. The system also calls [`InputDevice.OnRemoved`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_OnRemoved_).
|
||||
|
||||
The [`InputDevice.added`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_added) flag is reset to false in the process.
|
||||
|
||||
Note that Devices are not destroyed when removed. Device instances remain valid and you can still access them in code. However, trying to read values from the controls of these Devices leads to exceptions.
|
||||
|
||||
#### Device resets
|
||||
|
||||
Resetting a Device resets its Controls to their default state. You can do this manually using [`InputSystem.ResetDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_ResetDevice_UnityEngine_InputSystem_InputDevice_System_Boolean_):
|
||||
|
||||
```CSharp
|
||||
InputSystem.ResetDevice(Gamepad.current);
|
||||
```
|
||||
|
||||
There are two types of resets as determined by the second parameter to [`InputSystem.ResetDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_ResetDevice_UnityEngine_InputSystem_InputDevice_System_Boolean_):
|
||||
|
||||
|Type|Description|
|
||||
|----|-----------|
|
||||
|"Soft" Resets|This is the default. With this type, only controls that are *not* marked as [`dontReset`](Layouts.md#control-items) are reset to their default value. This excludes controls such as [`Pointer.position`](../api/UnityEngine.InputSystem.Pointer.html#UnityEngine_InputSystem_Pointer_position) from resets and thus prevents mouse positions resetting to `(0,0)`.|
|
||||
|"Hard" Resets|In this type, *all* controls are reset to their default value regardless of whether they have [`dontReset`](Layouts.md#control-items) set or not.|
|
||||
|
||||
Resetting Controls this way is visible on [Actions](Actions.md). If you reset a Device that is currently driving one or more Action, the Actions are cancelled. This cancellation is different from sending an event with default state. Whereas the latter may inadvertently [perform](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) Actions (e.g. a button that was pressed would not appear to have been released), a reset will force clean cancellation.
|
||||
|
||||
Resets may be triggered automatically by the Input System depending on [application focus](#background-and-focus-change-behavior).
|
||||
|
||||
#### Device syncs
|
||||
|
||||
A Device may be requested to send an event with its current state through [`RequestSyncCommand`](../api/UnityEngine.InputSystem.LowLevel.RequestSyncCommand.html). It depends on the platform and type of Device whether this is supported or not.
|
||||
|
||||
A synchronization request can be explicitly sent using [`InputSystem.TrySyncDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_TrySyncDevice_UnityEngine_InputSystem_InputDevice_). If the device supports sync requests, the method returns true and an [`InputEvent`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html) will have been queued on the device for processing in the next [update](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update_).
|
||||
|
||||
Synchronization requests are also automatically sent by the Input System in certain situations. See [Background and focus change behavior](#background-and-focus-change-behavior) for more details.
|
||||
|
||||
#### Device enabling and disabling
|
||||
|
||||
When a Device is added, the Input System sends it an initial [`QueryEnabledStateCommand`](../api/UnityEngine.InputSystem.LowLevel.QueryEnabledStateCommand.html) to find out whether the device is currently enabled or not. The result of this is reflected in the [`InputDevice.enabled`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_enabled) property.
|
||||
|
||||
When disabled, no events other than removal ([`DeviceRemoveEvent`](../api/UnityEngine.InputSystem.LowLevel.DeviceRemoveEvent.html)) and configuration change ([`DeviceConfigurationEvent`](../api/UnityEngine.InputSystem.LowLevel.DeviceConfigurationEvent.html)) events are processed for a Device, even if they are sent.
|
||||
|
||||
A Device can be manually disabled and re-enabled via [`InputSystem.DisableDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_DisableDevice_) and [`InputSystem.EnableDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_EnableDevice_) respectively.
|
||||
|
||||
Note that [sensors](Sensors.md) start in a disabled state by default, and you need to enable them in order for them to generate events.
|
||||
|
||||
The Input System may automatically disable and re-enable Devices in certain situations, as detailed in the [next section](#background-and-focus-change-behavior).
|
||||
|
||||
#### Background and focus change behavior
|
||||
|
||||
In general, input is tied to [application focus](https://docs.unity3d.com/ScriptReference/Application-isFocused.html). This means that Devices do not receive input while the application is not in the foreground and thus no [Actions](Actions.md) will receive input either. When the application comes back into focus, all devices will receive a [sync](#device-syncs) request to have them send their current state (which may have changed while the application was in the background) to the application. Devices that do not support sync requests will see a [soft reset](#device-resets) that resets all Controls not marked as [`dontReset`](Layouts.md#control-items) to their default state.
|
||||
|
||||
On platforms such as iOS and Android, that do not support running Unity applications in the background, this is the only supported behavior.
|
||||
|
||||
If the application is configured to run while in the background (that is, not having focus), input behavior can be selected from several options. This is supported in two scenarios:
|
||||
|
||||
* In Unity's [Player Settings](https://docs.unity3d.com/Manual/class-PlayerSettings.html) you can explicity enable `Run In Background` for specific players that support it (such as Windows or Mac standalone players). Note that in these players this setting is always enabled automatically in *development* players.
|
||||
* In the editor, application focus is tied to focus on the Game View. If no Game View is focused, the application is considered to be running in the background. However, while in play mode, the editor will *always* keep running the player loop regardless of focus on the Game View window. This means that in the editor, `Run In Background` is considered to always be enabled.
|
||||
|
||||
If the application is configured this way to keep running while in the background, the player loop and thus the Input System, too, will keep running even when the application does not have focus. What happens with respect to input then depends on two factors:
|
||||
|
||||
1. On the ability of individual devices to receive input while the application is not running in the foreground. This is only supported by a small subset of devices and platforms. VR devices ([`TrackedDevice`](../api/UnityEngine.InputSystem.TrackedDevice.html)) such as HMDs and VR controllers generally support this.<br><br>To find out whether a specific device supports this, you can query the [`InputDevice.canRunInBackground`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_canRunInBackground) property. This property can also be forced to true or false via a Device's [layout](Layouts.md#control-items).
|
||||
2. On two settings you can find in the project-wide [Input Settings](Settings.md). Specifically, [`InputSettings.backgroundBehavior`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_backgroundBehavior) and [`InputSettings.editorInputBehaviorInPlayMode`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_editorInputBehaviorInPlayMode). The table below shows a detailed breakdown of how input behaviors vary based on these two settings and in relation to the `Run In Background` player setting in Unity.
|
||||
|
||||
>__Note__: [`InputDevice.canRunInBackground`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_canRunInBackground) is overridden by the editor in certain situations (see table below). In general, the value of the property does not have to be the same between the editor and the player and depends on the specific platform and device.
|
||||
|
||||
The following table shows the full matrix of behaviors according to the [Input Settings](Settings.md) and whether the game is running in the editor or in the player.
|
||||
|
||||
|
||||
|
||||
#### Domain reloads in the Editor
|
||||
|
||||
The Editor reloads the C# application domain whenever it reloads and recompiles scripts, or when the Editor goes into Play mode. This requires the Input System to reinitialize itself after each domain reload. During this process, the Input System attempts to recreate devices that were instantiated before the domain reload. However, the state of each Device doesn't carry across, which means that Devices reset to their default state on domain reloads.
|
||||
|
||||
Note that layout registrations do not persist across domain reloads. Instead, the Input System relies on all registrations to become available as part of the initialization process (for example, by using `[InitializeOnLoad]` to run registration as part of the domain startup code in the Editor). This allows you to change registrations and layouts in script, and the change to immediately take effect after a domain reload.
|
||||
|
||||
## Native Devices
|
||||
|
||||
Devices that the [native backend](Architecture.md#native-backend) reports are considered native (as opposed to Devices created from script code). To identify these Devices, you can check the [`InputDevice.native`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_native) property.
|
||||
|
||||
The Input System remembers native Devices. For example, if the system has no matching layout when the Device is first reported, but a layout which matches the device is registered later, the system uses this layout to recreate the Device.
|
||||
|
||||
You can force the Input System to use your own [layout](Layouts.md) when the native backend discovers a specific Device, by describing the Device in the layout, like this:
|
||||
|
||||
```
|
||||
{
|
||||
"name" : "MyGamepad",
|
||||
"extend" : "Gamepad",
|
||||
"device" : {
|
||||
// All strings in here are regexs and case-insensitive.
|
||||
"product" : "MyController",
|
||||
"manufacturer" : "MyCompany"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note: You don't have to restart Unity in order for changes in your layout to take effect on native Devices. The Input System applies changes automatically on every domain reload, so you can just keep refining a layout and your Device is recreated with the most up-to-date version every time scripts are recompiled.
|
||||
|
||||
|
||||
### Disconnected Devices
|
||||
|
||||
If you want to get notified when Input Devices disconnect, subscribe to the [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange) event, and look for events of type [`InputDeviceChange.Disconnected`](../api/UnityEngine.InputSystem.InputDeviceChange.html).
|
||||
|
||||
The Input System keeps track of disconnected Devices in [`InputSystem.disconnectedDevices`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_disconnectedDevices). If one of these Devices reconnects later, the Input System can detect that the Device was connected before, and reuses its [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) instance. This allows the [`PlayerInputManager`](PlayerInputManager.md) to reassign the Device to the same [user](UserManagement.md) again.
|
||||
|
||||
## Device IDs
|
||||
|
||||
Each Device that is created receives a unique numeric ID. You can access this ID through [`InputDevice.deviceId`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId).
|
||||
|
||||
All IDs are only used once per Unity session.
|
||||
|
||||
## Device usages
|
||||
|
||||
Like any [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html), a Device can have usages associated with it. You can query usages with the [`usages`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_usages) property, and use[`InputSystem.SetDeviceUsage()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_SetDeviceUsage_UnityEngine_InputSystem_InputDevice_System_String_) to set them. Usages can be arbitrary strings with arbitrary meanings. One common case where the Input System assigns Devices usages is the handedness of XR controllers, which are tagged with the "LeftHand" or "RightHand" usages.
|
||||
|
||||
## Device commands
|
||||
|
||||
While input [events](Events.md) deliver data from a Device, commands send data back to the Device. The Input System uses these to retrieve specific information from the Device, to trigger functions on the Device (such as rumble effects), and for a variety of other needs.
|
||||
|
||||
### Sending commands to Devices
|
||||
|
||||
The Input System sends commands to the Device through [`InputDevice.ExecuteCommand<TCommand>`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_ExecuteCommand__1___0__). To monitor Device commands, use [`InputSystem.onDeviceCommand`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceCommand).
|
||||
|
||||
Each Device command implements the [`IInputDeviceCommandInfo`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html) interface, which only requires the [`typeStatic`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html#UnityEngine_InputSystem_LowLevel_IInputDeviceCommandInfo_typeStatic) property to identify the type of the command. The native implementation of the Device should then understand how to handle that command. One common case is the `"HIDO"` command type which is used to send [HID output reports](HID.md#hid-output) to HIDs.
|
||||
|
||||
### Adding custom device Commands
|
||||
|
||||
To create custom Device commands (for example, to support some functionality for a specific HID), create a `struct` that contains all the data to be sent to the Device, and add a [`typeStatic`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html#UnityEngine_InputSystem_LowLevel_IInputDeviceCommandInfo_typeStatic) property to make that struct implement the [`IInputDeviceCommandInfo`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html) interface. To send data to a HID, this property should return `"HIDO"`.
|
||||
|
||||
You can then create an instance of this struct and populate all its fields, then use [`InputDevice.ExecuteCommand<TCommand>`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_ExecuteCommand__1___0__) to send it to the Device. The data layout of the struct must match the native representation of the data as the device interprets it.
|
||||
|
||||
## Device state
|
||||
|
||||
Like any other type of [Control](Controls.md#control-state), each Device has a block of memory allocated to it which stores the state of all the Controls associated with the Device.
|
||||
|
||||
### State changes
|
||||
|
||||
State changes are usually initiated through [state events](Events.md#state-events) from the native backend, but you can use [`InputControl<>.WriteValueIntoState()`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_WriteValueIntoState__0_System_Void__) to manually overwrite the state of any Control.
|
||||
|
||||
#### Monitoring state changes
|
||||
|
||||
You can use [`InputState.AddChangeMonitor()`](../api/UnityEngine.InputSystem.LowLevel.InputState.html#UnityEngine_InputSystem_LowLevel_InputState_AddChangeMonitor_UnityEngine_InputSystem_InputControl_System_Action_UnityEngine_InputSystem_InputControl_System_Double_UnityEngine_InputSystem_LowLevel_InputEventPtr_System_Int64__System_Int32_System_Action_UnityEngine_InputSystem_InputControl_System_Double_System_Int64_System_Int32__) to register a callback to be called whenever the state of a Control changes. The Input System uses the same mechanism to implement [input Actions](Actions.md).
|
||||
|
||||
#### Synthesizing state
|
||||
|
||||
The Input System can synthesize a new state from an existing state. An example of such a synthesized state is the [`press`](../api/UnityEngine.InputSystem.Pointer.html#UnityEngine_InputSystem_Pointer_press) button Control that [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) inherits from [`Pointer`](../api/UnityEngine.InputSystem.Pointer.html). Unlike a mouse, which has a physical button, for [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) this is a [synthetic Control](Controls.md#synthetic-controls) that doesn't correspond to actual data coming in from the Device backend. Instead, the Input System considers the button to be pressed if any touch is currently ongoing, and released otherwise.
|
||||
|
||||
To do this, the Input System uses [`InputState.Change`](../api/UnityEngine.InputSystem.LowLevel.InputState.html#UnityEngine_InputSystem_LowLevel_InputState_Change__1_UnityEngine_InputSystem_InputControl___0_UnityEngine_InputSystem_LowLevel_InputUpdateType_UnityEngine_InputSystem_LowLevel_InputEventPtr_), which allows feeding arbitrary state changes into the system without having to run them through the input event queue. The Input System incorporates state changes directly and synchronously. State change [monitors](#monitoring-state-changes) still trigger as expected.
|
||||
|
||||
## Working with Devices
|
||||
|
||||
### Monitoring Devices
|
||||
|
||||
To be notified when new Devices are added or existing Devices are removed, use [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange).
|
||||
|
||||
```CSharp
|
||||
InputSystem.onDeviceChange +=
|
||||
(device, change) =>
|
||||
{
|
||||
switch (change)
|
||||
{
|
||||
case InputDeviceChange.Added:
|
||||
// New Device.
|
||||
break;
|
||||
case InputDeviceChange.Disconnected:
|
||||
// Device got unplugged.
|
||||
break;
|
||||
case InputDeviceChange.Connected:
|
||||
// Plugged back in.
|
||||
break;
|
||||
case InputDeviceChange.Removed:
|
||||
// Remove from Input System entirely; by default, Devices stay in the system once discovered.
|
||||
break;
|
||||
default:
|
||||
// See InputDeviceChange reference for other event types.
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange) delivers notifications for other device-related changes as well. See the [`InputDeviceChange` enum](../api/UnityEngine.InputSystem.InputDeviceChange.html) for more information.
|
||||
|
||||
### Adding and removing Devices
|
||||
|
||||
To manually add and remove Devices through the API, use [`InputSystem.AddDevice()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_AddDevice_UnityEngine_InputSystem_InputDevice_) and [`InputSystem.RemoveDevice()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RemoveDevice_UnityEngine_InputSystem_InputDevice_).
|
||||
|
||||
This allows you to create your own Devices, which can be useful for testing purposes, or for creating virtual Input Devices which synthesize input from other events. As an example, see the [on-screen Controls](OnScreen.md) that the Input System provides. The Input Devices used for on-screen Controls are created entirely in code and have no [native representation](#native-devices).
|
||||
|
||||
### Creating custom Devices
|
||||
|
||||
>__Note__: This example deals only with Devices that have fixed layouts (that is, you know the specific model or models that you want to implement). This is different from an interface such as HID, where Devices can describe themselves through the interface and take on a wide variety of forms. A fixed Device layout can't cover self-describing Devices, so you need to use a [layout builder](Layouts.md#generated-layouts) to build Device layouts from information you obtain at runtime.
|
||||
|
||||
There are two main situations in which you might need to create a custom Device:
|
||||
|
||||
1. You have an existing API that generates input, and which you want to reflect into the Input System.
|
||||
2. You have an HID that the Input System ignores, or that the Input system auto-generates a layout for that doesn't work well enough for your needs.
|
||||
|
||||
For the second scenario, see [Overriding the HID Fallback](HID.md#creating-a-custom-device-layout).
|
||||
|
||||
The steps below deal with the first scenario, where you want to create a new Input Device entirely from scratch and provide input to it from a third-party API.
|
||||
|
||||
#### Step 1: The state struct
|
||||
|
||||
The first step is to create a C# `struct` that represents the form in which the system receives and stores input, and also describes the `InputControl` instances that the Input System must create for the Device in order to retrieve its state.
|
||||
|
||||
```CSharp
|
||||
// A "state struct" describes the memory format that a Device uses. Each Device can
|
||||
// receive and store memory in its custom format. InputControls then connect to
|
||||
// the individual pieces of memory and read out values from them.
|
||||
//
|
||||
// If it's important for the memory format to match 1:1 at the binary level
|
||||
// to an external representation, it's generally advisable to use
|
||||
// LayoutLind.Explicit.
|
||||
[StructLayout(LayoutKind.Explicit, Size = 32)]
|
||||
public struct MyDeviceState : IInputStateTypeInfo
|
||||
{
|
||||
// You must tag every state with a FourCC code for type
|
||||
// checking. The characters can be anything. Choose something that allows
|
||||
// you to easily recognize memory that belongs to your own Device.
|
||||
public FourCC format => new FourCC('M', 'Y', 'D', 'V');
|
||||
|
||||
// InputControlAttributes on fields tell the Input System to create Controls
|
||||
// for the public fields found in the struct.
|
||||
|
||||
// Assume a 16bit field of buttons. Create one button that is tied to
|
||||
// bit #3 (zero-based). Note that buttons don't need to be stored as bits.
|
||||
// They can also be stored as floats or shorts, for example. The
|
||||
// InputControlAttribute.format property determines which format the
|
||||
// data is stored in. If omitted, the system generally infers it from the value
|
||||
// type of the field.
|
||||
[InputControl(name = "button", layout = "Button", bit = 3)]
|
||||
public ushort buttons;
|
||||
|
||||
// Create a floating-point axis. If a name is not supplied, it is taken
|
||||
// from the field.
|
||||
[InputControl(layout = "Axis")]
|
||||
public short axis;
|
||||
}
|
||||
```
|
||||
|
||||
The Input System's layout mechanism uses [`InputControlAttribute`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html) annotations to add Controls to the layout of your Device. For details, see the [layout system](Layouts.md) documentation.
|
||||
|
||||
With the state struct in place, you now have a way to send input data to the Input System and store it there. The next thing you need is an [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) that uses your custom state struct and represents your custom Device.
|
||||
|
||||
#### Step 2: The Device class
|
||||
|
||||
Next, you need a class derived from one of the [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) base classes. You can either base your Device directly on [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html), or you can pick a more specific Device type, like [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html).
|
||||
|
||||
This example assumes that your Device doesn't fit into any of the existing Device classes, so it derives directly from [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html).
|
||||
|
||||
```CSharp
|
||||
// InputControlLayoutAttribute attribute is only necessary if you want
|
||||
// to override the default behavior that occurs when you register your Device
|
||||
// as a layout.
|
||||
// The most common use of InputControlLayoutAttribute is to direct the system
|
||||
// to a custom "state struct" through the `stateType` property. See below for details.
|
||||
[InputControlLayout(displayName = "My Device", stateType = typeof(MyDeviceState))]
|
||||
public class MyDevice : InputDevice
|
||||
{
|
||||
// In the state struct, you added two Controls that you now want to
|
||||
// surface on the Device, for convenience. The Controls
|
||||
// get added to the Device either way. When you expose them as properties,
|
||||
// it is easier to get to the Controls in code.
|
||||
|
||||
public ButtonControl button { get; private set; }
|
||||
public AxisControl axis { get; private set; }
|
||||
|
||||
// The Input System calls this method after it constructs the Device,
|
||||
// but before it adds the device to the system. Do any last-minute setup
|
||||
// here.
|
||||
protected override void FinishSetup()
|
||||
{
|
||||
base.FinishSetup();
|
||||
|
||||
// NOTE: The Input System creates the Controls automatically.
|
||||
// This is why don't do `new` here but rather just look
|
||||
// the Controls up.
|
||||
button = GetChildControl<ButtonControl>("button");
|
||||
axis = GetChildControl<AxisControl>("axis");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 3: The Update method
|
||||
|
||||
You now have a Device in place along with its associated state format. You can call the following method to create a fully set-up Device with your two Controls on it:
|
||||
|
||||
```CSharp
|
||||
InputSystem.AddDevice<MyDevice>();
|
||||
```
|
||||
|
||||
However, this Device doesn't receive input yet, because you haven't added any code that generates input. To do that, you can use [`InputSystem.QueueStateEvent`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_QueueStateEvent__1_UnityEngine_InputSystem_InputDevice___0_System_Double_) or [`InputSystem.QueueDeltaStateEvent`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_QueueDeltaStateEvent__1_UnityEngine_InputSystem_InputControl___0_System_Double_) from anywhere, including from a thread. The following example uses [`IInputUpdateCallbackReceiver`](../api/UnityEngine.InputSystem.LowLevel.IInputUpdateCallbackReceiver.html), which, when implemented by any [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html), adds an [`OnUpdate()`](../api/UnityEngine.InputSystem.LowLevel.IInputUpdateCallbackReceiver.html#UnityEngine_InputSystem_LowLevel_IInputUpdateCallbackReceiver_OnUpdate) method that automatically gets called during [`InputSystem.onBeforeUpdate`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onBeforeUpdate) and provides input events to the current input update.
|
||||
|
||||
>__Note__: If you already have a place where input for your device becomes available, you can skip this step and queue input events from there instead of using [`IInputUpdateCallbackReceiver`](../api/UnityEngine.InputSystem.LowLevel.IInputUpdateCallbackReceiver.html).
|
||||
|
||||
```CSharp
|
||||
public class MyDevice : InputDevice, IInputUpdateCallbackReceiver
|
||||
{
|
||||
//...
|
||||
|
||||
public void OnUpdate()
|
||||
{
|
||||
// In practice, this would read out data from an external
|
||||
// API. This example uses some empty input.
|
||||
var state = new MyDeviceState();
|
||||
InputSystem.QueueStateEvent(this, state);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 4: Device registration and creation
|
||||
|
||||
You now have a functioning device, but you haven't registered it (added it to the system) yet. This means you can't see the device when, for example, you create bindings in the [Action editor](ActionAssets.md#editing-input-action-assets).
|
||||
|
||||
You can register your device type with the system from within the code that runs automatically as part of Unity's startup. To do so, modify the definition of `MyDevice` like so:
|
||||
|
||||
```CSharp
|
||||
// Add the InitializeOnLoad attribute to automatically run the static
|
||||
// constructor of the class after each C# domain load.
|
||||
#if UNITY_EDITOR
|
||||
[InitializeOnLoad]
|
||||
#endif
|
||||
public class MyDevice : InputDevice, IInputUpdateCallbackReceiver
|
||||
{
|
||||
//...
|
||||
|
||||
static MyDevice()
|
||||
{
|
||||
// RegisterLayout() adds a "Control layout" to the system.
|
||||
// These can be layouts for individual Controls (like sticks)
|
||||
// or layouts for entire Devices (which are themselves
|
||||
// Controls) like in our case.
|
||||
InputSystem.RegisterLayout<MyDevice>();
|
||||
}
|
||||
|
||||
// You still need a way to trigger execution of the static constructor
|
||||
// in the Player. To do this, you can add the RuntimeInitializeOnLoadMethod
|
||||
// to an empty method.
|
||||
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
|
||||
private static void InitializeInPlayer() {}
|
||||
}
|
||||
```
|
||||
|
||||
This registers the Device type with the system and makes it available in the Control picker. However, you still need a way to add an instance of the Device when it is connected.
|
||||
|
||||
In theory, you could call [`InputSystem.AddDevice<MyDevice>()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_AddDevice__1_System_String_) somewhere, but in a real-world setup you likely have to correlate the Input Devices you create with their identities in the third-party API.
|
||||
|
||||
It might be tempting to do something like this:
|
||||
|
||||
```CSharp
|
||||
public class MyDevice : InputDevice, IInputUpdateCallbackReceiver
|
||||
{
|
||||
//...
|
||||
|
||||
// This does NOT work correctly.
|
||||
public ThirdPartyAPI.DeviceId externalId { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
and then set that on the Device after calling [`AddDevice<MyDevice>`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_AddDevice__1_System_String_). However, this doesn't work as expected in the Editor, because the Input System requires Devices to be created solely from their [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) in combination with the chosen layout (and layout variant). In addition, the system supports a fixed set of mutable per-device properties such as device usages (that is, [`InputSystem.SetDeviceUsage()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_SetDeviceUsage_UnityEngine_InputSystem_InputDevice_System_String_) and related methods). This allows the system to easily recreate Devices after domain reloads in the Editor, as well as to create replicas of remote Devices when connecting to a Player. To comply with this requirement, you must cast that information provided by the third-party API into an [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) and then use an [`InputDeviceMatcher`](../api/UnityEngine.InputSystem.Layouts.InputDeviceMatcher.html) to match the description to our custom `MyDevice` layout.
|
||||
|
||||
This example assumes that the third-party API has two callbacks, like this:
|
||||
|
||||
```CSharp
|
||||
public static ThirdPartyAPI
|
||||
{
|
||||
// This example assumes that the argument is a string that
|
||||
// contains the name of the Device, and that no two Devices
|
||||
// have the same name in the external API.
|
||||
public static Action<string> deviceAdded;
|
||||
public static Action<string> deviceRemoved;
|
||||
}
|
||||
```
|
||||
|
||||
You can hook into those callbacks and create and destroy devices in response.
|
||||
|
||||
```CSharp
|
||||
// This example uses a MonoBehaviour with [ExecuteInEditMode]
|
||||
// on it to run the setup code. You can do this many other ways.
|
||||
[ExecuteInEditMode]
|
||||
public class MyDeviceSupport : MonoBehaviour
|
||||
{
|
||||
protected void OnEnable()
|
||||
{
|
||||
ThirdPartyAPI.deviceAdded += OnDeviceAdded;
|
||||
ThirdPartyAPI.deviceRemoved += OnDeviceRemoved;
|
||||
}
|
||||
|
||||
protected void OnDisable()
|
||||
{
|
||||
ThirdPartyAPI.deviceAdded -= OnDeviceAdded;
|
||||
ThirdPartyAPI.deviceRemoved -= OnDeviceRemoved;
|
||||
}
|
||||
|
||||
private void OnDeviceAdded(string name)
|
||||
{
|
||||
// Feed a description of the Device into the system. In response, the
|
||||
// system matches it to the layouts it has and creates a Device.
|
||||
InputSystem.AddDevice(
|
||||
new InputDeviceDescription
|
||||
{
|
||||
interfaceName = "ThirdPartyAPI",
|
||||
product = name
|
||||
});
|
||||
}
|
||||
|
||||
private void OnDeviceRemoved(string name)
|
||||
{
|
||||
var device = InputSystem.devices.FirstOrDefault(
|
||||
x => x.description == new InputDeviceDescription
|
||||
{
|
||||
interfaceName = "ThirdPartyAPI",
|
||||
product = name,
|
||||
});
|
||||
|
||||
if (device != null)
|
||||
InputSystem.RemoveDevice(device);
|
||||
}
|
||||
|
||||
// Move the registration of MyDevice from the
|
||||
// static constructor to here, and change the
|
||||
// registration to also supply a matcher.
|
||||
protected void Awake()
|
||||
{
|
||||
// Add a match that catches any Input Device that reports its
|
||||
// interface as "ThirdPartyAPI".
|
||||
InputSystem.RegisterLayout<MyDevice>(
|
||||
matches: new InputDeviceMatcher()
|
||||
.WithInterface("ThirdPartyAPI"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 5: `current` and `all` (optional)
|
||||
|
||||
For convenience, you can quickly access the last used device of a given type, or list all devices of a specific type. To do this, add support for a `current` and for an `all` getter to the API of `MyDevice`.
|
||||
|
||||
```CSharp
|
||||
public class MyDevice : InputDevice, IInputCallbackReceiver
|
||||
{
|
||||
//...
|
||||
|
||||
public static MyDevice current { get; private set; }
|
||||
|
||||
public static IReadOnlyList<MyDevice> all => s_AllMyDevices;
|
||||
private static List<MyDevice> s_AllMyDevices = new List<MyDevice>();
|
||||
|
||||
public override void MakeCurrent()
|
||||
{
|
||||
base.MakeCurrent();
|
||||
current = this;
|
||||
}
|
||||
|
||||
protected override void OnAdded()
|
||||
{
|
||||
base.OnAdded();
|
||||
s_AllMyDevices.Add(this);
|
||||
}
|
||||
|
||||
protected override void OnRemoved()
|
||||
{
|
||||
base.OnRemoved();
|
||||
s_AllMyDevices.Remove(this);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 6: Device Commands (Optional)
|
||||
|
||||
A final, but optional, step is to add support for Device commands. A "device command" is that opposite of input. In other words, it consists of data traveling __to__ the input device, which might also return data as part of the operation (much like a function call). You can use this to communicate with the backend of the device in order to query configuration, or to initiate effects such as haptics. At the moment there isn't a proper interface available for this, however there are still some scenarios that can be solved with the current interfaces.
|
||||
|
||||
E.g. the following shows, when implementing a non-hardware-backed device (simulated device), how to simulate hardware reporting that the device can be run in the background and supports sync commands. This is useful to prevent the device from cancelling Actions when application focus is lost and restored. For more info see [Device syncs](#device-syncs)
|
||||
|
||||
```CSharp
|
||||
public class MyDevice : InputDevice, IInputCallbackReceiver
|
||||
{
|
||||
//...
|
||||
|
||||
protected override unsafe long ExecuteCommand(InputDeviceCommand* commandPtr)
|
||||
{
|
||||
var type = commandPtr->type;
|
||||
if (type == RequestSyncCommand.Type)
|
||||
{
|
||||
// Report that the device supports the sync command and has handled it.
|
||||
// This will prevent device reset during focus changes.
|
||||
result = InputDeviceCommand.GenericSuccess;
|
||||
return true;
|
||||
}
|
||||
|
||||
if (type == QueryCanRunInBackground.Type)
|
||||
{
|
||||
// Notify that the device supports running in the background.
|
||||
((QueryCanRunInBackground*)commandPtr)->canRunInBackground = true;
|
||||
result = InputDeviceCommand.GenericSuccess;
|
||||
return true;
|
||||
}
|
||||
|
||||
result = default;
|
||||
return false;
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"folders": [
|
||||
{
|
||||
"path": "."
|
||||
}
|
||||
],
|
||||
"settings": {
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
uid: input-system-editor-features
|
||||
---
|
||||
# Input System Editor Features
|
||||
|
||||
This section describes how the Input System integrates with the Unity Editor, which allows you to read input in edit mode, debug input values, and set up automated input tests.
|
||||
|
||||
### [Using Input in the Editor](UseInEditor.md)
|
||||
|
||||
Unlike Unity's old Input Manager, the Input System package allows you to read input from within [Editor window code](https://docs.unity3d.com/Manual/editor-EditorWindows.html) as well. ([Read more](UseInEditor.md))
|
||||
|
||||
### [The Input Debugger](Debugging.md)
|
||||
|
||||
When something isn't working as expected, the quickest way to troubleshoot what's wrong is the Input Debugger in the Unity Editor. The Input Debugger provides access to the activity of the Input System in both the Editor and the connected Players. ([Read more](Debugging.md))
|
||||
|
||||
### [Automated Input Testing](Testing.md)
|
||||
|
||||
The Input System has built-in support for writing automated input tests. You can drive input entirely from code, without any dependencies on platform backends and physical hardware devices. The automated input tests you write consider the generated input to be the same as input generated at runtime by actual platform code. ([Read more](Testing.md))
|
||||
@@ -0,0 +1,328 @@
|
||||
---
|
||||
uid: input-system-events
|
||||
---
|
||||
# Input events
|
||||
|
||||
* [Types of events](#types-of-events)
|
||||
* [State events](#state-events)
|
||||
* [Device events](#device-events)
|
||||
* [Text events](#text-events)
|
||||
* [Working with events](#working-with-events)
|
||||
* [Listening to events](#listening-to-events)
|
||||
* [Reading state events](#reading-state-events)
|
||||
* [Creating events](#creating-events)
|
||||
* [Capturing events](#capturing-events)
|
||||
* [Processing events](#processing-events)
|
||||
* [Merging of events](#merging-of-events)
|
||||
|
||||
The Input System is event-driven. All input is delivered as events, and you can generate custom input by injecting events. You can also observe all source input by listening in on the events flowing through the system.
|
||||
|
||||
>__Note__: Events are an advanced, mostly internal feature of the Input System. Knowledge of the event system is mostly useful if you want to support custom Devices, or change the behavior of existing Devices.
|
||||
|
||||
Input events are a low-level mechanism. Usually, you don't need to deal with events if all you want to do is receive input for your app. Events are stored in unmanaged memory buffers and not converted to C# heap objects. The Input System provides wrapper APIs, but unsafe code is required for more involved event manipulations.
|
||||
|
||||
Note that there are no routing mechanism. The runtime delivers events straight to the Input System, which then incorporates them directly into the Device state.
|
||||
|
||||
Input events are represented by the [`InputEvent`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html) struct. Each event has a set of common properties:
|
||||
|
||||
|Property|Description|
|
||||
|--------|-----------|
|
||||
|[`type`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_type)|[`FourCC`](../api/UnityEngine.InputSystem.Utilities.FourCC.html) code that indicates what type of event it is.|
|
||||
|[`eventId`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_eventId)|Unique numeric ID of the event.|
|
||||
|[`time`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_time)|Timestamp of when the event was generated. This is on the same timeline as [`Time.realtimeSinceStartup`](https://docs.unity3d.com/ScriptReference/Time-realtimeSinceStartup.html).|
|
||||
|[`deviceId`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_deviceId)|ID of the Device that the event targets.|
|
||||
|[`sizeInBytes`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_sizeInBytes)|Total size of the event in bytes.|
|
||||
|
||||
You can observe the events received for a specific input device in the [input debugger](Debugging.md#debugging-devices).
|
||||
|
||||
## Types of events
|
||||
|
||||
### State events
|
||||
|
||||
A state event contains the input state for a Device. The Input System uses these events to feed new input to Devices.
|
||||
|
||||
There are two types of state events:
|
||||
|
||||
* [`StateEvent`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html) (`'STAT'`)
|
||||
* [`DeltaStateEvent`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html) (`'DLTA'`)
|
||||
|
||||
[`StateEvent`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html) contains a full snapshot of the entire state of a Device in the format specific to that Device. The [`stateFormat`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html#UnityEngine_InputSystem_LowLevel_StateEvent_stateFormat) field identifies the type of the data in the event. You can access the raw data using the [`state`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html#UnityEngine_InputSystem_LowLevel_StateEvent_state) pointer and [`stateSizeInBytes`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html#UnityEngine_InputSystem_LowLevel_StateEvent_stateSizeInBytes).
|
||||
|
||||
A [`DeltaStateEvent`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html) is like a [`StateEvent`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html), but only contains a partial snapshot of the state of a Device. The Input System usually sends this for Devices that require a large state record, to reduce the amount of memory it needs to update if only some of the Controls change their state. To access the raw data, you can use the [`deltaState`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html#UnityEngine_InputSystem_LowLevel_DeltaStateEvent_deltaState) pointer and [`deltaStateSizeInBytes`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html#UnityEngine_InputSystem_LowLevel_DeltaStateEvent_deltaStateSizeInBytes). The Input System should apply the data to the Device's state at the offset defined by [`stateOffset`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html#UnityEngine_InputSystem_LowLevel_DeltaStateEvent_stateOffset).
|
||||
|
||||
### Device events
|
||||
|
||||
Device events indicate a change that is relevant to a Device as a whole. If you're interested in these events, it is usually more convenient to subscribe to the higher-level [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange) event rather then processing [`InputEvents`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html) yourself.
|
||||
|
||||
There are three types of Device events:
|
||||
|
||||
* [`DeviceRemoveEvent`](../api/UnityEngine.InputSystem.LowLevel.DeviceRemoveEvent.html) (`'DREM'`)
|
||||
* [`DeviceConfigurationEvent`](../api/UnityEngine.InputSystem.LowLevel.DeviceConfigurationEvent.html) (`'DCFG'`)
|
||||
* [`DeviceResetEvent`](../api/UnityEngine.InputSystem.LowLevel.DeviceResetEvent.html) (`'DRST'`)
|
||||
|
||||
`DeviceRemovedEvent` indicates that a Device has been removed or disconnected. To query the device that has been removed, you can use the common [`deviceId`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_deviceId) field. This event doesn't have any additional data.
|
||||
|
||||
`DeviceConfigurationEvent` indicates that the configuration of a Device has changed. The meaning of this is Device-specific. This might signal, for example, that the layout used by the keyboard has changed or that, on a console, a gamepad has changed which player ID(s) it is assigned to. You can query the changed device from the common [`deviceId`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_deviceId) field. This event doesn't have any additional data.
|
||||
|
||||
`DeviceResetEvent` indicates that a device should get reset. This will trigger [`InputSystem.ResetDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_ResetDevice_UnityEngine_InputSystem_InputDevice_System_Boolean_) to be called on the Device.
|
||||
|
||||
### Text events
|
||||
|
||||
[Keyboard](Keyboard.md) devices send these events to handle text input. If you're interested in these events, it's usually more convenient to subscribe to the higher-level [callbacks on the Keyboard class](Keyboard.md#text-input) rather than processing [`InputEvents`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html) yourself.
|
||||
|
||||
There are two types of text events:
|
||||
|
||||
* [`TextEvent`](../api/UnityEngine.InputSystem.LowLevel.TextEvent.html) (`'TEXT'`)
|
||||
* [`IMECompositionEvent`](../api/UnityEngine.InputSystem.LowLevel.IMECompositionEvent.html) (`'IMES'`)
|
||||
|
||||
## Working with events
|
||||
|
||||
### Listening to events
|
||||
|
||||
If you want to do any monitoring or processing on incoming events yourself, subscribe to the [`InputSystem.onEvent`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onEvent) callback.
|
||||
|
||||
```CSharp
|
||||
InputSystem.onEvent +=
|
||||
(eventPtr, device) =>
|
||||
{
|
||||
Debug.Log($"Received event for {device}");
|
||||
};
|
||||
```
|
||||
|
||||
An [`IObservable`](https://docs.microsoft.com/en-us/dotnet/api/system.iobservable-1) interface is provided to more conveniently process events.
|
||||
|
||||
```CSharp
|
||||
// Wait for first button press on a gamepad.
|
||||
InputSystem.onEvent
|
||||
.ForDevice<Gamepad>()
|
||||
.Where(e => e.HasButtonPress())
|
||||
.CallOnce(ctrl => Debug.Log($"Button {ctrl} pressed"));
|
||||
```
|
||||
|
||||
To enumerate the controls that have value changes in an event, you can use [`InputControlExtensions.EnumerateChangedControls`](../api/UnityEngine.InputSystem.InputControlExtensions.html#UnityEngine_InputSystem_InputControlExtensions_EnumerateChangedControls_UnityEngine_InputSystem_LowLevel_InputEventPtr_UnityEngine_InputSystem_InputDevice_System_Single_).
|
||||
|
||||
```CSharp
|
||||
InputSystem.onEvent
|
||||
.Call(eventPtr =>
|
||||
{
|
||||
foreach (var control in eventPtr.EnumerateChangedControls())
|
||||
Debug.Log($"Control {control} changed value to {control.ReadValueFromEventAsObject(eventPtr)}");
|
||||
};
|
||||
```
|
||||
|
||||
This is significantly more efficient than manually iterating over [`InputDevice.allControls`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_allControls) and reading out the value of each control from the event.
|
||||
|
||||
### Reading state events
|
||||
|
||||
State events contain raw memory snapshots for Devices. As such, interpreting the data in the event requires knowledge about where and how individual state is stored for a given Device.
|
||||
|
||||
The easiest way to access state contained in a state event is to rely on the Device that the state is meant for. You can ask any Control to read its value from a given event rather than from its own internally stored state.
|
||||
|
||||
For example, the following code demonstrates how to read a value for [`Gamepad.leftStick`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_leftStick) from a state event targeted at a [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html).
|
||||
|
||||
```CSharp
|
||||
InputSystem.onEvent +=
|
||||
(eventPtr, device) =>
|
||||
{
|
||||
// Ignore anything that isn't a state event.
|
||||
if (!eventPtr.IsA<StateEvent>() && !eventPtr.IsA<DeltaStateEvent>())
|
||||
return;
|
||||
|
||||
var gamepad = device as Gamepad;
|
||||
if (gamepad == null)
|
||||
{
|
||||
// Event isn't for a gamepad or device ID is no longer valid.
|
||||
return;
|
||||
}
|
||||
|
||||
var leftStickValue = gamepad.leftStick.ReadValueFromEvent(eventPtr);
|
||||
};
|
||||
```
|
||||
|
||||
### Creating events
|
||||
|
||||
Anyone can create and queue new input events against any existing Device. Queueing an input event is thread-safe, which means that event generation can happen in background threads.
|
||||
|
||||
>__Note__: Unity allocates limited memory to events that come from background threads. If background threads produce too many events, queueing an event from a thread blocks the thread until the main thread flushes out the background event queue.
|
||||
|
||||
Note that queuing an event doesn't immediately consume the event. Event processing happens on the next update (depending on [`InputSettings.updateMode`](Settings.md#update-mode), it is triggered either manually via [`InputSystem.Update`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update), or automatically as part of the Player loop).
|
||||
|
||||
#### Sending state events
|
||||
|
||||
For Devices that have a corresponding "state struct" describing the state of the device, the easiest way of sending input to the Device is to simply queue instances of those structs:
|
||||
|
||||
```CSharp
|
||||
// Mouse.
|
||||
InputSystem.QueueStateEvent(Mouse.current, new MouseState { position = new Vector2(123, 234) });
|
||||
|
||||
// Keyboard.
|
||||
InputSystem.QueueStateEvent(Keyboard.current, new KeyboardState(Key.LeftCtrl, Key.A));
|
||||
```
|
||||
|
||||
`Touchscreen` is somewhat special in that it expects its input to be in [`TouchState`](../api/UnityEngine.InputSystem.LowLevel.TouchState.html) format.
|
||||
|
||||
```CSharp
|
||||
// Start touch.
|
||||
InputSystem.QueueStateEvent(Touchscreen.current,
|
||||
new TouchState { touchId = 1, phase = TouchPhase.Began, position = new Vector2(123, 234) });
|
||||
|
||||
// Move touch.
|
||||
InputSystem.QueueStateEvent(Touchscreen.current,
|
||||
new TouchState { touchId = 1, phase = TouchPhase.Moved, position = new Vector2(234, 345) });
|
||||
|
||||
// End touch.
|
||||
InputSystem.QueueStateEvent(Touchscreen.current,
|
||||
new TouchState { touchId = 1, phase = TouchPhase.Ended, position = new Vector2(123, 234) });
|
||||
```
|
||||
|
||||
>__IMPORTANT:__ [Touch IDs](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId) cannot be 0! A valid touch must have a non-zero touch ID. Concurrent touches must each have a unique ID. After a touch has ended, its ID can be reused – although it is recommended to not do so.
|
||||
|
||||
If the exact format of the state used by a given Device is not known, the easiest way to send input to it is to simply create a [`StateEvent`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html) from the Device itself:
|
||||
|
||||
```CSharp
|
||||
// `StateEvent.From` creates a temporary buffer in unmanaged memory that holds
|
||||
// a state event large enough for the given device and contains a memory
|
||||
// copy of the device's current state.
|
||||
InputEventPtr eventPtr;
|
||||
using (StateEvent.From(myDevice, out eventPtr))
|
||||
{
|
||||
((AxisControl) myDevice["myControl"]).WriteValueIntoEvent(0.5f, eventPtr);
|
||||
InputSystem.QueueEvent(eventPtr);
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, you can send events for individual Controls.
|
||||
|
||||
```CSharp
|
||||
// Send event to update leftStick on the gamepad.
|
||||
InputSystem.QueueDeltaStateEvent(Gamepad.current.leftStick,
|
||||
new Vector2(0.123f, 0.234f);
|
||||
```
|
||||
|
||||
Note that delta state events only work for Controls that are both byte-aligned and a multiple of 8 bits in size in memory. You can't send a delta state event for a button Control that is stored as a single bit, for example.
|
||||
|
||||
### Capturing Events
|
||||
|
||||
>NOTE: To download a sample project which contains a reusable MonoBehaviour called `InputRecorder`, which can capture and replay input from arbitrary devices, open the Package Manager, select the Input System Package, and choose the sample project "Input Recorder" to download.
|
||||
|
||||
You can use the [`InputEventTrace`](../api/UnityEngine.InputSystem.LowLevel.InputEventTrace.html) class to record input events for later processing:
|
||||
|
||||
```CSharp
|
||||
var trace = new InputEventTrace(); // Can also give device ID to only
|
||||
// trace events for a specific device.
|
||||
|
||||
trace.Enable();
|
||||
|
||||
//... run stuff
|
||||
|
||||
var current = new InputEventPtr();
|
||||
while (trace.GetNextEvent(ref current))
|
||||
{
|
||||
Debug.Log("Got some event: " + current);
|
||||
}
|
||||
|
||||
// Also supports IEnumerable.
|
||||
foreach (var eventPtr in trace)
|
||||
Debug.Log("Got some event: " + eventPtr);
|
||||
|
||||
// Trace consumes unmanaged resources. Make sure to dispose.
|
||||
trace.Dispose();
|
||||
```
|
||||
|
||||
Dispose event traces after use, so that they do not leak memory on the unmanaged (C++) memory heap.
|
||||
|
||||
You can also write event traces out to files/streams, load them back in, and replay recorded streams.
|
||||
|
||||
```CSharp
|
||||
// Set up a trace with such that it automatically grows in size as needed.
|
||||
var trace = new InputEventTrace(growBuffer: true);
|
||||
trace.Enable();
|
||||
|
||||
// ... capture some input ...
|
||||
|
||||
// Write trace to file.
|
||||
trace.WriteTo("mytrace.inputtrace.");
|
||||
|
||||
// Load trace from same file.
|
||||
var loadedTrace = InputEventTrace.LoadFrom("mytrace.inputtrace");
|
||||
```
|
||||
|
||||
You can replay captured traces directly from [`InputEventTrace`](../api/UnityEngine.InputSystem.LowLevel.InputEventTrace.html) instances using the [`Replay`](../api/UnityEngine.InputSystem.LowLevel.InputEventTrace.html#UnityEngine_InputSystem_LowLevel_InputEventTrace_Replay_) method.
|
||||
|
||||
```CSharp
|
||||
// The Replay method returns a ReplayController that can be used to
|
||||
// configure and control playback.
|
||||
var controller = trace.Replay();
|
||||
|
||||
// For example, to not replay the events as is but rather create new devices and send
|
||||
// the events to them, call WithAllDevicesMappedToNewInstances.
|
||||
controller.WithAllDevicessMappedToNewInstances();
|
||||
|
||||
// Replay all frames one by one.
|
||||
controller.PlayAllFramesOnyByOne();
|
||||
|
||||
// Replay events in a way that tries to simulate original event timing.
|
||||
controller.PlayAllEventsAccordingToTimestamps();
|
||||
```
|
||||
|
||||
## Processing events
|
||||
|
||||
[Events](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html) are collected on a queue by the Unity runtime. This queue is regularly flushed out and the events on it processed. Events can be added to the queue manually by calling [`InputSystem.QueueEvent`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_QueueEvent_UnityEngine_InputSystem_LowLevel_InputEventPtr_).
|
||||
|
||||
Each time input is processed, [`InputSystem.Update`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update_) is called implicitly by the Unity runtime.
|
||||
|
||||
The interval at which this happens is determined by the ["Update Mode"](Settings.md#update-mode) configured in the settings. By default, input is processed in each frame __before__ <c>MonoBehaviour.Update</c> methods are called. If the setting is changed to process input in fixed updates, then this changes to input being processed each time before <c>MonoBehaviour.FixedUpdate</c> methods are called.
|
||||
|
||||
Normally, when input is processed, __all__ outstanding input events on the queue will be consumed. There are two exceptions to this, however.
|
||||
|
||||
When using [`UpdateMode.ProcessEventsInFixedUpdate`](../api/UnityEngine.InputSystem.InputSettings.UpdateMode.html#UnityEngine_InputSystem_InputSettings_UpdateMode_ProcessEventsInFixedUpdate), the Input System attempts to associate events with the timeslice of the corresponding <c>FixedUpdate</c>. This is based on the [timestamps](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_time) of the events and a "best effort" at calculating the corresponding timeslice of the current <c>FixedUpdated</c>.
|
||||
|
||||
The other exception are [`BeforeRender`](../api/UnityEngine.InputSystem.LowLevel.InputUpdateType.html#UnityEngine_InputSystem_LowLevel_InputUpdateType_BeforeRender) updates. These updates are run after fixed or dynamic updates but before rendering and used used exclusively to update devices such as VR headsets that need the most up-to-date tracking data. Other input is not consumed from such updates and these updates are only enabled if such devices are actually present. `BeforeRender` updates are not considered separate frames as far as input is concerned.
|
||||
|
||||
>__Note__: Manually calling [`InputSystem.Update`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update_) is strongly advised against except within tests employing [`InputTestFixture`](../api/UnityEngine.InputSystem.InputTestFixture.html) or when explicitly setting the system to [manual update mode](../api/UnityEngine.InputSystem.InputSettings.UpdateMode.html#UnityEngine_InputSystem_InputSettings_UpdateMode_ProcessEventsManually).
|
||||
|
||||
Methods such as [`InputAction.WasPerformedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame) and [`InputAction.WasPerformedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame) operate implicitly based on the [`InputSystem.Update`] cadence described above. Meaning, that they refer to the state as per the __last__ fixed/dynamic/manual update happened.
|
||||
|
||||
You can query the [current/last update type](../api/UnityEngine.InputSystem.LowLevel.InputState.html#UnityEngine_InputSystem_LowLevel_InputState_currentUpdateType) and [count](../api/UnityEngine.InputSystem.LowLevel.InputState.html#UnityEngine_InputSystem_LowLevel_InputState_updateCount) from [`InputState`](../api/UnityEngine.InputSystem.LowLevel.InputState.html).
|
||||
|
||||
### Merging of events
|
||||
|
||||
Input system uses event mering to reduce amount of events required to be processed.
|
||||
This greatly improves performance when working with high refresh rate devices like 8000 Hz mice, touchscreens and others.
|
||||
|
||||
For example let's take a stream of 7 mouse events coming in the same update:
|
||||
|
||||
```
|
||||
|
||||
Mouse Mouse Mouse Mouse Mouse Mouse Mouse
|
||||
Event no1 Event no2 Event no3 Event no4 Event no5 Event no6 Event no7
|
||||
Time 1 Time 2 Time 3 Time 4 Time 5 Time 6 Time 7
|
||||
Pos(10,20) Pos(12,21) Pos(13,23) Pos(14,24) Pos(16,25) Pos(17,27) Pos(18,28)
|
||||
Delta(1,1) Delta(2,1) Delta(1,2) Delta(1,1) Delta(2,1) Delta(1,2) Delta(1,1)
|
||||
BtnLeft(0) BtnLeft(0) BtnLeft(0) BtnLeft(1) BtnLeft(1) BtnLeft(1) BtnLeft(1)
|
||||
```
|
||||
|
||||
To reduce workload we can skip events that are not encoding button state changes:
|
||||
|
||||
```
|
||||
Mouse Mouse Mouse
|
||||
Time 3 Time 4 Time 7
|
||||
Event no3 Event no4 Event no7
|
||||
Pos(13,23) Pos(14,24) Pos(18,28)
|
||||
Delta(3,3) Delta(1,1) Delta(4,4)
|
||||
BtnLeft(0) BtnLeft(1) BtnLeft(1)
|
||||
```
|
||||
|
||||
In that case we combine no1, no2, no3 together into no3 and accumulate the delta,
|
||||
then we keep no4 because it stores the transition from button unpressed to button pressed,
|
||||
and it's important to keep the exact timestamp of such transition.
|
||||
Later we combine no5, no6, no7 together into no7 because it is the last event in the update.
|
||||
|
||||
Currently this approach is implemented for:
|
||||
- `FastMouse`, combines events unless `buttons` or `clickCount` differ in `MouseState`.
|
||||
- `Touchscreen`, combines events unless `touchId`, `phaseId` or `flags` differ in `TouchState`.
|
||||
|
||||
You can disable merging of events by:
|
||||
```
|
||||
InputSystem.settings.disableRedundantEventsMerging = true;
|
||||
```
|
||||
@@ -0,0 +1,234 @@
|
||||
---
|
||||
uid: input-system-gamepad
|
||||
---
|
||||
# Gamepad Support
|
||||
|
||||
- [Controls](#controls)
|
||||
- [Deadzones](#deadzones)
|
||||
- [Polling](#polling)
|
||||
- [Rumble](#rumble)
|
||||
- [Pausing, resuming, and stopping haptics](#pausing-resuming-and-stopping-haptics)
|
||||
- [PlayStation controllers](#playstation-controllers)
|
||||
- [Xbox controllers](#xbox-controllers)
|
||||
- [Switch controllers](#switch-controllers)
|
||||
- [Cursor Control](#cursor-control)
|
||||
- [Discover all connected devices](#discover-all-connected-devices)
|
||||
|
||||
A [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) is narrowly defined as a Device with two thumbsticks, a D-pad, and four face buttons. Additionally, gamepads usually have two shoulder and two trigger buttons. Most gamepads also have two buttons in the middle.
|
||||
|
||||
A gamepad can have additional Controls, such as a gyro, which the Device can expose. However, all gamepads are guaranteed to have at least the minimum set of Controls described above.
|
||||
|
||||
Gamepad support guarantees the correct location and functioning of Controls across platforms and hardware. For example, a PS4 DualShock controller layout should look identical regardless of which platform it is supported on. A gamepad's south face button should always be the lowermost face button.
|
||||
|
||||
>NOTE: Generic [HID](./HID.md) gamepads will __not__ be surfaced as [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) devices but rather be created as generic [joysticks](./Joystick.md). This is because the Input System cannot guarantee correct mapping of buttons and axes on the controller (the information is simply not available at the HID level). Only HID gamepads that are explicitly supported by the Input System (like the PS4 controller) will come out as gamepads. Note that you can set up the same kind of support for specific HID gamepads yourself (see ["Overriding the HID Fallback"](./HID.md#creating-a-custom-device-layout)).
|
||||
|
||||
>NOTE: In case you want to use the gamepad for driving mouse input, there is a sample called `Gamepad Mouse Cursor` you can install from the package manager UI when selecting the Input System package. The sample demonstrates how to set up gamepad input to drive a virtual mouse cursor.
|
||||
|
||||
## Controls
|
||||
|
||||
Every gamepad has the following Controls:
|
||||
|
||||
|Control|Type|Description|
|
||||
|-------|----|-----------|
|
||||
|[`leftStick`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_leftStick)|[`StickControl`](../api/UnityEngine.InputSystem.Controls.StickControl.html)|Thumbstick on the left side of the gamepad. Deadzoned. Provides a normalized 2D motion vector. X is [-1..1] from left to right, Y is [-1..1] from bottom to top. Has up/down/left/right buttons for use like a D-pad.|
|
||||
|[`rightStick`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightStick)|[`StickControl`](../api/UnityEngine.InputSystem.Controls.StickControl.html)|Thumbstick on the right side of the gamepad. Deadzoned. Provides a normalized 2D motion vector. X is [-1..1] from left to right, Y is [-1..1] from bottom to top. Has up/down/left/right buttons for use like a D-pad.|
|
||||
|[`dpad`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_dpad)|[`DpadControl`](../api/UnityEngine.InputSystem.Controls.DpadControl.html)|The D-pad on the gamepad.|
|
||||
|[`buttonNorth`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_buttonNorth)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The upper button of the four action buttons, which are usually located on the right side of the gamepad. Labelled "Y" on Xbox controllers and "Triangle" on PlayStation controllers.|
|
||||
|[`buttonSouth`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_buttonSouth)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The lower button of the four action buttons, which are usually located on the right side of the gamepad. Labelled "A" on Xbox controllers and "Cross" on PlayStation controllers.|
|
||||
|[`buttonWest`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_buttonWest)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The left button of the four action buttons, which are usually located on the right side of the gamepad. Labelled "X" on Xbox controllers and "Square" on PlayStation controllers.|
|
||||
|[`buttonEast`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_buttonEast)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The right button of the four action buttons, which are usually located on the right side of the gamepad. Labelled "B" on Xbox controllers and "Circle" on PlayStation controllers.|
|
||||
|[`leftShoulder`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_leftShoulder)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The left shoulder button.|
|
||||
|[`rightShoulder`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightShoulder)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The right shoulder button.|
|
||||
|[`leftTrigger`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_leftTrigger)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The left trigger button.|
|
||||
|[`rightTrigger`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightTrigger)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The right trigger button.|
|
||||
|[`startButton`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_startButton)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The start button.|
|
||||
|[`selectButton`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_selectButton)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The select button.|
|
||||
|[`leftStickButton`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_leftStickButton)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The button pressed when the user presses down the left stick.|
|
||||
|[`rightStickButton`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightStickButton)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The button pressed when the user presses down the right stick.|
|
||||
|
||||
>__Note__: Buttons are also full floating-point axes. For example, the left and right triggers can function as buttons as well as full floating-point axes.
|
||||
|
||||
You can also access gamepad buttons using the indexer property on [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_Item_UnityEngine_InputSystem_LowLevel_GamepadButton_) and the [`GamepadButton`](../api/UnityEngine.InputSystem.LowLevel.GamepadButton.html) enumeration:
|
||||
|
||||
```CSharp
|
||||
Gamepad.current[GamepadButton.LeftShoulder];
|
||||
```
|
||||
|
||||
Gamepads have both both Xbox-style and PS4-style aliases on buttons. For example, the following four accessors all retrieve the same "north" face button:
|
||||
|
||||
```CSharp
|
||||
Gamepad.current[GamepadButton.Y]
|
||||
Gamepad.current["Y"]
|
||||
Gamepad.current[GamepadButton.Triangle]
|
||||
Gamepad.current["Triangle"]
|
||||
```
|
||||
|
||||
### Deadzones
|
||||
|
||||
Deadzones prevent accidental input due to slight variations in where gamepad sticks come to rest at their centre point. They allow a certain small inner area where the input is considered to be zero even if it is slightly off from the zero position.
|
||||
|
||||
To add a deadzone to gamepad stick, put a [stick deadzone Processor](Processors.md#stick-deadzone) on the sticks, like this:
|
||||
|
||||
```JSON
|
||||
{
|
||||
"name" : "MyGamepad",
|
||||
"extend" : "Gamepad",
|
||||
"controls" : [
|
||||
{
|
||||
"name" : "leftStick",
|
||||
"processors" : "stickDeadzone(min=0.125,max=0.925)"
|
||||
},
|
||||
{
|
||||
"name" : "rightStick",
|
||||
"processors" : "stickDeadzone(min=0.125,max=0.925)"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can do the same in your C# state structs.
|
||||
|
||||
```C#
|
||||
public struct MyDeviceState
|
||||
{
|
||||
[InputControl(processors = "stickDeadzone(min=0.125,max=0.925)"]
|
||||
public StickControl leftStick;
|
||||
[InputControl(processors = "stickDeadzone(min=0.125,max=0.925)"]
|
||||
public StickControl rightStick;
|
||||
}
|
||||
```
|
||||
|
||||
The gamepad layout already adds stick deadzone processors which take their min and max values from [`InputSettings.defaultDeadzoneMin`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultDeadzoneMin) and [`InputSettings.defaultDeadzoneMax`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultDeadzoneMax).
|
||||
|
||||
|
||||
|
||||
## Polling
|
||||
|
||||
On Windows (XInput controllers only), Universal Windows Platform (UWP), and Switch, Unity polls gamepads explicitly rather than deliver updates as events.
|
||||
|
||||
You can control polling frequency manually. The default polling frequency is 60 Hz. Use [`InputSystem.pollingFrequency`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_pollingFrequency) to get or set the frequency.
|
||||
|
||||
```CSharp
|
||||
// Poll gamepads at 120 Hz.
|
||||
InputSystem.pollingFrequency = 120;
|
||||
```
|
||||
|
||||
Increased frequency should lead to an increased number of events on the respective Devices. The timestamps provided on the events should roughly follow the spacing dictated by the polling frequency. Note, however, that the asynchronous background polling depends on OS thread scheduling and can vary.
|
||||
|
||||
## Rumble
|
||||
|
||||
The [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) class implements the [`IDualMotorRumble`](../api/UnityEngine.InputSystem.Haptics.IDualMotorRumble.html) interface that allows you to control the left and right motor speeds. In most common gamepads, the left motor emits a low-frequency rumble, and the right motor emits a high-frequency rumble.
|
||||
|
||||
```CSharp
|
||||
// Rumble the low-frequency (left) motor at 1/4 speed and the high-frequency
|
||||
// (right) motor at 3/4 speed.
|
||||
Gamepad.current.SetMotorSpeeds(0.25f, 0.75f);
|
||||
```
|
||||
|
||||
>__Note__: Only the following combinations of Devices/OSes currently support rumble:
|
||||
>* PS4, Xbox, and Switch controllers, when connected to their respective consoles. Only supported if you install console-specific input packages in your Project.
|
||||
>* PS4 controllers, when connected to Mac or Windows/UWP computers.
|
||||
>* Xbox controllers on Windows.
|
||||
|
||||
[//]: # (TODO: are we missing any supported configs?)
|
||||
|
||||
### Pausing, resuming, and stopping haptics
|
||||
|
||||
[`IDualMotorRumble`](../api/UnityEngine.InputSystem.Haptics.IDualMotorRumble.html) is based on [`IHaptics`](../api/UnityEngine.InputSystem.Haptics.IHaptics.html), which is the base interface for any haptics support on any Device. You can pause, resume, and reset haptic feedback using the [`PauseHaptics`](../api/UnityEngine.InputSystem.Haptics.IHaptics.html#UnityEngine_InputSystem_Haptics_IHaptics_PauseHaptics), [`ResumeHaptics`](../api/UnityEngine.InputSystem.Haptics.IHaptics.html#UnityEngine_InputSystem_Haptics_IHaptics_ResumeHaptics), and [`ResetHaptics`](../api/UnityEngine.InputSystem.Haptics.IHaptics.html#UnityEngine_InputSystem_Haptics_IHaptics_ResetHaptics) methods respectively.
|
||||
|
||||
In certain situations, you might want to globally pause or stop haptics for all Devices. For example, if the player enters an in-game menu, you can pause haptics while the player is in the menu, and then resume haptics once the player resumes the game. You can use the corresponding methods on [`InputSystem`](../api/UnityEngine.InputSystem.InputSystem.html) to achieve this result. These methods work the same way as Device-specific methods, but affect all Devices:
|
||||
|
||||
```CSharp
|
||||
// Pause haptics globally.
|
||||
InputSystem.PauseHaptics();
|
||||
|
||||
// Resume haptics globally.
|
||||
InputSystem.ResumeHaptics();
|
||||
|
||||
// Stop haptics globally.
|
||||
InputSystem.ResetHaptics();
|
||||
```
|
||||
|
||||
The difference between [`PauseHaptics`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_PauseHaptics) and [`ResetHaptics`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_ResetHaptics) is that the latter resets haptics playback state on each Device to its initial state, whereas [`PauseHaptics`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_PauseHaptics) preserves playback state in memory and only stops playback on the hardware.
|
||||
|
||||
## PlayStation controllers
|
||||
|
||||
PlayStation controllers are well supported on different Devices. The Input System implements these as different derived types of the [`DualShockGamepad`](../api/UnityEngine.InputSystem.DualShock.DualShockGamepad.html) base class, which derives from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html)):
|
||||
|
||||
* [`DualShock3GamepadHID`](../api/UnityEngine.InputSystem.DualShock.DualShock3GamepadHID.html): A DualShock 3 controller connected to a desktop computer using the HID interface. Currently only supported on macOS. Doesn't support [rumble](#rumble).
|
||||
|
||||
* [`DualShock4GamepadHID`](../api/UnityEngine.InputSystem.DualShock.DualShock4GamepadHID.html): A DualShock 4 controller connected to a desktop computer using the HID interface. Supported on macOS, Windows, UWP, and Linux.
|
||||
*
|
||||
* [`DualSenseGamepadHID`](../api/UnityEngine.InputSystem.DualShock.DualSenseGamepadHID.html): A DualSense controller connected to a desktop computer using the HID interface. Supported on macOS, Windows.
|
||||
|
||||
* [`DualShock4GampadiOS`](../api/UnityEngine.InputSystem.iOS.DualShock4GampadiOS.html): A DualShock 4 controller connected to an iOS Device via Bluetooth. Requires iOS 13 or higher.
|
||||
|
||||
* [`SetLightBarColor(Color)`](../api/UnityEngine.InputSystem.DualShock.DualShockGamepad.html#UnityEngine_InputSystem_DualShock_DualShockGamepad_SetLightBarColor_UnityEngine_Color_): Used to set the color of the light bar on the controller.
|
||||
|
||||
Note that, due to limitations in the USB driver and/or the hardware, only one IOCTL (input/output control) command can be serviced at a time. [`SetLightBarColor(Color)`](../api/UnityEngine.InputSystem.DualShock.DualShockGamepad.html#UnityEngine_InputSystem_DualShock_DualShockGamepad_SetLightBarColor_UnityEngine_Color_) and [`SetMotorSpeeds(Single, Single)`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_SetMotorSpeeds_System_Single_System_Single_) functionality on Dualshock 4 is implemented using IOCTL commands, and so if either method is called in quick succession, it is likely that only the first command will successfully complete. The other commands will be dropped. If there is a need to set both lightbar color and rumble motor speeds at the same time, use the [`SetMotorSpeedsAndLightBarColor(Single, Single, Color)`](../api/UnityEngine.InputSystem.DualShock.DualShock4GamepadHID.html#UnityEngine_InputSystem_DualShock_DualShock4GamepadHID_SetMotorSpeedsAndLightBarColor_System_Single_System_Single_UnityEngine_Color_) method.
|
||||
|
||||
>__Note__:
|
||||
>* Unity supports PlayStation controllers on WebGL in some browser and OS configurations, but treats them as basic [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) or [`Joystick`](../api/UnityEngine.InputSystem.Joystick.html) Devices, and doesn't support rumble or any other DualShock-specific functionality.
|
||||
>* Unity doesn't support connecting a PlayStation controller to a desktop machine using the DualShock 4 USB Wireless Adaptor. Use USB or Bluetooth to connect it.
|
||||
|
||||
## Xbox controllers
|
||||
|
||||
Xbox controllers are well supported on different Devices. The Input System implements these using the [`XInputController`](../api/UnityEngine.InputSystem.XInput.XInputController.html) class, which derives from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html). On Windows and UWP, Unity uses the XInput API to connect to any type of supported XInput controller, including all Xbox One or Xbox 360-compatible controllers. These controllers are represented as an [`XInputController`](../api/UnityEngine.InputSystem.XInput.XInputController.html) instance. You can query the [`XInputController.subType`](../api/UnityEngine.InputSystem.XInput.XInputController.html#UnityEngine_InputSystem_XInput_XInputController_subType) property to get information about the type of controller (for example, a wheel or a gamepad).
|
||||
|
||||
On other platforms Unity, uses derived classes to represent Xbox controllers:
|
||||
|
||||
* [`XboxGamepadMacOS`](../api/UnityEngine.InputSystem.XInput.XboxGamepadMacOS.html): Any Xbox or compatible gamepad connected to a Mac via USB using the [Xbox Controller Driver for macOS](https://github.com/360Controller/360Controller).
|
||||
|
||||
* [`XboxOneGampadMacOSWireless`](../api/UnityEngine.InputSystem.XInput.XboxOneGampadMacOSWireless.html): An Xbox One controller connected to a Mac via Bluetooth. Only the latest generation of Xbox One controllers supports Bluetooth. These controllers don't require any additional drivers in this scenario.
|
||||
|
||||
* [`XboxOneGampadiOS`](../api/UnityEngine.InputSystem.iOS.XboxOneGampadiOS.html): An Xbox One controller connected to an iOS Device via Bluetooth. Requires iOS 13 or higher.
|
||||
|
||||
>__Note__:
|
||||
>* XInput controllers on Mac currently require the installation of the [Xbox Controller Driver for macOS](https://github.com/360Controller/360Controller). This driver only supports USB connections, and doesn't support wireless dongles. However, the latest generation of Xbox One controllers natively support Bluetooth. Macs natively support these controllers as HIDs without any additional drivers when connected via Bluetooth.
|
||||
>* Unity supports Xbox controllers on WebGL in some browser and OS configurations, but treats them as basic [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) or [`Joystick`](../api/UnityEngine.InputSystem.Joystick.html) Devices, and doesn't support rumble or any other Xbox-specific functionality.
|
||||
|
||||
## Switch controllers
|
||||
|
||||
The Input System support Switch Pro controllers on desktop computers via the [`SwitchProControllerHID`](../api/UnityEngine.InputSystem.Switch.SwitchProControllerHID.html) class, which implements basic gamepad functionality.
|
||||
|
||||
>__Note__: This support does not currently work for Switch Pro controllers connected via wired USB. Instead, the Switch Pro controller *must* be connected via Bluetooth. This is due to the controller using a prioprietary communication protocol on top of HID which does not allow treating the controller like any other HID.
|
||||
|
||||
>__Note__: Switch Joy-Cons are not currently supported on desktop.
|
||||
|
||||
## Cursor Control
|
||||
|
||||
To give gamepads and joysticks control over a hardware or software cursor, you can use the [`VirtualMouseInput`](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html) component. See [`VirtualMouseInput` component](UISupport.md#virtual-mouse-cursor-control) in the UI section of the manual.
|
||||
|
||||
## Discover all connected devices
|
||||
|
||||
There are various ways to discover the currently connected devices, as shown in the code samples below.
|
||||
|
||||
To query a list of all connected devices (does not allocate; read-only access):
|
||||
```
|
||||
InputSystem.devices
|
||||
```
|
||||
|
||||
To get notified when a device is added or removed:
|
||||
```
|
||||
InputSystem.onDeviceChange +=
|
||||
(device, change) =>
|
||||
{
|
||||
if (change == InputDeviceChange.Added || change == InputDeviceChange.Removed)
|
||||
{
|
||||
Debug.Log($"Device '{device}' was {change}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To find all gamepads and joysticks:
|
||||
```
|
||||
var devices = InputSystem.devices;
|
||||
for (var i = 0; i < devices.Count; ++i)
|
||||
{
|
||||
var device = devices[i];
|
||||
if (device is Joystick || device is Gamepad)
|
||||
{
|
||||
Debug.Log("Found " + device);
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,317 @@
|
||||
---
|
||||
uid: input-system-hid
|
||||
---
|
||||
# HID Support
|
||||
|
||||
Human Interface Device (HID) is a [specification](https://www.usb.org/hid) to describe peripheral user input devices connected to computers via USB or Bluetooth. HID is commonly used to implement devices such as gamepads, joysticks, or racing wheels.
|
||||
|
||||
The Input System directly supports HID (connected via both USB and Bluetooth) on Windows, MacOS, and the Universal Windows Platform (UWP). The system might support HID on other platforms, but not deliver input through HID-specific APIs. For example, on Linux, the system supports gamepad and joystick HIDs through SDL, but doesn't support other HIDs.
|
||||
|
||||
Every HID comes with a device descriptor. To browse through the descriptor of an HID from the Input Debugger, click the __HID Descriptor__ button in the device debugger window. To specify the type of the device, the HID descriptor reports entry numbers in the [HID usage tables](https://www.usb.org/document-library/hid-usage-tables-112), and a list of all controls on the device, along with their data ranges and usages.
|
||||
|
||||
|
||||
|
||||
The Input System handles HIDs in one of two ways:
|
||||
|
||||
1. The system has a known layout for the specific HID.
|
||||
2. If the system does not have a known layout, it auto-generates one for the HID.
|
||||
|
||||
## Auto-generated layouts
|
||||
|
||||
By default, the Input System creates layouts and Device representations for any HID which reports its usage as `GenericDesktop/Joystick`, `GenericDesktop/Gamepad`, or `GenericDesktop/MultiAxisController` (see the [HID usage table specifications](https://www.usb.org/document-library/hid-usage-tables-112) for more information). To change the list of supported usages, set [`HIDSupport.supportedHIDUsages`](../api/UnityEngine.InputSystem.HID.HIDSupport.html#UnityEngine_InputSystem_HID_HIDSupport_supportedHIDUsages).
|
||||
|
||||
When the Input System automatically creates a layout for an HID, it always reports these Devices as [`Joysticks`](Joystick.md), represented by the [`Joystick` device class](../api/UnityEngine.InputSystem.Joystick.html). The first elements with a reported HID usage of `GenericDesktop/X` and `GenericDesktop/Y` together form the joystick's [`stick`](../api/UnityEngine.InputSystem.Joystick.html#UnityEngine_InputSystem_Joystick_stick) Control. The system then adds Controls for all further HID axis or button elements, using the Control names reported by the HID specification. The Input System assigns the first control with an HID usage of `Button/Button 1` to the joystick's [`trigger`](../api/UnityEngine.InputSystem.Joystick.html#UnityEngine_InputSystem_Joystick_trigger) Control.
|
||||
|
||||
The auto-generated layouts represent a "best effort" on the part of the Input System. The way Human Interface Devices describe themselves in accordance with the HID standard is too ambiguous in practice, so generated layouts might lead to Controls that don't work as expected. For example, while the layout builder can identify hat switches and D-pads, it can often only make guesses as to which direction represents which. The same goes for individual buttons, which generally aren't assigned any meaning in HID.
|
||||
|
||||
The best way to resolve the situation of HIDs not working as expected is to add a custom layout, which bypasses auto-generation altogether. See [Creating a custom device layout](#creating-a-custom-device-layout) for details.
|
||||
|
||||
## HID output
|
||||
|
||||
HIDs can support output (for example, to toggle lights or force feedback motors on a gamepad). Unity controls output by sending HID Output Report commands to a Device. Output reports use Device-specific data formats. To use HID Output Reports, call [`InputDevice.ExecuteCommand`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_ExecuteCommand__1___0__) to send a command struct with the [`typeStatic`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html#properties) property set as `"HIDO"` to a Device. The command struct contains the Device-specific data sent out to the HID.
|
||||
|
||||
## Creating a custom device layout
|
||||
|
||||
Often, when using the layouts auto-generated for HIDs, the result isn't ideal. Controls don't receive proper names specific to the Device, some Controls might not work as expected, and some Controls that use vendor-specific formats might not appear altogether.
|
||||
|
||||
The best way to deal with this is to override the HID fallback and set up a custom Device layout specifically for your Device. This overrides the default auto-generation and gives you full control over how the Device is exposed.
|
||||
|
||||
Below are three example workflows showing different ways to achieve this.
|
||||
|
||||
- [Example 1 - Use an existing C# InputDevice](#custom-device-workflow-example-1---use-an-existing-c-inputdevice)
|
||||
- [Example 2 - Create your own InputDevice class](#custom-device-workflow-example-2---create-your-own-inputdevice-class)
|
||||
- [Example 3 - A more complex example using the PS4 DualShock Controller](#custom-device-workflow-example-3---ps4-dualshock-controller)
|
||||
|
||||
### Custom Device Workflow Example 1 - Use an existing C# InputDevice
|
||||
|
||||
If you want to use one of the existing C# [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) classes in code to interface with your Device, you can build on an existing layout using JSON:
|
||||
|
||||
```
|
||||
{
|
||||
"name" : "MyDevice",
|
||||
"extend" : "Gamepad", // Or some other thing
|
||||
"controls" : [
|
||||
{
|
||||
"name" : "firstButton",
|
||||
"layout" : "Button",
|
||||
"offset" : 0,
|
||||
"bit": 0,
|
||||
"format" : "BIT",
|
||||
},
|
||||
{
|
||||
"name" : "secondButton",
|
||||
"layout" : "Button",
|
||||
"offset" : 0,
|
||||
"bit": 1,
|
||||
"format" : "BIT",
|
||||
},
|
||||
{
|
||||
"name" : "axis",
|
||||
"layout" : "Axis",
|
||||
"offset" : 4,
|
||||
"format" : "FLT",
|
||||
"parameters" : "clamp=true,clampMin=0,clampMax=1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
You then register your layout with the system and then instantiate it:
|
||||
|
||||
```C#
|
||||
InputSystem.RegisterControlLayout(myDeviceJson);
|
||||
var device = InputSystem.AddDevice("MyDevice");
|
||||
```
|
||||
|
||||
### Custom Device Workflow Example 2 - Create your own InputDevice class
|
||||
|
||||
Alternatively, you can create your own [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) class and state layouts in C#.
|
||||
|
||||
```C#
|
||||
public struct MyDeviceState : IInputStateTypeInfo
|
||||
{
|
||||
// FourCC type codes are used to identify the memory layouts of state blocks.
|
||||
public FourCC format => new FourCC('M', 'D', 'E', 'V');
|
||||
|
||||
[InputControl(name = "firstButton", layout = "Button", bit = 0)]
|
||||
[InputControl(name = "secondButton", layout = "Button", bit = 1)]
|
||||
public int buttons;
|
||||
[InputControl(layout = "Analog", parameters="clamp=true,clampMin=0,clampMax=1")]
|
||||
public float axis;
|
||||
}
|
||||
|
||||
[InputState(typeof(MyDeviceState)]
|
||||
public class MyDevice : InputDevice
|
||||
{
|
||||
public ButtonControl firstButton { get; private set; }
|
||||
public ButtonControl secondButton { get; private set; }
|
||||
public AxisControl axis { get; private set; }
|
||||
|
||||
protected override void FinishSetup(InputControlSetup setup)
|
||||
{
|
||||
firstButton = setup.GetControl<ButtonControl>(this, "firstButton");
|
||||
secondButton = setup.GetControl<ButtonControl>(this, "secondButton");
|
||||
axis = setup.GetControl<AxisControl>(this, "axis");
|
||||
base.FinishSetup(setup);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To create an instance of your Device, register it as a layout and then instantiate it:
|
||||
|
||||
```C#
|
||||
InputSystem.RegisterControlLayout("MyDevice", typeof(MyDevice));
|
||||
InputSystem.AddDevice("MyDevice");
|
||||
```
|
||||
|
||||
### Custom Device Workflow Example 3 - PS4 DualShock Controller
|
||||
|
||||
This example workflow uses the same technique as the previous example, but provides more detail by using the PS4 DualShock controller as a more complex device to set up.
|
||||
|
||||
The following example assumes that the Input System doesn't already have a custom layout for the PS4 DualShock controller, and that you want to add such a layout.
|
||||
|
||||
In this example, you want to expose the controller as a [`Gamepad`](Gamepad.md) and you roughly know the HID data format used by the Device.
|
||||
|
||||
>__Tip__: If you don't know the format of a given HID you want to support, you can open the Input Debugger with the Device plugged in and pop up both the debugger view for the Device and the window showing the HID descriptor. Then, you can go through the Controls one by one, see what happens in the debug view, and correlate that to the Controls in the HID descriptor. You can also double-click individual events and compare the raw data coming in from the Device. If you select two events in the event trace, you can then right-click them and choose __Compare__ to open a window that shows only the differences between the two events.
|
||||
|
||||
#### Step 1: The state struct
|
||||
|
||||
The first step is to describe in detail what format that input data for the Device comes in, as well as the [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html) instances that should read out individual pieces of information from that data.
|
||||
|
||||
The HID input reports from the PS4 controller look approximately like this:
|
||||
|
||||
```C++
|
||||
struct PS4InputReport
|
||||
{
|
||||
byte reportId; // #0
|
||||
byte leftStickX; // #1
|
||||
byte leftStickY; // #2
|
||||
byte rightStickX; // #3
|
||||
byte rightStickY; // #4
|
||||
byte dpad : 4; // #5 bit #0 (0=up, 2=right, 4=down, 6=left)
|
||||
byte squareButton : 1; // #5 bit #4
|
||||
byte crossButton : 1; // #5 bit #5
|
||||
byte circleButton : 1; // #5 bit #6
|
||||
byte triangleButton : 1; // #5 bit #7
|
||||
byte leftShoulder : 1; // #6 bit #0
|
||||
byte rightShoulder : 1; // #6 bit #1
|
||||
byte leftTriggerButton : 2;// #6 bit #2
|
||||
byte rightTriggerButton : 2;// #6 bit #3
|
||||
byte shareButton : 1; // #6 bit #4
|
||||
byte optionsButton : 1; // #6 bit #5
|
||||
byte leftStickPress : 1; // #6 bit #6
|
||||
byte rightStickPress : 1; // #6 bit #7
|
||||
byte psButton : 1; // #7 bit #0
|
||||
byte touchpadPress : 1; // #7 bit #1
|
||||
byte padding : 6;
|
||||
byte leftTrigger; // #8
|
||||
byte rightTrigger; // #9
|
||||
}
|
||||
```
|
||||
|
||||
You can translate this into a C# struct:
|
||||
|
||||
```CSharp
|
||||
// We receive data as raw HID input reports. This struct
|
||||
// describes the raw binary format of such a report.
|
||||
[StructLayout(LayoutKind.Explicit, Size = 32)]
|
||||
struct DualShock4HIDInputReport : IInputStateTypeInfo
|
||||
{
|
||||
// Because all HID input reports are tagged with the 'HID ' FourCC,
|
||||
// this is the format we need to use for this state struct.
|
||||
public FourCC format => new FourCC('H', 'I', 'D');
|
||||
|
||||
// HID input reports can start with an 8-bit report ID. It depends on the device
|
||||
// whether this is present or not. On the PS4 DualShock controller, it is
|
||||
// present. We don't really need to add the field, but let's do so for the sake of
|
||||
// completeness. This can also help with debugging.
|
||||
[FieldOffset(0)] public byte reportId;
|
||||
|
||||
// The InputControl annotations here probably look a little scary, but what we do
|
||||
// here is relatively straightforward. The fields we add we annotate with
|
||||
// [FieldOffset] to force them to the right location, and then we add InputControl
|
||||
// to attach controls to the fields. Each InputControl attribute can only do one of
|
||||
// two things: either it adds a new control or it modifies an existing control.
|
||||
// Given that our layout is based on Gamepad, almost all the controls here are
|
||||
// inherited from Gamepad, and we just modify settings on them.
|
||||
|
||||
[InputControl(name = "leftStick", layout = "Stick", format = "VC2B")]
|
||||
[InputControl(name = "leftStick/x", offset = 0, format = "BYTE",
|
||||
parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5")]
|
||||
[InputControl(name = "leftStick/left", offset = 0, format = "BYTE",
|
||||
parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0,clampMax=0.5,invert")]
|
||||
[InputControl(name = "leftStick/right", offset = 0, format = "BYTE",
|
||||
parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0.5,clampMax=1")]
|
||||
[InputControl(name = "leftStick/y", offset = 1, format = "BYTE",
|
||||
parameters = "invert,normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5")]
|
||||
[InputControl(name = "leftStick/up", offset = 1, format = "BYTE",
|
||||
parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0,clampMax=0.5,invert")]
|
||||
[InputControl(name = "leftStick/down", offset = 1, format = "BYTE",
|
||||
parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0.5,clampMax=1,invert=false")]
|
||||
[FieldOffset(1)] public byte leftStickX;
|
||||
[FieldOffset(2)] public byte leftStickY;
|
||||
|
||||
[InputControl(name = "rightStick", layout = "Stick", format = "VC2B")]
|
||||
[InputControl(name = "rightStick/x", offset = 0, format = "BYTE", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5")]
|
||||
[InputControl(name = "rightStick/left", offset = 0, format = "BYTE", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0,clampMax=0.5,invert")]
|
||||
[InputControl(name = "rightStick/right", offset = 0, format = "BYTE", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0.5,clampMax=1")]
|
||||
[InputControl(name = "rightStick/y", offset = 1, format = "BYTE", parameters = "invert,normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5")]
|
||||
[InputControl(name = "rightStick/up", offset = 1, format = "BYTE", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0,clampMax=0.5,invert")]
|
||||
[InputControl(name = "rightStick/down", offset = 1, format = "BYTE", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp,clampMin=0.5,clampMax=1,invert=false")]
|
||||
[FieldOffset(3)] public byte rightStickX;
|
||||
[FieldOffset(4)] public byte rightStickY;
|
||||
|
||||
[InputControl(name = "dpad", format = "BIT", layout = "Dpad", sizeInBits = 4, defaultState = 8)]
|
||||
[InputControl(name = "dpad/up", format = "BIT", layout = "DiscreteButton", parameters = "minValue=7,maxValue=1,nullValue=8,wrapAtValue=7", bit = 0, sizeInBits = 4)]
|
||||
[InputControl(name = "dpad/right", format = "BIT", layout = "DiscreteButton", parameters = "minValue=1,maxValue=3", bit = 0, sizeInBits = 4)]
|
||||
[InputControl(name = "dpad/down", format = "BIT", layout = "DiscreteButton", parameters = "minValue=3,maxValue=5", bit = 0, sizeInBits = 4)]
|
||||
[InputControl(name = "dpad/left", format = "BIT", layout = "DiscreteButton", parameters = "minValue=5, maxValue=7", bit = 0, sizeInBits = 4)]
|
||||
[InputControl(name = "buttonWest", displayName = "Square", bit = 4)]
|
||||
[InputControl(name = "buttonSouth", displayName = "Cross", bit = 5)]
|
||||
[InputControl(name = "buttonEast", displayName = "Circle", bit = 6)]
|
||||
[InputControl(name = "buttonNorth", displayName = "Triangle", bit = 7)]
|
||||
[FieldOffset(5)] public byte buttons1;
|
||||
|
||||
[InputControl(name = "leftShoulder", bit = 0)]
|
||||
[InputControl(name = "rightShoulder", bit = 1)]
|
||||
[InputControl(name = "leftTriggerButton", layout = "Button", bit = 2)]
|
||||
[InputControl(name = "rightTriggerButton", layout = "Button", bit = 3)]
|
||||
[InputControl(name = "select", displayName = "Share", bit = 4)]
|
||||
[InputControl(name = "start", displayName = "Options", bit = 5)]
|
||||
[InputControl(name = "leftStickPress", bit = 6)]
|
||||
[InputControl(name = "rightStickPress", bit = 7)]
|
||||
[FieldOffset(6)] public byte buttons2;
|
||||
|
||||
[InputControl(name = "systemButton", layout = "Button", displayName = "System", bit = 0)]
|
||||
[InputControl(name = "touchpadButton", layout = "Button", displayName = "Touchpad Press", bit = 1)]
|
||||
[FieldOffset(7)] public byte buttons3;
|
||||
|
||||
[InputControl(name = "leftTrigger", format = "BYTE")]
|
||||
[FieldOffset(8)] public byte leftTrigger;
|
||||
|
||||
[InputControl(name = "rightTrigger", format = "BYTE")]
|
||||
[FieldOffset(9)] public byte rightTrigger;
|
||||
|
||||
[FieldOffset(30)] public byte batteryLevel;
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 2: The InputDevice
|
||||
|
||||
Next, you need an `InputDevice` to represent your device. Because you're dealing with a gamepad, you must create a new subclass of `Gamepad`.
|
||||
|
||||
For simplicity, this example ignores the fact that there is a `DualShockGamepad` class that the actual `DualShockGamepadHID` is based on.
|
||||
|
||||
```CSharp
|
||||
// Using InputControlLayoutAttribute, we tell the system about the state
|
||||
// struct we created, which includes where to find all the InputControl
|
||||
// attributes that we placed on there. This is how the Input System knows
|
||||
// what controls to create and how to configure them.
|
||||
[InputControlLayout(stateType = typeof(DualShock4HIDInputReport)]
|
||||
public DualShock4GamepadHID : Gamepad
|
||||
{
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 3: Registering the Device
|
||||
|
||||
The last step is to register your new type of Device and set up the Input System so that when a PS4 controller is connected, the Input System generates your custom Device instead of using the default HID fallback.
|
||||
|
||||
This only requires a call to [`InputSystem.RegisterLayout<T>`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterLayout__1_System_String_System_Nullable_UnityEngine_InputSystem_Layouts_InputDeviceMatcher__), giving it an [`InputDeviceMatcher`](../api/UnityEngine.InputSystem.Layouts.InputDeviceMatcher.html) that matches the description for a PS4 DualShock HID. In theory, you can place this call anywhere, but the best point for registering layouts is generally during startup. Doing so ensures that your custom layout is visible to the Unity Editor and therefore exposed, for example, in the Input Control picker.
|
||||
|
||||
You can insert your registration into the startup sequence by modifying the code for your `DualShock4GamepadHID` Device as follows:
|
||||
|
||||
```CSharp
|
||||
[InputControlLayout(stateType = typeof(DualShock4HIDInputReport)]
|
||||
#if UNITY_EDITOR
|
||||
[InitializeOnLoad] // Make sure static constructor is called during startup.
|
||||
#endif
|
||||
public DualShock4GamepadHID : Gamepad
|
||||
{
|
||||
static DualShock4GamepadHID()
|
||||
{
|
||||
// This is one way to match the Device.
|
||||
InputSystem.RegisterLayout<DualShock4GamepadHID>(
|
||||
new InputDeviceMatcher()
|
||||
.WithInterface("HID")
|
||||
.WithManufacturer("Sony.+Entertainment")
|
||||
.WithProduct("Wireless Controller"));
|
||||
|
||||
// Alternatively, you can also match by PID and VID, which is generally
|
||||
// more reliable for HIDs.
|
||||
InputSystem.RegisterLayout<DualShock4GamepadHID>(
|
||||
matches: new InputDeviceMatcher()
|
||||
.WithInterface("HID")
|
||||
.WithCapability("vendorId", 0x54C) // Sony Entertainment.
|
||||
.WithCapability("productId", 0x9CC)); // Wireless controller.
|
||||
}
|
||||
|
||||
// In the Player, to trigger the calling of the static constructor,
|
||||
// create an empty method annotated with RuntimeInitializeOnLoadMethod.
|
||||
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
|
||||
static void Init() {}
|
||||
}
|
||||
```
|
||||
|
||||
Your custom layout now picks up any Device that matches the manufacturer and product name strings, or the vendor and product IDs in its HID descriptor. The Input System now represents a `DualShock4GamepadHID` Device instance.
|
||||
|
||||
For more information, you can also read the [Device matching](Devices.md#matching) documentation.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
uid: input-system-how-do-i
|
||||
---
|
||||
# How do I…?
|
||||
|
||||
A collection of frequently asked questions, and where to find their answers in the documentation.
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> If you're new to the Input System and have landed on this page looking for documentation, it's best to read the [QuickStart Guide](QuickStartGuide.md), and the [Concepts](Concepts.md) and [Workflows](Workflows.md) pages, so that you can make sure you're choosing the best workflow for your project's input requirements.
|
||||
>
|
||||
> This is because there are a number of different ways to read input using the Input System, and many of the answers on this page give you the quickest but least flexible solution, and may not be suitable for a project with more complex requirements.
|
||||
|
||||
|
||||
How do I...?
|
||||
|
||||
- [check if a specific key or button was pressed this frame?](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame)
|
||||
|
||||
- [check if any key or button was pressed](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onAnyButtonPress)
|
||||
|
||||
- [find all connected gamepads?](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_all)
|
||||
|
||||
- [find the gamepad that the player is currently using?](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_current)
|
||||
|
||||
- [know when a new device was plugged in?](Devices.md#monitoring-devices)
|
||||
|
||||
- [create my own custom devices?](HID.md#creating-a-custom-device-layout)
|
||||
|
||||
- create a simple "Fire" type action?</br>
|
||||
Use the same techniques shown for the "Jump" action in the [Workflows section](Workflows.md)
|
||||
|
||||
- [require a button to be held down for some duration before triggering an action?](Interactions.html#hold)
|
||||
|
||||
- [use a "positive" and a "negative" button to drive an axis?](ActionBindings.html#1d-axis)
|
||||
|
||||
- [create a UI to rebind input in my game?](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html)
|
||||
|
||||
- [set up an Action to specifically target the left-hand XR controller?](../api/UnityEngine.InputSystem.XR.XRController.html#UnityEngine_InputSystem_XR_XRController_leftHand)
|
||||
|
||||
- [make my left-hand XR controller my right-hand one?](../api/UnityEngine.InputSystem.XR.XRController.html#UnityEngine_InputSystem_XR_XRController_leftHand)
|
||||
|
||||
- [get all current touches from the touchscreen?](Touch.md#reading-all-touches)
|
||||
|
||||
- [deal with my gamepad data arriving in a format different from `GamepadState`?](../api/UnityEngine.InputSystem.LowLevel.GamepadState.html)
|
||||
|
||||
- [force the Input System to use my own layout when the native backend discovers a specific Device?](Devices.md#native-devices)
|
||||
|
||||
- [add deadzoning to my gamepad sticks?](Gamepad.md#deadzones)
|
||||
|
||||
- [give my head tracking an extra update before rendering?](../api/UnityEngine.InputSystem.XR.XRHMD.html)
|
||||
|
||||
- [record events flowing through the system?](Debugging.md#other-tips)
|
||||
|
||||
- [see events as they're processed?](Debugging.md#other-tips)
|
||||
|
||||
- [see what Devices I have and what state they're in?](Debugging.html#debugging-devices)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 82 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 309 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 436 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 286 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 610 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 108 KiB |
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 80 KiB |
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 80 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 921 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 209 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 95 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 127 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 166 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 96 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 150 KiB |
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 220 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 92 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 178 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 257 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 190 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 270 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 106 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.3 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user