From ebb2df6503765baad7ad29a58ef1308829ecd686 Mon Sep 17 00:00:00 2001 From: Jonas Echterhoff Date: Wed, 18 Sep 2019 14:08:03 +0200 Subject: [PATCH 1/3] Docs feedback --- .../Documentation~/ActionAssets.md | 96 ++++---- .../Documentation~/ActionBindings.md | 174 ++++++++------- .../Documentation~/Actions.md | 176 +++++++-------- .../Documentation~/Architecture.md | 24 +- .../Documentation~/Components.md | 119 +++++----- .../Documentation~/Contributing.md | 8 +- .../Documentation~/Controls.md | 106 ++++----- .../Documentation~/Debugging.md | 62 +++--- .../Documentation~/Devices.md | 210 +++++++++--------- .../Documentation~/Events.md | 88 ++++---- .../Documentation~/Gamepad.md | 73 +++--- .../Documentation~/HID.md | 58 +++-- .../Documentation~/HowDoI.md | 179 ++++++++------- .../Images/CreateInputActions.png | Bin 385774 -> 0 bytes .../Documentation~/Installation.md | 25 ++- .../Documentation~/Interactions.md | 112 +++++----- .../Documentation~/Joystick.md | 8 +- .../Documentation~/Keyboard.md | 50 ++--- .../Documentation~/Layouts.md | 112 +++++----- .../Documentation~/Migration.md | 102 ++++----- .../Documentation~/Mouse.md | 32 ++- .../Documentation~/OnScreen.md | 31 ++- .../Documentation~/Pen.md | 37 ++- .../Documentation~/Pointers.md | 12 +- .../Documentation~/Processors.md | 69 +++--- .../Documentation~/QuickStartGuide.md | 44 ++-- .../Documentation~/Sensors.md | 38 ++-- .../Documentation~/Settings.md | 81 ++++--- .../Documentation~/SupportedDevices.md | 49 ++-- .../Documentation~/TableOfContents.md | 42 ++-- .../Documentation~/Testing.md | 31 +-- .../Documentation~/Touch.md | 55 ++--- .../Documentation~/UISupport.md | 42 ++-- .../Documentation~/UseInEditor.md | 16 +- .../Documentation~/UserManagement.md | 32 +-- .../Documentation~/index.md | 4 +- 36 files changed, 1206 insertions(+), 1191 deletions(-) delete mode 100644 Packages/com.unity.inputsystem/Documentation~/Images/CreateInputActions.png diff --git a/Packages/com.unity.inputsystem/Documentation~/ActionAssets.md b/Packages/com.unity.inputsystem/Documentation~/ActionAssets.md index 555004124b..f623795be7 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ActionAssets.md +++ b/Packages/com.unity.inputsystem/Documentation~/ActionAssets.md @@ -1,123 +1,125 @@ # Input Action Assets -* [Creating action assets](#creating-input-action-assets) -* [Editing action assets](#editing-input-action-assets) -* [Using action assets](#using-input-action-assets) +* [Creating Action Assets](#creating-input-action-assets) +* [Editing Action Assets](#editing-input-action-assets) +* [Using Acion Assets](#using-input-action-assets) -An "input action asset" is an asset containing [input actions](Actions.md) as well as their associated [bindings](ActionBindings.md) and [control schemes](ActionBindings.md#control-schemes). These assets are distinguished by the `.inputactions` file extension and are stored in a plain JSON format. +An Input Action Asset is an Asset containing [Input Actions](Actions.md) as well as their associated [Bindings](ActionBindings.md) and [Control Schemes](ActionBindings.md#control-schemes). These Assets are distinguished by the `.inputactions` file extension and are stored in a plain JSON format. ## Creating Input Action Assets -To create an asset containing [input actions](Actions.md) in Unity, right-click in the Project window or open the `Assets` entry in Unity's main menu. From there, select `Create >> Input Actions`. - -![Create Input Actions](Images/CreateInputActions.png) +To create an Asset containing [Input Acions](Actions.md) in Unity, right-click in the __Project__ window or go to __Assets > Create > Input Actions__ in Unity's main menu. ## Editing Input Action Assets -To bring up the action editor, double-click an `.inputactions` asset in the Project Browser or click the "Edit asset" button in the inspector for the asset. Multiple action editor windows can be open concurrently (not on the same asset, though). +To bring up the Action editor, double-click an `.inputactions` asset in the Project Browser or click 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. ![Action Editor Window](Images/MyGameActions.png) -The action editor comes up as a separate window which can optionally be docked into Unity's main UI. +The Action editor comes up as a separate window which you can also dock into Unity's main UI. + +>__Note__: For details about how Action Maps, Actions, and Bindings work, see the documentation on [Actions](Actions.md). ->NOTE: For details about how action maps, actions, and bindings work, see the documentation on [actions](Actions.md). +By default, Unity doesn't save edits you make in the Action Asset window when you save the Project. To save your changes, click __Save Asset__ in the window's toolbar. To discard your changes, close the window and choose __Don't Save__ when prompted. Alternatively, you can toggle auto-saving on by enabling the __Auto-Save__ checkbox in the toolbar. This saves any changes to that Asset. -Edits made in the action asset window are not saved automatically with the project by default. To save your changes, click `Save Asset` in the window's toolbar. To discard your changes, close the window and choose `Don't Save`. Alternatively, auto-saving can be toggled on by ticking the `Auto-Save` checkbox in the toolbar. This will cause any change to the asset to automatically be persisted back to disk. This setting will take effect for all `.inputactions` assets and will persist across editor sessions. +>__Note__: This setting affects all `.inputactions` Assets, and persists across Unity Editor sessions. The editor window is divided into three panes. -1. The left pane lists the "action maps" in the asset. Each map is a collection of actions that can be enabled and disabled in bulk. -2. The middle pane contains the actions in the currently selection action map and the bindings associated with each action. -3. The right pane contains the properties of the currently selected action or binding. +1. The left pane lists the Action Maps in the Asset. Each Map is a collection of Actions that you can enable or disable in bulk. +2. The middle pane contains the Actions in the currently selected Action Map, and the bindings associated with each Action. +3. The right pane contains the properties of the currently selected Action or Binding. -Multiple shorts are available to provide quick access to certain common operations. +Use the following keyboard shortcuts to quickly trigger common operations: |Shortcut (Mac)|Shortcut (Windows)|Description| |--------------|------------------|-----------| -|⌘X, ⌘C, ⌘V|Ctrl-X, Ctrl-C, Ctrl-V|Cut, Copy and Paste. Can be used on actions, action maps and binding.| -|⌘D|Ctrl-D|Duplicate. Can be used on actions, action maps and bindings.| -|⌘⌫|Del|Delete. Can be used on actions, action maps and bindings.| +|⌘X, ⌘C, ⌘V|Ctrl-X, Ctrl-C, Ctrl-V|Cut, Copy and Paste. Can be used on Actions, Action Maps and Bindings.| +|⌘D|Ctrl-D|Duplicate. Can be used on Actions, Action Maps and Bindings.| +|⌘⌫|Del|Delete. Can be used on Actions, Action Maps and Bindings.| |⌥S|Alt-S|Save.| |⌥M|Alt-M|Add Action Map.| |⌥A|Alt-A|Add Action.| |⌥B|Alt-B|Add Binding.| ->Pro Tip: You can search quickly by devices and/or control schemes directly from the search box. "d:gamepad" filters for bindings to gamepad devices whereas "g:gamepad" filters for bindings in the gamepad control scheme. Matching is case-insensitive and will match any partial name. +>__Tip__: You can search for Devices and/or Control Schemes directly from the search box. For example, "d:gamepad" filters for bindings to gamepad Devices, whereas "g:gamepad" filters for bindings in the "gamepad" Control Scheme. Matching is case-insensitive and will match any partial name. ### Editing Action Maps ![Action Maps Column](Images/ActionMapsColumn.png) ->NOTE: Action map names should not contain slashes (`/`). +>__Note__: Action Map names can't contain slashes (`/`). -* To add a new action map, click the plus icon in the header of the action map column. -* To rename an existing map, either long-click the name or right-click the action map and select "Rename" from the context menu. -* To delete an existing map, either right-click it and select "Delete" from the context menu or use the Delete key (Windows) / ⌘⌫ (Mac). -* To duplicate an existing map, either right-click it and select "Duplicate" or use Ctrl-D (Windows) / ⌘D (Mac). +* To add a new Action Map, click the plus icon in the header of the Action Map column. +* To rename an existing Action Map, either long-click the name, or right-click the action map and select __Rename__ from the context menu. +* To delete an existing Action Map, either right-click it and select __Delete__ from the context menu, or use the Delete key (Windows) / ⌘⌫ (Mac). +* To duplicate an existing Action Map, either right-click it and select __Duplicate__ from the context menu, or use Ctrl-D (Windows) / ⌘D (Mac). ### Editing Actions ![Action Column](Images/ActionColumn.png) -* To add a new action, click the plus 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 or use the Delete key (Windows) / ⌘⌫ (Mac). -* To duplicate an existing action, either right-click it and select "Duplicate" or use Ctrl-D (Windows) / ⌘D (Mac). +* To add a new Action, click the plus 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, or use the Delete key (Windows) / ⌘⌫ (Mac). +* To duplicate an existing Action, either right-click it and select __Duplicate__ from the context menu, or use Ctrl-D (Windows) / ⌘D (Mac). -If you select an action you can edit it's properties in the right hand pane of the window: +If you select an Action, you can edit it's properties in the right-hand pane of the window: ![Action Properties](Images/ActionProperties.png) ### Editing Bindings -* To add a new binding, click the plus icon on the action you want to add it to, and select the binding type fron the popup menu. -* To delete an existing binding, either right-click it and select "Delete" from the context menu or use the Delete key (Windows) / ⌘⌫ (Mac). -* To duplicate an existing binding, either right-click it and select "Duplicate" or use Ctrl-D (Windows) / ⌘D (Mac). +* To add a new Binding, click the plus 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, or use the Delete key (Windows) / ⌘⌫ (Mac). +* To duplicate an existing Binding, either right-click it and select __Duplicate__ from the context menu, or use Ctrl-D (Windows) / ⌘D (Mac). -If you select an action you can edit it's properties in the right hand pane of the window: +If you select a Binding, you can edit its properties in the right-hand pane of the window: ![Binding Properties](Images/BindingProperties.png) #### Picking Controls -The most important property of any binding is the [control path](Controls.md#control-paths) it is bound to. To edit it, click on the popup button for the `Path` property. This will pop up a Control Picker window. +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 will pop up a Control picker window. ![Control Picker](Images/InputControlPicker.png) -In the control picker window, you can explore a tree of input devices and controls known to the input system to bind to. This list will be filtered by the action's [`Control Type`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_expectedControlType) property, so if the control type is `Vector2`, you will only be able to select any control which generates two-dimensional values (like a stick). The device and control tree is organized hierarchically from generic to specific. So, you can for instance navigate to "Gamepad", and choose the control path `/buttonSouth`. This will then match the lower action button on any gamepad. But you can also navigate to "Gamepad", and from there scroll down to "More specific Gamepads" and select "PS4 Controller", and then choose the control path `/buttonSouth`. This will then only match the "cross" button on PlayStation gamepads, and not match any other gamepads. +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, navigate to __Gamepad__, and choose the Control path `/buttonSouth`, this matches the lower action button on any gamepad. On the other hand, if you navigate to __Gamepad__, then scroll down to __More Specific Gamepads__ and select __PS4 Controller__, and then choose the Control path `/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 is often easier to simply let the input system listen for input. To do that, click the "Listen" button. The list of controls will first be empty. Now you can start clicking buttons or actuating controls on the devices you want to bind to. The control picker window will list any bindings which would match the controls you pressed, and you can click on one to choose it. +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, click the __Listen__ button. At first, the list of Controls is empty. Once you start clicking 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. Click any of these Bindings to select it. -Finally, you can choose to manually edit the binding path, instead of using the control picker. To do that, you can click the "T" button next to the control path popup. This will switch the popup to a text field, where you can enter any binding string. The advantage of doing this is that you are allowed to use wildcard (`*`) characters in your bindings. So you can for instance use a binding path such as `/touch*/press` to bind to any finger being pressed on the touchscreen (instead of manually binding to `/touch0/press`, `/touch1/press`, etc..). +Finally, you can choose to manually edit the Binding path, instead of using the Control picker. To do that, click 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 `/touch*/press` to bind to any finger being pressed on the touchscreen, instead of manually binding to `/touch0/press`, `/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. You can learn more about how composites works and which types of composites there are [here](ActionBindings.md#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, click the plus icon on the action you want to add it to, and select the composite binding type fron the popup menu. This will create multiple bindings 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 does not have a binding path property, but it's individual parts do - and those can be edited like any other binding. Once you have bound all the composite's parts, the composite can work together as if you bound a single control to the action. +To create a Composite Binding, in the Input Action Asset editor window, click the plus 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. ### 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. +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. ![Control Scheme Properties](Images/ControlSchemeProperties.png) -To see the control schemes in the input action asset editor window, click the control scheme popup button in the top left of the window. This popup menu lets you add or remove control schemes to your asset. If your asset contains any control schemes, you can select a control scheme, and then the window will only show bindings belong to that scheme. If you select a binding, you will now be able to 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…" from the popup), a little window will open which lets you edit the name of the control scheme and which devices the scheme should be active for. +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 Asset. If the Asset contains any Control Schemes, you can select a Control Scheme, and then the window only shows bindings that belong to 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 click __Edit Control Scheme…__, you can edit the name of the Control Scheme and which devices the Scheme should be active for. ## Using Input Action Assets -### Auto-Generating Script Code for Actions +### Auto-generating script code for Actions -One of the most convenient ways to work with `.inputactions` assets in script is to generate a C# wrapper class for them automatically. This obviates the need for manually looking up actions and maps using their names and also provides easier ways for setting up callbacks. +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, tick the `Generate C# Class` in the importer properties in the inspector of the `.inputactions` asset when selected in Unity and hit "Apply". +To enable this option, tick the __Generate C# Class__ checkbox in the importer properties in the Inspector of the `.inputactions` Asset, then click __Apply__. ![MyPlayerControls Importer Settings](Images/FireActionInputAssetInspector.png) -(You can optionally choose a path name, and a class name and namespace for the generated script, or you can keep the defaults.) +You can optionally choose a path name, class name, and namespace for the generated script, or keep the default values. -This will generate a C# script that makes working with the asset a lot simpler. +This generates a C# script that simplifies working with the Asset. ```CSharp using UnityEngine; @@ -166,6 +168,6 @@ public class MyPlayerScript : MonoBehaviour, IGameplayActions ### Using Action Assets with `PlayerInput` -The [`PlayerInput` component](Components.md#playerinput-component) provides a convenient way to handle input for one or multiple players. It requires you to set up all your actions in an Input Action Asset, which you can then assign to the [`PlayerInput`](Components.md#playerinput-component) component. [`PlayerInput`](Components.md#playerinput-component) can then automatically handle activating action maps and selecting control schemes for you. Check the docs on [GameObject Components for Input](Components.md) to learn mode. +The [`PlayerInput`](Components.md#playerinput-component) component provides a convenient way to handle input for one or multiple players. It requires you to set up all your Actions in an Input Action Asset, which you can then assign to the [`PlayerInput`](Components.md#playerinput-component) component. [`PlayerInput`](Components.md#playerinput-component) can then automatically handle activating Action Maps and selecting Control Schemes for you. Check the documentation on [GameObject Components for Input](Components.md) to learn more. ![PlayerInput](Images/PlayerInput.png) diff --git a/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md b/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md index c5e986a0f1..d9f7f58bef 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md +++ b/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md @@ -1,35 +1,35 @@ # Input Bindings -An [`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html) represents a connection between an action and one or more controls identified by a [control path](Controls.md#control-paths). An action can have arbitrary many bindings pointed at it and the same control may be referenced by multiple bindings. +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). An Action have an arbitrary number of Bindings pointed at it. Multiple Bindings can reference the same Control. -Each binding has the following properties: +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 input should be received.

Example: `"/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, meaning that it can be used to non-destructively override the path on a binding. If it is set to something other than null, it will take effect and override `path`. If you want to get the path which is currently being used (ie, 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 should be triggered from the binding. Note that this can be null or empty (e.g. for [composites](#composite-bindings)). Case-insensitive.

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). Case-insensitive.

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 interactions applied to the [action](Actions.md) itself (if any) will get appended to this list. Case-insensitive.

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 processors applied to the [action](Actions.md) itself (if any) will get appended to this list. Case-insensitive.

Note that processors applied to bindings apply __in addition__ to processors applied to controls that are providing values. If, for example, you put a `stickDeadzone` processor on a binding and then bind it to `/leftStick`, you will get deadzones applied twice, once from the deadzone processor sitting on the `leftStick` control and once from the binding.

Example: `"invert;axisDeadzone(min=0.1,max=0.95)"`| -|[`id`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_id)|Unique ID of the binding. Can be used, for example, to identify the binding when storing binding overrides in user settings.| -|[`name`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_name)|Optional name of the binding. Most importantly used to identify part names inside [composites](#composite-bindings).

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).| - -The bindings to a particular action can be queried from the action using [`InputAction.bindings`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_bindings). A flat list of bindings for all actions in a map can be queried from an action map using [`InputActionMap.bindings`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_bindings). +|[`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.

Example: `"/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, meaning that it can be used to non-destructively override the path on a Binding. If it is set to something other than null, it will take effect and override `path`. If you want to get the path which is currently being used (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)). Case-insensitive.

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). Case-insensitive.

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. Case-insensitive.

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. Case-insensitive.

Processors applied to Bindings apply in addition to Processors applied to Controls that are providing values. If, for example, you put a `stickDeadzone` Processor on a Binding and then bind it to `/leftStick`, you will get deadzones applied twice: once from the deadzone Processor sitting on the `leftStick` Control and once from the Binding.

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. Most importantly used to identify part names inside [Composites](#composite-bindings).

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).| + +You can query the Bindings to a particular Action using [`InputAction.bindings`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_bindings). You can also query a flat list of Nindings for all Actions in an Action Map using [`InputActionMap.bindings`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_bindings). ## Composite Bindings -Sometimes it is desirable to have several controls act in unison to mimick 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 using two keys to form a 1D axis equivalent to a mouse scroll axis. +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. -The problem is that with "normal" bindings, this cannot be solved easily. It is possible to bind a [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) to an action expecting a `Vector2` but doing so will result in an exception at runtime when trying to read a `Vector2` from a control that can deliver only a `float`. +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 will result in an exception at runtime when trying to read a `Vector2` from a Control that can deliver only a `float`. -This problem is solved by "composite bindings", i.e. bindings that are made up of other bindings. Composites themselves do not bind directly to controls but rather source values from other bindings that do and synthesize input on the fly from those values. +Composite Bindings (that is, Bindings that are made up of other Bindings) solve this problem. Composites themselves don't bind directly to Controls, but rather 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 [here](ActionAssets.md#editing-composite-bindings). +To see how to create Composites in the editor UI, see documentation on [editing Composite Bindings](ActionAssets.md#editing-composite-bindings). -In code, composites can be created using the [`AddCompositeBinding`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.html#UnityEngine_InputSystem_InputActionSetupExtensions_AddCompositeBinding_UnityEngine_InputSystem_InputAction_System_String_System_String_) syntax. +In code, you can create Composites using the [`AddCompositeBinding`](../api/UnityEngine.InputSystem.InputActionSetupExtensions.html#UnityEngine_InputSystem_InputActionSetupExtensions_AddCompositeBinding_UnityEngine_InputSystem_InputAction_System_String_System_String_) syntax. ```CSharp myAction.AddCompositeBinding("Axis") @@ -37,19 +37,19 @@ myAction.AddCompositeBinding("Axis") .With("Negative", "/leftTrigger"); ``` -Each composite is comprised of one binding with set to true and then one or more bindings immediately following it that have [`InputBinding.isPartOfComposiste`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_isPartOfComposite) set to true. This means that 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. +Each Composite consists of one Binding that has [`InputBinding.isComposiste`](../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. -Composites can have parameters, just like [interactions](Interactions.md) and [processors](Processors.md). +Composites can have parameters, just like [Interactions](Interactions.md) and [Processors](Processors.md). ```CSharp myAction.AddCompositeBinding("Axis(wichSideWins=1)"); ``` -There are currently four composite types that come with the system out of the box: [1D-Axis](#1d-axis), [2D-Vector](#2d-vector), [Button With One Modifier](#button-with-one-modifier) and [Button With Two Modifiers](#button-with-two-modifiers). +There are currently four Composite types that come with the system out of the box: [1D-Axis](#1d-axis), [2D-Vector](#2d-vector), [Button With One Modifier](#button-with-one-modifier) and [Button With Two Modifiers](#button-with-two-modifiers). -### 1D Axis +### 1D axis -A composite made up of two buttons, one pulling a 1D axis in its negative direction and one pulling it in its positive direction. Implemented in the [`AxisComposite`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html) class. The result is a `float`. +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" @@ -57,14 +57,14 @@ myAction.AddCompositeBinding("1DAxis") // Or just "Axis" .With("Negative", "/leftTrigger"); ``` -The axis composite has two part bindings. +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, i.e. 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, i.e. towards [`minValue`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_minValue).| +|[`positive`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_positive)|`Button`|Controls pulling in the positive direction, that is, 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, that is, towards [`minValue`](../api/UnityEngine.InputSystem.Composites.AxisComposite.html#UnityEngine_InputSystem_Composites_AxisComposite_minValue).| -You can set the following parameters on an axis composite: +You can set the following parameters on an axis Composite: |Parameter|Description| |---------|-----------| @@ -72,19 +72,19 @@ You can set the following parameters on an axis composite: |[`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. +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.

This is the default.| -|(1) `Positive`|The positive side has precedence and the composite returns `maxValue`.| -|(2) `Negative`|The negative side has precedence and the composite returns `minValue`.| +|(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.

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`.| -### 2D Vector +### 2D vector -A composite representing a 4-way button setup akin to the d-pad on gamepads with each button representing a cardinal direction. Implemented in the [`Vector2Composite`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html) class. The result is a `Vector2`. +A Composite that represents a 4-way button setup like the D-pad on gamepads, with each button representing 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 controls such as WASD. +This Composite is most useful for representing controls such as WASD keyboard input. ```CSharp myAction.AddCompositeBinding("2DVector") // Or "Dpad" @@ -94,24 +94,24 @@ myAction.AddCompositeBinding("2DVector") // Or "Dpad" .With("Right", "/d"); ``` -The 2D vector composite has four part bindings. +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)`, i.e. +Y.| -|[`down`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_down)|`Button`|Controls representing `(0,-1)`, i.e. -Y.| -|[`left`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_left)|`Button`|Controls representing `(-1,0)`, i.e. -X.| -|[`right`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_right)|`Button`|Controls representing `(1,0)`, i.e. X.| +|[`up`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_up)|`Button`|Controls representing `(0,1)`, that is, +Y.| +|[`down`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_down)|`Button`|Controls representing `(0,-1)`, that is, -Y.| +|[`left`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_left)|`Button`|Controls representing `(-1,0)`, that is, -X.| +|[`right`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_right)|`Button`|Controls representing `(1,0)`, that is, X.| -In addition, you can set the following parameters on a 2D vector composite: +In addition, you can set the following parameters on a 2D vector Composite: |Parameter|Description| |---------|-----------| -|[`normalize`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_normalize)|Whether the resulting vector should be normalized or not. If this is disabled, then, for example, pressing both [`up`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_up) and [`right`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_right) will yield a vector `(1,1)` which has a length greater than one. This can be undesirable in situations where the vector's magnitude matterse. E.g. when scaling running speed by the length of the input vector.

This is true by default.| +|[`normalize`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_normalize)|Whether the resulting vector should be normalized or not. If this is disabled, then, for example, pressing both [`up`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_up) and [`right`](../api/UnityEngine.InputSystem.Composites.Vector2Composite.html#UnityEngine_InputSystem_Composites_Vector2Composite_right) will yield a vector `(1,1)` which has a length greater than 1. This can be undesirable in situations where the vector's magnitude matters (for example, when scaling running speed by the length of the input vector).

This is true by default.| -### Button With One Modifier +### Button with one modifier -A composite that requires another button to be held when pressing the button that triggers the action. Implemented in the [`ButtonWithOneModifier`](../api/UnityEngine.InputSystem.Composites.ButtonWithOneModifier.html) class. This is useful, for example, to represent keyboard shortcuts such as "CTRL+1" but is not restricted to keyboard controls, i.e. the buttons can be on any device and may be toggle buttons or full-range buttons like the gamepad triggers. +A Composite that requires another button to be held when pressing the button that triggers the Action. Implemented in the [`ButtonWithOneModifier`](../api/UnityEngine.InputSystem.Composites.ButtonWithOneModifier.html) class. This is useful, for example, to represent keyboard shortcuts such as Ctrl+1 but isn't restricted to keyboard controls. The buttons can be on any Device, and can be toggle buttons or full-range buttons such as gamepad triggers. The result is a `float`. @@ -122,18 +122,18 @@ myAction.AddCompositeBinding("ButtonWithOneModifier") .With("Modifier", "/rightCtrl"); ``` -The Button With One Modifier composite has two part bindings. +The button with one modifier Composite has two part Bindings. |Part|Type|Description| |----|----|-----------| -|[`modifier`](../api/UnityEngine.InputSystem.Composites.ButtonWithOneModifier.html#UnityEngine_InputSystem_Composites_ButtonWithOneModifier_modifier)|`Button`|Modifier that has to be held for `button` to come through. If any of the buttons bound to the `modifier` part is pressed, the composite will assume the value of the `button` binding. If none of the buttons bound to the `modifier` part is pressed, the composite has a zero value.| -|[`button`](../api/UnityEngine.InputSystem.Composites.ButtonWithOneModifier.html#UnityEngine_InputSystem_Composites_ButtonWithOneModifier_button)|`Button`|The button whose value the composite will assume while `modifier` is pressed.| +|[`modifier`](../api/UnityEngine.InputSystem.Composites.ButtonWithOneModifier.html#UnityEngine_InputSystem_Composites_ButtonWithOneModifier_modifier)|`Button`|Modifier that has to be held for `button` to come through. If any of the buttons bound to the `modifier` part is pressed, the Composite assumes the value of the `button` Binding. If none of the buttons bound to the `modifier` part are pressed, the Composite has a value of 0.| +|[`button`](../api/UnityEngine.InputSystem.Composites.ButtonWithOneModifier.html#UnityEngine_InputSystem_Composites_ButtonWithOneModifier_button)|`Button`|The button whose value the Composite will assume while `modifier` is pressed.| -The Button With One Modifier composite does not have parameters. +This Composite has no parameters. -### Button With Two Modifiers +### Button with two modifiers -A composite that requires two other buttons to be held when pressing the button that triggers the action. Implemented in the [`ButtonWithTwoModifiers`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html) class. This is useful, for example, to represent keyboard shortcuts such as "CTRL+SHIFT+1" but is not restricted to keyboard controls, i.e. the buttons can be on any device and may be toggle buttons or full-range buttons like the gamepad triggers. +A Composite that requires two other buttons to be held when pressing the button that triggers the Action. Implemented in the [`ButtonWithTwoModifiers`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html) class. This is useful, for example, to represent keyboard shortcuts such as "Ctrl+Shift+1" but isn't restricted to keyboard controls. The buttons can be on any Device, and can be toggle buttons or full-range buttons such as gamepad triggers. The result is a `float`. @@ -146,21 +146,21 @@ myAction.AddCompositeBinding("ButtonWithTwoModifiers") .With("Modifier2", "/rightShift"); ``` -The Button With Two Modifiers composite has three part bindings. +The button with two modifiers Composite has three part Bindings. |Part|Type|Description| |----|----|-----------| -|[`modifier1`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html#UnityEngine_InputSystem_Composites_ButtonWithTwoModifiers_modifier1)|`Button`|First modifier that has to be held for `button` to come through. If none of the buttons bound to the `modifier1` part is pressed, the composite has a zero value.| -|[`modifier2`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html#UnityEngine_InputSystem_Composites_ButtonWithTwoModifiers_modifier2)|`Button`|Second modifier that has to be held for `button` to come through. If none of the buttons bound to the `modifier2` part is pressed, the composite has a zero value.| -|[`button`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html#UnityEngine_InputSystem_Composites_ButtonWithTwoModifiers_button)|`Button`|The button whose value the composite will assume while both `modifier1` and `modifier2` are pressed.| +|[`modifier1`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html#UnityEngine_InputSystem_Composites_ButtonWithTwoModifiers_modifier1)|`Button`|First modifier that has to be held for `button` to come through. If none of the buttons bound to the `modifier1` part is pressed, the composite has a value of 0.| +|[`modifier2`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html#UnityEngine_InputSystem_Composites_ButtonWithTwoModifiers_modifier2)|`Button`|Second modifier that has to be held for `button` to come through. If none of the buttons bound to the `modifier2` part is pressed, the composite has a value of 0.| +|[`button`](../api/UnityEngine.InputSystem.Composites.ButtonWithTwoModifiers.html#UnityEngine_InputSystem_Composites_ButtonWithTwoModifiers_button)|`Button`|The button whose value the Composite assumes while both `modifier1` and `modifier2` are pressed.| -The Button With Two Modifiers composite does not have parameters. +This Composite has no parameters. -### Writing Custom Composites +### Writing custom Composites -New types of composites can be defined and registered with the API. They are treated the same as predefined types — which are internally defined and registered the same way. +You can define new types of Composites, and register them with the API. Unity treats these the same as predefined types, which are internally defined and registered the same way. -To define a new type of composite, create a class based on [`InputBindingComposite`](../api/UnityEngine.InputSystem.InputBindingComposite-1.html). +To define a new type of Composite, create a class based on [`InputBindingComposite`](../api/UnityEngine.InputSystem.InputBindingComposite-1.html). ```CSharp // Use InputBindingComposite as a base class for a composite that returns @@ -227,7 +227,7 @@ public class CustomComposite : InputBindingComposite } ``` -The composite should now show up in the editor UI when adding a binding and it can now be used in scripts. +The Composite should now appear in the editor UI when adding a Binding, and you can now use it in scripts. ```CSharp myAction.AddCompositeBinding("custom(floatParameter=2.0)") @@ -235,7 +235,7 @@ The composite should now show up in the editor UI when adding a binding and it c .With("secondpart", "/buttonNorth"); ``` -It is also possible to define a custom parameter editor for the composite by deriving from [`InputParameterEditor`](../api/UnityEngine.InputSystem.Editor.InputParameterEditor-1.html). +You can also define a custom parameter editor for the Composite by deriving from [`InputParameterEditor`](../api/UnityEngine.InputSystem.Editor.InputParameterEditor-1.html). ```CSharp #if UNITY_EDITOR @@ -250,23 +250,25 @@ public class CustomParameterEditor : InputParameterEditor #endif ``` -## Binding Resolution +## Binding resolution -When the input system accesses the [controls](Controls.md) bound to an action for the first time, the action will "resolve" the action's bindings to match them to existing controls on existing devices. In this process, the action will call [`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 will then result in a list of resolved controls now bound to the action. Note that a single [binding path](Controls.md#control-paths) can match multiple controls: +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. -* A specific device path such as `/buttonEast` will match the "circle button" on a [PlayStation controllers](Gamepad.md#playstation-controllers). If you have multiple PlayStation controllers connected, it will resolve to the "circle button" on each of these controllers. +Note that a single [Binding path](Controls.md#control-paths) can match multiple Controls: -* An abstract device path such as `/buttonEast` will match the right action button on any connected gamepad. If you have a PlayStation controller and an [Xbox controller](Gamepad.md#xbox) connected, it will resolve to the "circle button" on the PlayStation controller, and to the "B Button" on the Xbox controller. +* A specific Device path such as `/buttonEast` matches the "circle button" on a [PlayStation controllers](Gamepad.md#playstation-controllers). If you have multiple PlayStation controllers connected, it resolves to the "circle" button on each of these controllers. -* A binding path can also contain wildcards, such as `/button*`. This will match any control on any gamepad with a name starting with "button", which will match all the four action buttons on any connected gamepad. A different example: `*/{Submit}` will match any control tagged with the "Submit" [usage](Controls.md#control-usages) on any device. +* An abstract Device path such as `/buttonEast` matches the right action button on any connected gamepad. If you have a PlayStation controller and an [Xbox controller](Gamepad.md#xbox) connected, it resolves the "circle button" on the PlayStation controller, and to the "B Button" on the Xbox controller. -The controls that an action has resolved to can be queried from the action using [`InputAction.controls`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_controls). This can also be done when the action has not yet been enabled. +* A Binding path can also contain wildcards, such as `/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. -### Choosing Which Devices to Use +You can query the Controls that an Action resolves to using [`InputAction.controls`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_controls). You can also run this query if the Action is disabled. -By default, actions will resolve their bindings against all devices present in the system (i.e. [`InputSystem.devices`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_devices)). This means that, for example, if there are two gamepads present in the system, a binding to `/buttonSouth` will pick up __both__ gamepads and alows the action to be used from either. +### Choosing which Devices to use -This behavior can be overridden by restricting [`InputActionAssets`](../api/UnityEngine.InputSystem.InputActionAsset.html) or individual [`InputActionMaps`](../api/UnityEngine.InputSystem.InputActionMap.html) to a specific set of devices. If this is done, binding resolution will take only the controls of the given devices into account. +By default, Actions will 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 `/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(); @@ -275,23 +277,25 @@ This behavior can be overridden by restricting [`InputActionAssets`](../api/Unit actionMap.devices = new[] { Gamepad.all[0] }; ``` ->NOTE: [`InputUser`](UserManagement.md) and [`PlayerInput`](Components.md) make use of this facility automatically. I.e. they will set [`InputActionMap.devices`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_devices) automatically based on the devices that are paired to the user/player. +>__Note__: [`InputUser`](UserManagement.md) and [`PlayerInput`](Components.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. ## Disambiguation -If multiple controls are bound to an action, the input system will monitor input from each bound control to feed the action. But then, how does the system decide which of the bound controls to use for the value of the action? For instance if you have a binding to `/leftStick`, and you have multiple connected gamepads, which gamepad's stick will provide the input value for the action? We call this control the control which is "driving the action". Which control is currently driving the action is decided in a process called "disambiguation". During the disambiguation process, the input system looks at the value of each control bound to an action. If the [magnitude](Controls.md#control-actuation) of the input from any control is higher then the magnitude of the control currently driving the action, then the control with the higher magnitude becomes the new control driving the action. So in the above example of `/leftStick` binding to multiple gamepads, the control driving the action will always be the left stick which is actuated the furthest of all the gamepads. You can query which control is currently driving the action by checking the [`InputAction.CallbackContext.control`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html#UnityEngine_InputSystem_InputAction_CallbackContext_control) property in an [action callback](Actions.md#started-performed-and-canceled-callbacks). +If multiple Controls are bound to an Action, the Input System monitors input from each bound Control to feed the Action. But then, how does the system decide which of the bound Controls to use for the value of the Action? For instance, if you have a Binding to `/leftStick`, and you have multiple connected gamepads, which gamepad's stick will provide the input value for the Action? We call this Control the Control which is driving the Action. + +Unity decides which Control is currently driving the Action in a process called disambiguation. During the disambiguation process, the Input System looks at the value of each Control bound to an Action. If the [magnitude](Controls.md#control-actuation) of the input from any Control is higher then the magnitude of the Control currently driving the Action, then the Control with the higher magnitude becomes the new Control driving the Action. In the above example of `/leftStick` binding to multiple gamepads, the Control driving the Action is the left stick which is actuated the furthest of all the gamepads. You can query which Control is currently driving the Action by checking the [`InputAction.CallbackContext.control`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html#UnityEngine_InputSystem_InputAction_CallbackContext_control) property in an [Action callback](Actions.md#started-performed-and-canceled-callbacks). -If yo don't want your action to perform disambiguation, you can set your action type to [Pass-Through](Actions.md#pass-through). Pass-Through actions skip disambiguation, and are trigged by changes to any bound control. The value of a Pass-Through action will always be the value of whichever bound control changed the last. +If you don't want your Action to perform disambiguation, you can set your Action type to [Pass-Through](Actions.md#pass-through). Pass-Through Actions skip disambiguation, changes to any bound Control trigger them. The value of a Pass-Through Action is the value of whichever bound Control changed most recently. -## Initial State Check +## Initial state check -Actions with the type set to [Value](Actions.md#value) will perform an initial state check when they are first enabled to check the current state of any bound control, and set the action's value to the highest value of any bound control. +Actions with the type set to [Value](Actions.md#value) perform an initial state check when they are first enabled to check the current state of any bound Control, and set the Action's value to the highest value of any bound Control. -Actions with the type set to [Button](Actions.md#button) will not perform any initial state check, so that only buttons pressed after the action was enabled will have any effect on the action. +Actions with the type set to [Button](Actions.md#button) don't perform any initial state check, so that only buttons pressed after the Action was enabled have any effect on the Action. -## Runtime Rebinding +## Run time rebinding -It can be desirable to allow users to choose their own bindings to let them map the controls to match personal preferences. This can be done using 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_) method on an action to create a rebinding operation, which will wait for the input system to register any input to assign to the action as a new binding. Once it detects any control being actuated on any device which matches the action's expected control type, it will then assign the control path for that control to the action's bindings using [`InputBinding.overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath). If multiple controls are actuated, it will choose the control with the highest [magnitude](Controls.md#control-actuation). +To allow users to choose their own Bindings, 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_) method on an Action to create a rebinding operation, which waits for the Input System to register any input to assign to the Action as a new Binding. Once it detects any Control being actuated on any Device which matches the Action's expected Control type, it then assigns the Control path for that Control to the Action's Bindings using [`InputBinding.overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath). If multiple Controls are actuated, the operation chooses the Control with the highest [magnitude](Controls.md#control-actuation). ```C# void RemapButtonClicked(InputAction actionToRebind) @@ -306,19 +310,19 @@ It can be desirable to allow users to choose their own bindings to let them map The [`InputActionRebindingExtensions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) API is highly configurable to match your needs. Among other things, you can: -* Choose expected control types ([`WithExpectedControlType()`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithExpectedControlType_System_Type_)). +* 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_)) +* 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_)) +* 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__)). +* 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. -### Showing Current Bindings +### Showing current Bindings -Both in rebinding UIs as well for on-screen hints during gameplay, it can be useful to know what an action is currently bound to (taking any potentially active rebindings into account). You can use [`InputBinding.effectivePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_effectivePath) to get the currently active path for a binding (ie, either [`path`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_path) or [`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath) if applicable). Then you can use [`InputControlPath.ToHumanReadableString`](../api/UnityEngine.InputSystem.InputControlPath.html#UnityEngine_InputSystem_InputControlPath_ToHumanReadableString_System_String_UnityEngine_InputSystem_InputControlPath_HumanReadableStringOptions_) to turn that into a meaningful control name. +It can be useful for the user to know what an Action is currently bound to (taking any potentially active rebindings into account), both in rebinding UIs as well as 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 (either [`path`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_path) or [`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath), if applicable). You can then use [`InputControlPath.ToHumanReadableString`](../api/UnityEngine.InputSystem.InputControlPath.html#UnityEngine_InputSystem_InputControlPath_ToHumanReadableString_System_String_UnityEngine_InputSystem_InputControlPath_HumanReadableStringOptions_) to turn that into a meaningful control name. ```CSharp m_RebindButtonName.text = InputControlPath.ToHumanReadableString(m_Action.bindings[0].effectivePath); @@ -326,6 +330,6 @@ Both in rebinding UIs as well for on-screen hints during gameplay, it can be use ## Control Schemes -A binding can belong to any number of binding "groups". This is stored on the binding class as a semicolon-separated string, in the [`InputBinding.groups`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_groups) property. This can be used for any arbitrary grouping of bindings. You can enable different sets of binding groups for an [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) or [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html) using the [`InputActionMap.bindingMask`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_bindingMask)/[`InputActionAsset.bindingMask`](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_bindingMask) property. +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. You can enable different sets of binding groups for an [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) or [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html) using 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). -This is used by the input system 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. This is used by the [`PlayerInput`](Components.md) class to enable a matching control scheme for a new [user](UserManagement.md) joining the game, based on the device they are playing on. +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`](Components.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. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/Actions.md b/Packages/com.unity.inputsystem/Documentation~/Actions.md index 9d8ea0959c..bf7e4b2d91 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Actions.md +++ b/Packages/com.unity.inputsystem/Documentation~/Actions.md @@ -2,16 +2,16 @@ * [Overview](#overview) * [Creating Actions](#creating-actions) - * [Using the Action Editor](#using-the-action-editor) + * [Using the Action editor](#using-the-action-editor) * [Embedding Actions in MonoBehaviours](#embedding-actions-in-monobehaviours) * [Loading Actions from JSON](#loading-actions-from-json) - * [Creating Actions in Code](#creating-actions-in-code) + * [Creating Actions in code](#creating-actions-in-code) * [Using Actions](#using-actions) * [Responding to Actions](#responding-to-actions) - * [Action Types](#action-types) + * [Action types](#action-types) * [Debugging Actions](#debugging-actions) - * [Using Actions with Multiple Players](#using-actions-with-multiple-players) -* [Terms and Concepts](#terms-and-concepts) + * [Using Actions with multiple players](#using-actions-with-multiple-players) +* [Terms and concepts](#terms-and-concepts) Related pages: @@ -19,7 +19,7 @@ Related pages: * [Bindings](ActionBindings.md) * [Interactions](Interactions.md) -Input actions are designed to separate the logical meaning of an input from the physical means (i.e. activity on an input device) by which the input is generated. Instead of writing input code like so: +Input Actions are designed to separate the logical meaning of an input from the physical means of input (that is, activity on an input device) that generate the input. Instead of writing input code like this: ```CSharp var look = new Vector2(); @@ -33,57 +33,57 @@ Input actions are designed to separate the logical meaning of an input from the look = mouse.delta.ReadValue(); ``` -You can instead write code that is agnostic to where the input is coming from: +You can write code that is agnostic to where the input is coming from: ```CSharp myControls.gameplay.look.performed += context => look = context.ReadValue(); ``` -The mapping can then be established graphically in the editor: +You can then establish the mapping using the visual editor: ![Look Action Binding](Images/LookActionBinding.png) -This also makes it easier to let players to [customize bindings at runtime](ActionBindings.md#runtime-rebinding). +This also makes it easier to let players [customize bindings at runtime](ActionBindings.md#runtime-rebinding). ->NOTES: ->* Actions are a game-time only feature. They cannot be used in `EditorWindow` code. ->* For an overview of the terms and terminology used on this page, see [Terms and Concepts](#terms-and-concepts). +>__Note__: +>* Actions are a game-time only feature. You can't use them in `EditorWindow` code. +>* For an overview of the terms and terminology used on this page, see [Terms and concepts](#terms-and-concepts). ## Overview -There are three key classes for actions in the API: +There are three key classes for Actions in the API: |Class|Description| |-----|-----------| -|`InputActionAsset`|An asset that contains one or more action maps as well as, optionally, a sequence of control schemes. Details how to create, edit, and work with such assets can be found [here](ActionAssets.md).| -|`InputActionMap`|A named collection of actions.| -|`InputAction`|A named action which will trigger callbacks in response to input.| +|`InputActionAsset`|An Asset that contains one or more Action Maps as well as, optionally, a sequence of Control Schemes. For more information about how to create, edit, and work with these Assets, see [Action Assets](ActionAssets.md).| +|`InputActionMap`|A named collection of Actions.| +|`InputAction`|A named Action that triggers callbacks in response to input.| -The key mechanism by which bindings refer to the inputs they collect is `InputBinding`. More details about bindings and how to use them can be found [here](ActionBindings.md). +The key mechanism by which Actions refer to the inputs they collect is `InputBinding`. 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). Also, each action has a unique ID ([`InputAction.id`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id)) that can be used to reference the action. The ID will remain the same even if the action is renamed. +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)) that 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 be unique within the action asset that the map belongs to (if any; see [`InputActionMap.asset`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_asset)). Also, each action map has a unique ID ([`InputActionMap.id`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_id)) that can be used to reference the map. The ID will remain the same even if the map is renamed. +Each Action Map has a name ([`InputActionMap.name`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_name)) which must be unique within the Action Asset that the Action Map belongs to (if any; see [`InputActionMap.asset`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_asset)). Each Action Map also has a unique ID ([`InputActionMap.id`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_id)) that can be used to reference the Action Map. The ID remains the same even if you rename the Action Map. ## Creating Actions -Actions can be created in a variety of ways: +You can create Actions in one of the following ways: -1. Using the dedicated editor for `.inputactions` assets. +1. Using the dedicated editor for `.inputactions` Assets. 2. By embedding them in MonoBehaviour components. 3. By manually loading them from JSON. -4. By simply creating them directly in code. +4. By creating them directly in code. -### Using the Action Editor +### Using the Action editor -How to create and edit input action assets using the dedicated editor is described on a [separate page](ActionAssets.md). +For information on how to create and edit Input Action Assets using the dedicated editor, see [Action Assets](ActionAssets.md). ![Action Editor Window](Images/MyGameActions.png) ### Embedding Actions in MonoBehaviours -[`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) and [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) can be embedded as fields directly inside `MonoBehaviour` components. In the editor, these fields will receive a custom editor UI. +[`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) and [`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html) can be embedded as fields directly inside `MonoBehaviour` components. ```CSharp public MyBehavior : MonoBehaviour @@ -95,20 +95,20 @@ public MyBehavior : MonoBehaviour } ``` -This is presented in the editor like so: +These fields receive a custom editor UI in the Unity Editor: ![MyBehavior Inspector](Images/MyBehaviorInspector.png) -The editors work similar to the [action asset editor](ActionAssets.md). +The visual editors work similar to the [Action Asset editor](ActionAssets.md). -* To add or remote actions or bindings, click the plus or minus icon in the header. -* To edit binding entries, double-click them.
+* To add or remove Actions or Bindings, click the plus or minus icon in the header. +* To edit Bindings, double-click them.
![InputBinding Inspector](Images/InputBindingInspector.png) -* To edit action entries, double-click them in an InputActionMap, or click the 'gear' icon on individual action properties.
+* To edit Actions, double-click them in an Action Map, or click the gear icon on individual Action properties.
![InputAction Inspector](Images/InputActionInspector.png) -* Entries can also be right-clicked to bring up a context menu and can be dragged around (hold alt to duplicate). +* You can also right-click entries to bring up a context menu, and drag them. Hold the Alt key and drag an entry to duplicate it. -Actions and action maps that are embedded in MonoBehaviour components have to be manually [enabled and disabled](#using-actions). +You must manually [enable and disable](#using-actions) Actions and Action Maps that are embedded in MonoBehaviour components. ```CSharp public class MyBehavior : MonoBehaviour @@ -143,7 +143,7 @@ public class MyBehavior : MonoBehaviour ### Loading Actions from JSON -Actions can be loaded 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. +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 run time in the player. ```CSharp // Load a set of action maps from JSON. @@ -153,9 +153,9 @@ var maps = InputActionMap.FromJson(json); var asset = InputActionAsset.FromJson(json); ``` -### Creating Actions in Code +### Creating Actions in code -Actions can be manually created and configured in code. This also works at runtime in the player. +You can manually create and configure Actions. This also works at run time in the Player. ```CSharp // Create a free-standing actions. @@ -183,7 +183,7 @@ var lookAction = gameplayMap.AddAction("look", "/leftStick"); ## Using Actions -For an action to do something, it must be enabled. This can be done either by individually enabling actions or by enabling them in bulk through action maps. Note that the latter is always more efficient. +For an Action to do something, you must first enable it. You can do this either by individually enabling Actions, or by enabling them in bulk through Action Maps. The second method is more efficient in all scenarios. ```CSharp // Enable a single action. @@ -193,39 +193,39 @@ lookAction.Enable(); gameplayActions.Enable(); ``` -When an action is enabled, all its bindings will be resolved, if this hasn't happened already or if the set of devices usable by the action has changed. For more details about this process, see [here](ActionBindings.md#binding-resolution). +When you enable an action, the Input System resolves its bindings, if this hasn't happened already or if the set of devices usable by the action has changed. For more details about this process, see the documentation on [binding resolution](ActionBindings.md#binding-resolution). -To stop actions or action maps from responding to input, call [`Disable`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_Disable). Note that while actions are enabled, it is not possible to change certain aspects of the configuration (such as their bindings). +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 will actively monitor the [control(s)](Controls.md) it is bound to. If a bound control changes state, the action will process the change and create a response if the state change represents an [interaction](Interactions.md) change. This all happens during the input system update logic. Depending on the [update mode](Settings.md#update-mode) selected in the input settings, this happens once ever frame, or once every fixed update (or, manually if updates are set to manual). +While enabled, an Action actively monitors the [Control(s)](Controls.md) it is bound to. If a bound Control changes state, the Action processes the change and creates a response if the state change represents an [Interaction](Interactions.md) change. 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. ### Responding to Actions -By itself, an action does not represent an actual response to input. Instead, an action tells your code that a certain kind of input has been performed. It is up to your code to in turn respond. +An Action doesn't represent an actual response to input by itself. Instead, an Action informs your code that a certain kind of input has occurred. Your code then responds to this information. There are several ways in which this can be done. -1. Each action has a [`started`, `performed`, and `canceled` callback](#started-performed-and-canceled-callbacks). -2. Each action map has an [`actionTriggered` callback](#inputactionmapactiontriggered-callback). -3. There is a global [`InputSystem.onActionChange` callback](#inputsystemonactionchange-callback). -4. You also can poll the current state of an action whenever you need it using [`InputAction.ReadValue<>()`](#polling-actions). -5. [`InputActionTrace`](#inputactiontrace) can record changes happening on actions. +1. Each Action has a [`started`, `performed`, and `canceled` callback](#started-performed-and-canceled-callbacks). +2. Each Action map has an [`actionTriggered` callback](#inputactionmapactiontriggered-callback). +3. The Input System has a global [`InputSystem.onActionChange` callback](#inputsystemonactionchange-callback). +4. You can poll the current state of an Action whenever you need it using [`InputAction.ReadValue<>()`](#polling-actions). +5. [`InputActionTrace`](#inputactiontrace) can record changes happening on Actions. -There are also higher-level, more streamlined ways of picking up input from actions. One is to use [`PlayerInput`](Components.md#notification-behaviors) and another one is to [generate script code](ActionAssets.md#auto-generating-script-code-for-actions) that wraps around the input actions. +There are also two higher-level, more streamlined ways of picking up input from Actions: using [`PlayerInput`](Components.md#notification-behaviors), or [generating script code](ActionAssets.md#auto-generating-script-code-for-actions) that wraps around the Input Actions. -#### `started`, `performed`, and `canceled` Callbacks +#### `started`, `performed`, and `canceled` callbacks -Every action has a set of dictinct phases it can go through in response to receiving input. +Every Action has a set of distinct phases it can go through in response to receiving input. |Phase|Description| |-----|-----------| -|`Disabled`|The action is disabled and will not receive input.| -|`Waiting`|The action is enabled and is actively waiting for input.| -|`Started`|Input has been received that started an interaction with the action.| -|`Performed`|An interaction with the action has been completed.| -|`Canceled`|An interaction with the action has been canceled.| +|`Disabled`|The Action is disabled and can't receive input.| +|`Waiting`|The Action is enabled and is actively waiting for input.| +|`Started`|The Input System received input that started an Interaction with the Action.| +|`Performed`|An Interaction with the Action has been completed.| +|`Canceled`|An Interaction with the Action has been canceled.| -The current phase of an action can be read using [`InputAction.phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase). +You can read the current phase of an action using [`InputAction.phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase). The `Started`, `Performed`, and `Canceled` phases each have a callback associated with them: @@ -237,13 +237,15 @@ The `Started`, `Performed`, and `Canceled` phases each have a callback associate action.canceled += ctx => /* Action was started */; ``` -Each callback receives an [`InputAction.CallbackContext`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html) structure holding context information that can be used to query the current state of the action and to read out values from controls that triggered the action ([`InputAction.CallbackContext.ReadValue`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html#UnityEngine_InputSystem_InputAction_CallbackContext_ReadValue__1)). Note that the contents of the structure are __only valid for the duration of the callback__. In particular, it is not safe to store the received context and later access its properties from outside the callback. +Each callback receives an [`InputAction.CallbackContext`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html) structure holding context information that you can use to query the current state of the Action and to read out values from Controls that triggered the Action ([`InputAction.CallbackContext.ReadValue`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html#UnityEngine_InputSystem_InputAction_CallbackContext_ReadValue__1)). -When an how the callbacks are triggered depends on the [interactions](Interactions.md) present on the respective bindings. If no interactions are applied to them, the [default interaction](Interactions.md#default-interaction) applies. +>__Note__: The contents of the structure are only valid for the duration of the callback. In particular, it isn't safe to store the received context and later access its properties from outside the callback. -#### `InputActionMap.actionTriggered` Callback +When and how the callbacks are triggered depends on the [Interactions](Interactions.md) present on the respective Bindings. If the bindings have no Interactions that apply to them, the [default Interaction](Interactions.md#default-interaction) applies. -Alternatively, instead of listening to individual actions, you can listen on an entire action map for state changes on any of the actions in the map. +#### `InputActionMap.actionTriggered` callback + +Instead of listening to individual actions, you can listen on an entire Action Map for state changes on any of the Actions in the Action Map. ```CSharp var actionMap = new InputActionMap(); @@ -254,13 +256,13 @@ actionMap.onActionTriggered += context => { ... }; ``` -The argument received is the same `InputAction.CallbackContext` structure that is received through the [`started`, `performed`, and `canceled` callbacks](#started-performed-and-canceled-callbacks). +The argument received is the same `InputAction.CallbackContext` structure that you receive through the [`started`, `performed`, and `canceled` callbacks](#started-performed-and-canceled-callbacks). ->NOTE: The `InputActionMap.actionTriggered` will be called for all three of the individual callbacks on actions, i.e. you get `started`, `performed`, and `canceled` all on a single callback. +>__Note__: The Input System calls `InputActionMap.actionTriggered` for all three of the individual callbacks on Actions. That is, you get `started`, `performed`, and `canceled` all on a single callback. -#### `InputSystem.onActionChange` Callback +#### `InputSystem.onActionChange` callback -Similar to `InputSystem.onDeviceChange`, it is possible to listen for any action-related change globally. +Similar to `InputSystem.onDeviceChange`, your app can listen for any action-related change globally. ```CSharp InputSystem.onActionChange += @@ -279,9 +281,9 @@ InputSystem.onActionChange += } ``` -#### Polling actions +#### Polling Actions -Instead of using callbacks, it may sometimes be simpler to simple poll the value of the action you are interested in where you need it in your code. You can poll the value of an action using [`InputAction.ReadValue<>()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_ReadValue__1): +Instead of using callbacks, it might be simpler sometimes to poll the value of an Action where you need it in your code. You can poll the value of an Action using[`InputAction.ReadValue<>()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_ReadValue__1): ```CSharp public InputAction moveAction; @@ -302,9 +304,9 @@ Instead of using callbacks, it may sometimes be simpler to simple poll the value #### `InputActionTrace` -As when using [`InputEventTrace`](../api/UnityEngine.InputSystem.LowLevel.InputEventTrace.html) for events, actions can be traced in order to generate a log of all activity that happened on a particular set of actions. To do so, use [`InputActionTrace`](../api/UnityEngine.InputSystem.Utilities.InputActionTrace.html). +You can trace Actions in order to generate a log of all activity that happened on a particular set of Actions. To do so, use [`InputActionTrace`](../api/UnityEngine.InputSystem.Utilities.InputActionTrace.html). This behaves in a similar way to [`InputEventTrace`](../api/UnityEngine.InputSystem.LowLevel.InputEventTrace.html) for events. ->NOTE: `InputActionTrace` allocates unmanaged memory and needs to be disposed of in order to not create memory leaks. +>__Note__: `InputActionTrace` allocates unmanaged memory and needs to be disposed of in order to not create memory leaks. ```CSharp var trace = new InputActionTrace(); @@ -356,49 +358,49 @@ trace.UnsubscribeFromAll(); trace.Dispose(); ``` -Once recorded, a trace can be safely read from multiple threads as long as it is not concurrently being written to and as long as the action setup (i.e. the configuration data accessed by the trace) is not concurrently being changed on the main thread. +Once recorded, a trace can be safely read from multiple threads as long as it is not concurrently being written to and as long as the Action setup (that is, the configuration data accessed by the trace) is not concurrently being changed on the main thread. -### Action Types +### Action types -Each action can be one of three different action types. You can select the action type in the Input Action editor window, or by specifying the `type` when parameter when calling the [`InputAction()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction__ctor_System_String_UnityEngine_InputSystem_InputActionType_System_String_System_String_System_String_System_String_) constructor. The action type influences how state changes for the action are processed. The default action type is `Value`. +Each Action can be one of three different Action types. You can select the Action type in the Input Action editor window, or by specifying the `type` parameter when calling the [`InputAction()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction__ctor_System_String_UnityEngine_InputSystem_InputActionType_System_String_System_String_System_String_System_String_) constructor. The Action type influences how the Input System processes state changes for the Action. The default Action type is `Value`. #### Value -This is the default action type. This is recommended to use for any inputs which should track continuous changes to the state of a control. +This is the default Action type. Use this for any inputs which should track continuous changes to the state of a Control. -`Value` type actions continuously monitor all the controls which are bound to the action, and then choose the one which is the most actuated to be the control "driving the action", and report the values from that control in callbacks, triggered whenever the value changes. If a different bound control actuated more, then that control becomes the control driving the action, and values will be reported from that control. This process is called ["Disambiguation"](ActionBindings.md#disambiguation). This is useful if you want to allow different controls to control an action in the game, but only take input from one at the same time. +`Value` type actions continuously monitor all the Controls which are bound to the Action, and then choose the one which is the most actuated to be the Control driving the Action, and report the values from that Control in callbacks, triggered whenever the value changes. If a different bound Control actuated more, then that Control becomes the Control driving the Action, and the Action starts reporting values from that Control. This process is called [disambiguation](ActionBindings.md#disambiguation). This is useful if you want to allow different Controls to control an Action in the game, but only take input from one Control at the same time. -When the action is initially enabled, it will perform an [initial state check](ActionBindings.md#initial-state-check) of all bound controls, and if any of them is actuated, it will trigger a callback with the current value. +When the Action is initially enabled, it will perform an [initial state check](ActionBindings.md#initial-state-check) of all bound Controls. If any of them is actuated, the Action then triggers a callback with the current value. #### Button -This is very similar to `Value`, but `Button` type actions can only be bound to [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) controls, and will not perform an initial state check like described above for `Value` actions. This is recommended to use for any inputs which should trigger an action in the game once every time they are pressed. The initial state check is usually not desirable in such cases, as you don't want to trigger actions because button was still held down from a previous press when the action was enabled. +This is very similar to `Value`, but `Button` type Actions can only be bound to [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) Controls, and don't perform an initial state check like `Value` Actions do (see the Value section above). Use this for inputs that trigger an Action once every time they are pressed. The initial state check is usually not desirable in such cases, as you don't want to trigger actions because the button was still held down from a previous press when the Action was enabled. #### Pass-Through -`Pass-Through` actions bypass the [disambiguation](ActionBindings.md#disambiguation) process described above for `Value` actions. So, for `Pass-Through` actions, the concept of a specific control "driving the action" does not exist. Instead, __any__ change to __any__ bound control will trigger a callback with that control's value. This is useful if you want to process all input from a set of controls. +`Pass-Through` Actions bypass the [disambiguation](ActionBindings.md#disambiguation) process described above for `Value` Actions and don't use the concept of a specific Control driving the Action. Instead, any change to any bound Control triggers a callback with that Control's value. This is useful if you want to process all input from a set of Controls. ### Debugging Actions -You can see currently enabled actions and their bound controls using the [Input Debugger](Debugging.md#debugging-actions). +You can see currently enabled Actions and their bound Controls using the [Input Debugger](Debugging.md#debugging-actions). -You can also use the [`InputActionVisualizer`](Debugging.md#inputactionvisualizer) component from the "Visualizers" sample to get an on-screen visualization of an action's value and interaction state in real-time. +You can also use the [`InputActionVisualizer`](Debugging.md#inputactionvisualizer) component from the Visualizers sample to get an on-screen visualization of an Action's value and Interaction state in real-time. -### Using Actions with Multiple Players +### Using Actions with multiple players -It is possible to use the same action definitions for multiple local players. This setup is useful in a local co-op games, for example. More details about this can be found [here](Components.md#playerinputmanager-component). +You can use the same Action definitions for multiple local players, for example in a local co-op game. For more information, see documentation on the [player input manager](Components.md#playerinputmanager-component) component. -## Terms and Concepts +## Terms and concepts -The following terms and concepts are used through the input action system: +The Input Action system uses the following terms and concepts: |Concept|Description| |-------|-----------| -|[__Action__](Actions.md)|A "logical" input such as "Jump" or "Fire". I.e. an input action that can triggered by a player through one or more input devices and which will run a piece of game logic in response.| -|[__Binding__](ActionBindings.md)|A connection between an action and one or more controls represented by a [control path](Controls.md#control-paths). At runtime, a binding is "resolved" to yield zero or more controls which are then connected to the action.| -|[__Interaction__](Interactions.md)|A distinct input pattern that can be recognized on a control. Interactions trigger actions as they are being recognized.

An example of an interaction is a "hold" which requires a control to be actuated and then held for a certain time before the associated action is triggered.| -|[__Processor__](Processors.md)|An operation that is applied to an input value. An example is "invert" which inverts a floating-point value.| +|[__Action__](Actions.md)|A logical input such as "Jump" or "Fire". That is, an input action that a player can trigger through one or more input devices and runs a piece of game logic in response.| +|[__Binding__](ActionBindings.md)|A connection between an Action and one or more Controls represented by a [control path](Controls.md#control-paths). At run time, a binding is resolved to yield zero or more Controls, which the Input System then connects to the Action.| +|[__Interaction__](Interactions.md)|A distinct input pattern that can be recognized on a Control. An Interaction only triggers an Action when the Input System recognizes the pattern.

For example, a "hold" Interaction requires a Control to be actuated and then held for a certain time before it triggers the associated Action.| +|[__Processor__](Processors.md)|An operation that the Input System applies to an input value. For example, an "invert" Processor inverts a floating-point value.| |[__Phase__](Interactions.md#operation)|An enum describing the current state of an Interaction.| -|[__Control Scheme__](ActionBindings.md#control-schemes)|Lets you define mappings of bindings to different control schemes. Allows you to switch your action maps between different control schemes to enable different subsets of bindings for your actions. Control Schemes can have associated device types, so that they can automatically be enabled for [users](UserManagement.md) when using that type of device.| -|__Action Map__|A named collection of actions. You can simultaneously enable or disable all actions in an action map, so it is useful to group actions in maps by the context they are relevant in (ie. "gameplay").| -|[__Action Asset__](ActionAssets.md)|An asset that contains one or more action maps as well as, optionally, a sequence of control schemes.| +|[__Control Scheme__](ActionBindings.md#control-schemes)|Allows you to define mappings of Bindings to different Control Schemes, and to switch your Action Maps between different Control Schemes to enable different subsets of Bindings for your Actions. Control Schemes can have associated Device types, so that the game can automatically enable them for [users](UserManagement.md) when using that type of Device.| +|__Action Map__|A named collection of Actions. 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 they are relevant in (for example: "gameplay").| +|[__Action Asset__](ActionAssets.md)|An Asset that contains one or more Action Maps as well as, optionally, a sequence of Control Schemes.| diff --git a/Packages/com.unity.inputsystem/Documentation~/Architecture.md b/Packages/com.unity.inputsystem/Documentation~/Architecture.md index 4e2658ef1e..a362d65e6b 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Architecture.md +++ b/Packages/com.unity.inputsystem/Documentation~/Architecture.md @@ -1,27 +1,27 @@ # Architecture -The input system has a layered architecture. Principally, it divides into a low-level and a high-level layer. +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 highly 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 in Unity itself instead, and has implementations for each runtime platform supported by Unity (This is also why some platform-specific input bugs can only be fixed by an update to Unity, and not by a new version of the Input System package). +The foundation of the Input System is the native backend code. This is highly 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 also why some platform-specific input bugs can only be fixed by an update to Unity, and not by a new version of the Input System package. -The Input System interfaces with the native backend using [events](Events.md) which are sent by the native backend. These events notify the system of the creation and removal of input [devices](Devices.md), as well as of any updates to the state of devices. For efficiency and to avoid creating any garbage, the native backends reports the events as a simple buffer of raw, unmanaged memory containing a stream of events. +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 which are interpreted by the native backend and can have different meanings for different device types and platforms. +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 +# Input System (low-level) -The low-level input system code will process and interpret the memory from the event stream provided by the native backend, and dispatch individual events. +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 will create device representations for any newly discovered device in the event stream. For the low-level code, an input device is represented as a block of raw, unmanaged memory. If a state event is received for a device, the data from the state event will be written 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 it's controls. +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. +The low-level system code also contains structs which describe the data layout of commonly known Devices. -# Input System High-Level +# Input System (high-level) -It's the job of the high-level input system code to interpret the data in device's state buffers. To do this, it uses the concept of [layouts](Layouts.md), which describe the data layout of a device and it's controls in memory. Layouts are created 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). +The high-level Input System code interprets the data in 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 will then create [control](Controls.md) representations for each of the devices controls, which let you read the state of each individual control in a device. +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. -The high-level system then also allows you to build another abstraction layer to map input controls to your game mechanics, by using [actions](Actions.md). Actions allow you to [bind](ActionBindings.md) one or multiple controls to an input in your game. The input system will then monitor these controls for state changes, and notify your game logic using [callbacks](Actions.md#responding-to-actions). 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, etc). +The high-level system also allows you to build another abstraction layer to map Input Controls to your game mechanics, by using [Actions](Actions.md). Actions allow you to [bind](ActionBindings.md) one or more Controls to an input in your game. The Input System then monitors these Controls for state changes, and notifies your game logic using [callbacks](Actions.md#responding-to-actions). 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). diff --git a/Packages/com.unity.inputsystem/Documentation~/Components.md b/Packages/com.unity.inputsystem/Documentation~/Components.md index 3690883493..687112d487 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Components.md +++ b/Packages/com.unity.inputsystem/Documentation~/Components.md @@ -1,49 +1,49 @@ -# GameObject Components for Input +# GameObject components for input -Two `MonoBehaviour` components are available to simplify setting up and working with input. They are generally the quickest and easiest way to get started with input in Unity. +The Input System provides two `MonoBehaviour` components that simplify setting up and working with input. |Component|Description| |---------|-----------| -|[`PlayerInput`](#playerinput-component)|Represents a single player along with the player's associated [input actions](Actions.md).| -|[`PlayerInputManager`](#playerinputmanager-component)|Handles setups that allow for several players including scenarios such as player lobbies and split-screen gameplay.| +|[`PlayerInput`](#playerinput-component)|Represents a single player along with the player's associated [Input Actions](Actions.md).| +|[`PlayerInputManager`](#playerinputmanager-component)|Handles setups that allow for several players, including player lobbies and split-screen gameplay.| ->NOTE: These components are built on top of the public input system API. As such, they don't do anything that you cannot program yourself. They are meant primarily as an easy out-of-the-box setup to obsolete much of the need for custom scripting. +>__Note__: These components are built on top of the public Input System API. As such, they don't do anything that you can't program yourself. They are meant primarily as an easy, out-of-the-box setup that eliminates much of the need for custom scripting. -## `PlayerInput` Component +## `PlayerInput` component ![PlayerInput](Images/PlayerInput.png) -Each [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) represents a separate player in the game. Multiple [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) instances may coexist at the same time (though not on the same `GameObject`) to represent local multiplayer setups. Each player will be paired to a unique set of devices for exclusive use by the player, although it is possible to manually pair devices such that players share a device (e.g. for left/right keyboard splits or hotseat use). +Each [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) instance represents a separate player in the game. Multiple [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) instances can coexist at the same time (though not on the same `GameObject`) to represent local multiplayer setups. The Input System pairs each player to a unique set of Devices that the player uses excplusively, but you can also manually pair Devices in a way that enables two or more players to share a Device (for example, left/right keyboard splits or hot seat use). -Each [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) corresponds to one [`InputUser`](UserManagement.md). The [`InputUser`](UserManagement.md) can be queried from the component using [`PlayerInput.user`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_user). +Each [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) corresponds to one [`InputUser`](UserManagement.md). You can query the [`InputUser`](UserManagement.md) from the component using [`PlayerInput.user`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_user). You can use the following properties to configure [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html). |Property|Description| |--------|-----------| -|[`Actions`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions)|The set of [input actions](Actions.md) associated with the player. To receive input, each player must have an associated set of actions. See [here](#actions) for details.| -|[`Default Control Scheme`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_defaultControlScheme)|Which [control scheme](ActionBindings.md#control-schemes) to use from what is defined in [`Actions`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions) by default.| -|[`Default Action Map`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_defaultActionMap)|Which [action map](Actions.md#overview) in [`Actions`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions) to enable by default. If set to `None`, then the player will start out with no actions being enabled.| -|[`Camera`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_camera)|The individual camera associated with the player.

This is __only required__ when employing [split-screen](#split-screen) setups. It has no effect otherwise.| -|[`Behavior`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_notificationBehavior)|How the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component notifies game code about things that happen with the player. See [here](#notification-behaviors).| +|[`Actions`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions)|The set of [Input Actions](Actions.md) associated with the player. To receive input, each player must have an associated set of Actions. See documentation on [Actions](#actions) for details.| +|[`Default Control Scheme`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_defaultControlScheme)|Which [Control Scheme](ActionBindings.md#control-schemes) (selected from what is defined in [`Actions`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions)) to enable by default.| +|[`Default Action Map`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_defaultActionMap)|Which [Action Map](Actions.md#overview) in [`Actions`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions) to enable by default. If set to `None`, then the player starts out with no Actions being enabled.| +|[`Camera`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_camera)|The individual camera associated with the player. This is only required when employing [split-screen](#split-screen) setups and has no effect otherwise.| +|[`Behavior`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_notificationBehavior)|How the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component notifies game code about things that happen with the player. See documentation on [notification behaviors](#notification-behaviors).| ### Actions -To receive input, each player requires an associated set of input actions. When creating these through the "Create Actions..." button in the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) inspector, a default set of actions will be created. However, the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component places no restrictions on the arrangement of actions. +To receive input, each player must have an associated set of Input Actions. When creating these through the __Create Actions…__ button in the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) Inspector, The Input System creates a default set of Actions. However, the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component places no restrictions on the arrangement of Actions. -[`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) will handle [enabling and disabling](Actions.md#using-actions) automatically and will also take care of installing [callbacks](Actions.md#responding-to-actions) on the actions. Also, when multiple [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) components use the same actions, the components will automatically take care of creating [private copies of the actions](Actions.md#using-actions-with-multiple-players). +[`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) automatically handles [enabling and disabling](Actions.md#using-actions) Actions, and also takes care of installing [callbacks](Actions.md#responding-to-actions) on the Actions. When multiple [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) components use the same Actions, the components automatically create [private copies of the Actions](Actions.md#using-actions-with-multiple-players). -When first enabled, [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) will enable all actions from the action map identified by [`Default Action Map`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_defaultActionMap). If no default action map has been set, no actions will be enabled by default. To manually enable actions, you can simply call [`Enable`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_Enable) and [`Disable`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_Disable) on the action maps or actions like you would do [without `PlayerInput`](Actions.md#using-actions). You can check or switch which action map is currently enabled using the [`PlayerInput.currentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_currentActionMap) property. To switch action maps by action map name, you can also call [`PlayerInput.SwitchCurrentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_SwitchCurrentActionMap_System_String_). +When first enabled, [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) enables all Actions from the the [`Default Action Map`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_defaultActionMap). If no default Action Map exists, [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) will not enable any Actions. To manually enable Actions, you can call [`Enable`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_Enable) and [`Disable`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_Disable) on the Action Maps or Actions like you would do [without `PlayerInput`](Actions.md#using-actions). You can check which Action Map is currently enabled or switch to a different one by using the [`PlayerInput.currentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_currentActionMap) property. To switch Action Maps using an Action Map name, you can also call [`PlayerInput.SwitchCurrentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_SwitchCurrentActionMap_System_String_). -To disable input on a player, call [`PlayerInput.PassivateInput`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_PassivateInput). To re-enable it, call [`PlayerInput.ActivateInput`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_ActivateInput). The latter will enable the default action map, if set. +To disable a player's input, call [`PlayerInput.PassivateInput`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_PassivateInput). To re-enable it, call [`PlayerInput.ActivateInput`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_ActivateInput). The latter enables the default action map, if it exists. -When [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) is disabled, it will automatically disable the currently active action map ([`PlayerInput.currentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_currentActionMap)) and disassociate any devices paired to the player. +When [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) is disabled, it automatically disables the currently active Action Map ([`PlayerInput.currentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_currentActionMap)) and disassociate any Devices paired to the player. -See [the following section](#notification-behaviors) for how to be notified when an action is triggered by a player. +See the [notification behaviors](#notification-behaviors) section below for how to be notified when player triggers an Action. #### `SendMessage`/`BroadcastMessage` Actions -When the [notification behavior](#notification-behaviors) of [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) is set to `Send Messages` or `Broadcast Messages`, actions can be responded to by defining methods in components like so: +When the [notification behavior](#notification-behaviors) of [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) is set to `Send Messages` or `Broadcast Messages`, you can set your app to respond to Actions by defining methods in components like so: ```CSharp public class MyPlayerScript : MonoBehaviour @@ -70,11 +70,11 @@ public class MyPlayerScript : MonoBehaviour } ``` -The component must sit on the same `GameObject` if `Send Messages` is chosen or on the same or any child `GameObject` if `Broadcast Messages` is chosen. +The component must be on the same `GameObject` if using `Send Messages` or on the same or any child `GameObject` if using `Broadcast Messages`. #### `UnityEvent` Actions -When the [notification behavior](#notification-behaviors) of [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) is set to `Invoke Unity Events`, each action has to individually be routed to a target method. The methods have the same format as the [`started`, `performed`, and `canceled` callbacks](Actions.md#started-performed-and-canceled-callbacks) on [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html). +When the [notification behavior](#notification-behaviors) of [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) is set to `Invoke Unity Events`, each Action has to be routed to a target method. The methods have the same format as the [`started`, `performed`, and `canceled` callbacks](Actions.md#started-performed-and-canceled-callbacks) on [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html). ```CSharp public class MyPlayerScript : MonoBehaviour @@ -90,91 +90,90 @@ public class MyPlayerScript : MonoBehaviour } ``` -### Notification Behaviors +### Notification behaviors -You can use the [`Behavior`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_notificationBehavior) property in the inspector to determine how a [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component notifies game code when something related to the player has occurred. The following options are available to choose the specific mechanism that [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) employs. +You can use the [`Behavior`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_notificationBehavior) property in the Inspector to determine how a [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component notifies game code when something related to the player has occurred. -You can listen to the following notifications: +The following options are available: |Behavior|Description| |--------|-----------| -|[`Send Messages`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Uses [`GameObject.SendMessage`](https://docs.unity3d.com/ScriptReference/GameObject.SendMessage.html) on the `GameObject` that the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component belongs to. The messages that will be sent by the component are shown in the UI.| -|[`Broadcast Messages`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Like `Send Message` but instead of [`GameObject.SendMessage`](https://docs.unity3d.com/ScriptReference/GameObject.SendMessage.html) uses [`GameObject.BroadcastMessage`](https://docs.unity3d.com/ScriptReference/GameObject.BroadcastMessage.html). This will broadcast the message down the `GameObject` hierarchy.| -|[`Invoke Unity Events`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Uses a separate [`UnityEvent`](https://docs.unity3d.com/ScriptReference/Events.UnityEvent.html) for each individual type of message. When this is selected, the events that are available on the given [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) are accessible from the "Events" foldout. The argument received by events triggered for actions is the same as the one received by [`started`, `performed`, and `canceled` callbacks](Actions.md#started-performed-and-canceled-callbacks).

![PlayerInput UnityEvents](Images/MyPlayerActionEvents.png)| -|[`Invoke CSharp Events`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Similar to `Invoke Unity Events` except that the events are plain C# events available on the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) API. These cannot be initialized from the inspector but have to be manually registered callbacks for in script.

The following events are available:

  • [`onActionTriggered`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_onActionTriggered) (collective event for all actions on the player)
  • [`onDeviceLost`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_onDeviceLost)
  • [`onDeviceRegained`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_onDeviceRegained)
| +|[`Send Messages`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Uses [`GameObject.SendMessage`](https://docs.unity3d.com/ScriptReference/GameObject.SendMessage.html) on the `GameObject` that the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component belongs to.| +|[`Broadcast Messages`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Like `Send Message` but instead of [`GameObject.SendMessage`](https://docs.unity3d.com/ScriptReference/GameObject.SendMessage.html) uses [`GameObject.BroadcastMessage`](https://docs.unity3d.com/ScriptReference/GameObject.BroadcastMessage.html). This broadcasts the message down the `GameObject` hierarchy.| +|[`Invoke Unity Events`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Uses a separate [`UnityEvent`](https://docs.unity3d.com/ScriptReference/Events.UnityEvent.html) for each individual type of message. When this is selected, the events that are available on the given [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) are accessible from the __Events__ foldout. The argument received by events triggered for Actions is the same as the one received by [`started`, `performed`, and `canceled` callbacks](Actions.md#started-performed-and-canceled-callbacks).

![PlayerInput UnityEvents](Images/MyPlayerActionEvents.png)| +|[`Invoke CSharp Events`](../api/UnityEngine.InputSystem.PlayerNotifications.html)|Similar to `Invoke Unity Events` except that the events are plain C# events available on the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) API. You cannot configure these from the inspector. Instead, you have to register callbacks for the events in your scripts. +

The following events are available:

  • [`onActionTriggered`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_onActionTriggered) (collective event for all actions on the player)
  • [`onDeviceLost`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_onDeviceLost)
  • [`onDeviceRegained`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_onDeviceRegained)
| -In addition to per-action notifications, the following general notifications are employed by [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html). +In addition to per-action notifications, [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) sends the following general notifications: |Notification|Description| |------------|-----------| -|[`DeviceLostMessage`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_DeviceLostMessage)|The player has lost one of the devices assigned to it. This can happen, for example, if a wireless device runs out of battery.| -|[`DeviceRegainedMessage`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_DeviceRegainedMessage)|Notification that is triggered when the player recovers from device loss and is good to go again.| +|[`DeviceLostMessage`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_DeviceLostMessage)|The player has lost one of the Devices assigned to it. This can happen, for example, if a wireless device runs out of battery.| +|[`DeviceRegainedMessage`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_DeviceRegainedMessage)|Notification that triggers when the player recovers from Device loss and is good to go again.| -### Control Schemes +### Device assignments -### Device Assignments +Each [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) can be assigned one or more Devices. By default, no two [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) components are assigned the same Devices, but you can force this by manually assigning Devices to a player when calling [`PlayerInput.Instantiate`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_Instantiate_GameObject_System_Int32_System_String_System_Int32_UnityEngine_InputSystem_InputDevice_), or by calling [`InputUser.PerformPairingWithDevice`](../api/UnityEngine.InputSystem.Users.InputUser.html#UnityEngine_InputSystem_Users_InputUser_PerformPairingWithDevice_UnityEngine_InputSystem_InputDevice_UnityEngine_InputSystem_Users_InputUser_UnityEngine_InputSystem_Users_InputUserPairingOptions_) on the [`InputUser`](UserManagement.md) of a [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html). -Each [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) can be assigned one or more devices. By default, no two [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) components will be assigned the same devices — although this can be forced explicitly by manually assigning devices to a player when calling [`PlayerInput.Instantiate`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_Instantiate_GameObject_System_Int32_System_String_System_Int32_UnityEngine_InputSystem_InputDevice_) or by calling [`InputUser.PerformPairingWithDevice`](../api/UnityEngine.InputSystem.Users.InputUser.html#UnityEngine_InputSystem_Users_InputUser_PerformPairingWithDevice_UnityEngine_InputSystem_InputDevice_UnityEngine_InputSystem_Users_InputUser_UnityEngine_InputSystem_Users_InputUserPairingOptions_) on the [`InputUser`](UserManagement.md) of a [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html). +If the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component has any Devices assigned, it matches these to the [Control Schemes](ActionBindings.md#control-schemes) in the associated Action Asset, and will only enables Control Schemes which match its Input Devices. -The devices assigned . - -### UI Input +### UI input The [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component can work together with a [`InputSystemUIInputModule`](UISupport.md#inputsystemuiinputmodule-component) to drive the [UI system](UISupport.md). To set this up, assign a reference to a [`InputSystemUIInputModule`](UISupport.md#inputsystemuiinputmodule-component) component in the [`UI Input Module`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_uiInputModule) field of the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component. The [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) and [`InputSystemUIInputModule`](UISupport.md#inputsystemuiinputmodule-component) components should be configured to work with the same [`InputActionAsset`](Actions.md) for this to work. -Now, when the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component configures the actions for a specific player, it will assign the same action configuration to the [`InputSystemUIInputModule`](UISupport.md#inputsystemuiinputmodule-component). So the same device used to control the player will now be set up to control the UI. +Once you've completed this setup, when the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component configures the Actions for a specific player, it assigns the same Action configuration to the [`InputSystemUIInputModule`](UISupport.md#inputsystemuiinputmodule-component). In other words, the same Action and Device configuration used to control the player now also controls the UI. -If you use [`MultiplayerEventSystem`](UISupport.md#multiplayereventsystem-component) components to dispatch UI events, you can also use this setup to simultaneously have multiple UI instances on the screen, controlled by separate players. +If you use [`MultiplayerEventSystem`](UISupport.md#multiplayereventsystem-component) components to dispatch UI events, you can also use this setup to simultaneously have multiple UI instances on the screen, each controlled by a separate player. -## `PlayerInputManager` Component +## `PlayerInputManager` component -The [`PlayerInput`](#playerinput-component) system has been designed to facilitate setting up local multiplayer games, with multiple players sharing a single device with a single screen and multiple controllers. This is set up using the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) component, which automatically manages the creation and livetime of [`PlayerInput`](#playerinput-component) instances as players join and leave the game. +The [`PlayerInput`](#playerinput-component) system facilitates setting up local multiplayer games, where multiple players share a single device with a single screen and multiple controllers. Set this up using the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) component, which automatically manages the creation and lifetime of [`PlayerInput`](#playerinput-component) instances as players join and leave the game. ![PlayerInputManager](Images/PlayerInputManager.png) |Property|Description| |--------|-----------| -|[`Notification Behavior`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_notificationBehavior)|How the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInput.html) component notifies game code about things that happen with the. [This works the same way as for the `PlayerInput` component](#notification-behaviors).| -|[`Join Behavior`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_joinBehavior)|Determines the mechanism by which players can join when joining is enabled. See [Join Behaviors](#join-behaviors).| -|[`Player Prefab`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_playerPrefab)|A prefab representing a player in the game. The [`PlayerInputManager`]((../api/UnityEngine.InputSystem.PlayerInputManager.html) component will create an instance of this prefab whenever a new player joins. This prefab must have one [`PlayerInput`](#playerinput-component) component in it's hierarchy.| +|[`Notification Behavior`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_notificationBehavior)|How the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInput.html) component notifies game code about changes to the connected players. [This works the same way as for the `PlayerInput` component](#notification-behaviors).| +|[`Join Behavior`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_joinBehavior)|Determines the mechanism by which players can join when joining is enabled. See documentation on [join behaviors](#join-behaviors).| +|[`Player Prefab`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_playerPrefab)|A prefab that represents a player in the game. The [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) component creates an instance of this prefab whenever a new player joins. This prefab must have one [`PlayerInput`](#playerinput-component) component in its hierarchy.| |[`Joining Enabled By Default`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_joiningEnabled)|While this is enabled, new players can join via the mechanism determined by [`Join Behavior`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_joinBehavior).| |[`Limit Number of Players`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_maxPlayerCount)|Enable this if you want to limit the number of players who can join the game.| |[`Max Player Cou nt`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_maxPlayerCount)(Only shown when `Limit number of Players` is enabled.)|The maximum number of players allowed to join the game.| -|[`Enable Split-Screen`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_splitScreen)|If enabled, each player will automatically be assigned a portion of the available screen area. See [Split-Screen](#split-screen)| +|[`Enable Split-Screen`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_splitScreen)|If enabled, each player is automatically assigned a portion of the available screen area. See documentation on [split-screen](#split-screen) multiplayer.| -### Join Behaviors +### Join behaviors You can use the [`Join Behavior`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_joinBehavior) property in the inspector to determine how a [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) component decides when to add new players to the game. The following options are available to choose the specific mechanism that [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) employs. |Behavior|Description| |--------|-----------| -|[`Join Players When Button IsPressed`](../api/UnityEngine.InputSystem.PlayerJoinBehavior.html)|Listen for button presses on devices that are not paired to any player. If they occur and joining is allowed, join a new player using the device the button was pressed on.| -|[`Join Players When Join Action Is Triggered`](../api/UnityEngine.InputSystem.PlayerJoinBehavior.html)|Similar to `Join Players When Button IsPressed`, but this will only join a player if the control which was triggered matches a specific action you can define. That way, you can set up players to join when pressing a specific gamepad button for instance.| -|[`Join Players Manually`](../api/UnityEngine.InputSystem.PlayerJoinBehavior.html)|Do not join players automatically. Call [`JoinPlayerFromUI`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_JoinPlayerFromUI) or [`JoinPlayerFromAction`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_JoinPlayerFromAction_UnityEngine_InputSystem_InputAction_CallbackContext_) explicitly in order to join new players. Alternatively, just create GameObjects with [`PlayerInput`](#playerinput-component) components directly and they will be joined automatically.| +|[`Join Players When Button IsPressed`](../api/UnityEngine.InputSystem.PlayerJoinBehavior.html)|Listen for button presses on Devices that are not paired to any player. If a player presses a button and joining is allowed, join the new player using the Device they pressed the button on.| +|[`Join Players When Join Action Is Triggered`](../api/UnityEngine.InputSystem.PlayerJoinBehavior.html)|Similar to `Join Players When Button IsPressed`, but this will only join a player if the control they triggered matches a specific action you define. For example, you can set up players to join when pressing a specific gamepad button.| +|[`Join Players Manually`](../api/UnityEngine.InputSystem.PlayerJoinBehavior.html)|Don't join players automatically. Call [`JoinPlayerFromUI`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_JoinPlayerFromUI) or [`JoinPlayerFromAction`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_JoinPlayerFromAction_UnityEngine_InputSystem_InputAction_CallbackContext_) explicitly in order to join new players. Alternatively, create GameObjects with [`PlayerInput`](#playerinput-component) components directly and the Input System will automatically join them.| -### Split-Screen +### Split-screen -If you enable the [`Split-Screen`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_splitScreen) option, then the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) will automatically split the available screen space between the active players. For this to work, the [`Camera`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_camera) property must be configured on the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) prefab. The [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) will then automatically resize and reposition each camera instance to let each player have it's own part of the screen. +If you enable the [`Split-Screen`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_splitScreen) option, the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) automatically splits the available screen space between the active players. For this to work, you must set the [`Camera`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_camera) property on the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) prefab. The [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) then automatically resizes and repositions each camera instance to let each player have their own part of the screen. -If you enable the [`Split-Screen`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_splitScreen) option, the following additional properties will be shown in the inspector: +If you enable the [`Split-Screen`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_splitScreen) option, you can configure the following additional properties in the Inspector: |Property|Description| |--------|-----------| -|[`Maintain Aspect Ratio`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_maintainAspectRatioInSplitScreen)|Determines whether subdividing the screen is allowed to produce screen areas that have an aspect ratio different from the screen resolution.| -|[`Set Fixed Number`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_fixedNumberOfSplitScreens)|If this value is larger then zero, then the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) will always split the screen into a fixed number of rectangles, regardless of the actual number of players.| +|[`Maintain Aspect Ratio`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_maintainAspectRatioInSplitScreen)|A `false` value enables the game to produce screen areas that have an aspect ratio different from the screen resolution when subdividing the screen.| +|[`Set Fixed Number`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_fixedNumberOfSplitScreens)|If this value is greater than zero, the [`PlayerInputManager`](../api/UnityEngine.InputSystem.PlayerInputManager.html) always splits the screen into a fixed number of rectangles, regardless of the actual number of players.| |[`Screen Rectangle`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_splitScreenArea)|The normalized screen rectangle available for allocating player split-screens into.| -By default, any UI elements can be interacted with by any player in the game. However, in split-screen setups, it is possible to have screen-space UIs that are restricted to just one specific camera. See the (UI Input)[#ui-input] section above on how to set this up using the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html), [`InputSystemUIInputModule`](UISupport.md#inputsystemuiinputmodule-component) and [`MultiplayerEventSystem`](UISupport.md#multiplayereventsystem-component) components. +By default, any player in the game can interact with any UI elements. However, in split-screen setups, your game can have screen-space UIs that are restricted to just one specific camera. See the [UI Input](#ui-input) section above on how to set this up using the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html), [`InputSystemUIInputModule`](UISupport.md#inputsystemuiinputmodule-component) and [`MultiplayerEventSystem`](UISupport.md#multiplayereventsystem-component) components. -### `PlayerInputManager` Notifications +### `PlayerInputManager` notifications -`PlayerInputManager` sends notifications when something notable happens with the current player setup. How these notifications are delivered through the `Notification Behavior` property the [same way as for `PlayerInput`](#notification-behaviors). +`PlayerInputManager` sends notifications when something notable happens with the current player setup. These notifications are delivered according to the `Notification Behavior` property, in the [same way as for `PlayerInput`](#notification-behaviors). -You can listen to the following notifications: +Your game can listen to the following notifications: |Notification|Description| |------------|-----------| -|[`PlayerJoinedMessage`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_PlayerJoinedMessage)|A new player has joined the game. Passes the [`PlayerInput`](#playerinput-component) instance of the player who has joined.

Note that if there are already active [`PlayerInput`](#playerinput-component) components present when `PlayerInputManager` is enabled, it will send a `Player Joined` notification for each of these.| +|[`PlayerJoinedMessage`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_PlayerJoinedMessage)|A new player has joined the game. Passes the [`PlayerInput`](#playerinput-component) instance of the player who has joined.

__Note__: If there are already active [`PlayerInput`](#playerinput-component) components present when `PlayerInputManager` is enabled, the `PlayerInputManager` will send a `Player Joined` notification for each of these.| |[`PlayerLeftMessage`](../api/UnityEngine.InputSystem.PlayerInputManager.html#UnityEngine_InputSystem_PlayerInputManager_PlayerLeftMessage)|A player left the game. Passes the [`PlayerInput`](#playerinput-component) instance of the player who has left.| diff --git a/Packages/com.unity.inputsystem/Documentation~/Contributing.md b/Packages/com.unity.inputsystem/Documentation~/Contributing.md index b0876e7d64..3200f844f8 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Contributing.md +++ b/Packages/com.unity.inputsystem/Documentation~/Contributing.md @@ -1,13 +1,13 @@ # Contributing -[Full source code](https://github.com/Unity-Technologies/InputSystem) for the input system is available on GitHub. This is also where most of our development happens. +The [full source code](https://github.com/Unity-Technologies/InputSystem) for the Input System is available on GitHub. This is also where most of our 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. +>__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 -Input System bugs should be reported through using [same mechanism as for any other Unity bugs](https://unity3d.com/unity/qa/bug-reporting). Make sure to submit a repro project, and to mention that the bug is specific to the Input System package in the description, so it can get forwarded to the correct respondents at Unity. +Please follow Unity's standard [bug reporting guidelines](https://unity3d.com/unity/qa/bug-reporting) to report any bugs related to the Input System. Don't forget to submit a Project we can use to reproduce the issue. Also, 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, we have a [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. +To ask questions or discuss the Input System, we have a [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. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/Controls.md b/Packages/com.unity.inputsystem/Documentation~/Controls.md index 18d07606cd..e403fa72be 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/Controls.md @@ -9,58 +9,58 @@ * [Noisy Controls](#noisy-controls) * [Synthetic Controls](#synthetic-controls) -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). +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 used for __input__ only. Output and configuration items on input devices are not represented as controls. +>__Note__: Controls are used 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 face button closest to the touchpad on the PS4 controller has the control name "buttonSouth" and the display name "Square". +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 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 may be identified by one or more aliases which provide alternative names for the control. The aliases for a specific control can be accessed through its [`InputControl.aliases`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_aliases) property. +Additionally, a Control might be identified by 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 may have a "short" display name which can be accessed through the [`InputControl.shortDisplayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_shortDisplayName) property. An example of such a name is "LMB" for the left mouse button. +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 +## Control hierarchies -Controls can form hierarchies. The root of a control hierarchy is always a [device](Devices.md). +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). -The parent of a control can be accessed using [`InputControl.parent`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_parent), the children through [`InputControl.children`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_children). The flattened hierarchy of all controls on a device can be accessed through [`InputDevice.allControls`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_allControls). +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 +## Control types All controls are based on the [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html) base class. Most concrete implementations are based on [`InputControl`](../api/UnityEngine.InputSystem.InputControl-1.html). -The following types of controls are provided by the input system out of the box: +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. It depends on the underlying representation whether the button can have a value other than 0 and 1. The gamepad trigger buttons can do so, for example, whereas the gamepad face buttons generally can not.|[`Mouse.leftButton`](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_leftButton)| -|[`KeyControl`](../api/UnityEngine.InputSystem.Controls.KeyControl.html)|A specialized button representing 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, will 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)| +|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|A button expressed as a floating-point value. It depends on the underlying representation whether the button can have a value other than 0 and 1. The gamepad trigger buttons can do so, for example, whereas the 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 representing 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 dpad on gamepads or hatswitches on joysticks.|[`Gamepad.dpad`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_dpad)| +|[`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 representing all the properties of a touch on a [touch screen](Touch.md).|[`Touchscreen.primaryTouch`](../api/UnityEngine.InputSystem.Touchscreen.html#UnityEngine_InputSystem_Touchscreen_primaryTouch)| -The set of all registered control layouts can be browsed using the [input debugger](Debugging.md#debugging-layouts). +You can browse the set of all registered control layouts in the [input debugger](Debugging.md#debugging-layouts). -## Control Usages +## Control usages -A control may have one or more associated usages. A usage is a string denoting the semantics of a control, i.e. the way the control is intended to be used. An example of a control usage is `Submit` which denotes a control that is commonly used to confirm selections in UIs and such. On a gamepad, this usage is commonly found on the `buttonSouth` control. +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. -The usages of a control can be accessed via the [`InputControl.usages`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_usages) property. +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 +## Control paths ->Example: `/leftStick/x` means "X control on left stick of gamepad". +>Example: `/leftStick/x` means "X Control on left stick of gamepad". -Controls can be looked up using textual paths. This feature is heavily used by [bindings](ActionBindings.md) on input actions in order to identify the control(s) from which input is to be read. However, they can also be used 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_). +The Input System can looked up Controls using textual paths. [Bindings](ActionBindings.md) on Input Actions rely on this feature in order to identify the Control(s) to 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]; @@ -69,11 +69,11 @@ var submitButton = gamepad["{Submit}"]; var allSubmitButtons = InputSystem.FindControls("*/{Submit}"); ``` -Control paths resemble file system paths. Each path is comprised of one or more components each separated by a forward slash: +Control paths resemble file system paths. Each path consists of one or more components separated by a forward slash: component/component... -Each component has the same syntax made up of multiple fields. Each field is optional but at least one field must be present. All fields are case-insensitive. +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. {usageName}controlName#(displayName) @@ -81,30 +81,30 @@ The following table explains the use of each field: |Field|Description|Example| |-----|-----------|-------| -|``|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.|`/buttonSouth`| -|`{usageName}`|Works differently for controls and devices.

When used on a device (i.e. in 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.

For looking up a control, the usage field is currently restricted to the path component immediately following the device (i.e. the second component in the path). It will find the control on the device that has the given usage. The control can be anywhere in the control hierarchy of the device.|*Device:*

`{LeftHand}/trigger`

*Control:*

`/{Submit}`| -|`controlName`|Requires the control at the current level to have the given name. 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)) are taken into account.

This field can also be `*` to match any name.|`MyGamepad/buttonSouth`

`*/{PrimaryAction}` (match `PrimaryAction` usage on device 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)). Note that the display name may contain whitespace and symbols.|`/#(a)` (matches the key that generates the "a" character, if any, according to the current keyboard layout).

`/#(Cross)`| +|``|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.|`/buttonSouth`| +|`{usageName}`|Works differently for Controls and Devices.

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.

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:*

`{LeftHand}/trigger`

*Control:*

`/{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.

This field can also be a wildcard (`*`) to match any name.|`MyGamepad/buttonSouth`

`*/{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.|`/#(a)` (matches the key that generates the "a" character, if any, according to the current keyboard layout).

`/#(Cross)`| -The "literal" path of a given control can be accessed via its [`InputControl.path`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_path) property. +You can access the literal path of a given control via its [`InputControl.path`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_path) property. -## Control State +## Control state -Each control is connected to a block of memory that is considered the control's "state". The size, format, and location of this block of memory can be queried from a control through the [`InputControl.stateBlock`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_stateBlock) property. +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 is handled internally by the input system. All devices added to the system share one block of unmanaged memory that contains the state of all the controls on the devices. +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. -State might not be stored in the "natural" format for a control. For example, buttons are often represented as bitfields and axis controls are often represented as 8-bit or 16-bit integer values. The format is determined by how the platform, hardware, and driver combination feeds input into Unity. Each control knows the format of its storage and how to translate the values as needed. This process is set up through [layouts](Layouts.md). +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. -The current state of a control can be accessed through its [`ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) method. +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 that it supports for its state. This value type can be accessed through the [`InputControl.valueType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_valueType) property. +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 may apply one or more value processors. Details on how processors operate can be found [here](Processors.md). +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) @@ -112,9 +112,9 @@ Reading a value from a control may apply one or more value processors. Details o #### Recording State History -It can be useful to be able to access the history of value changes on a control. For example, in order to compute exit velocity on a touch release. +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). -Recording state changes over time can be easily achieved using [`InputStateHistory`](../api/UnityEngine.InputSystem.LowLevel.InputStateHistory.html) or [`InputStateHistory`](../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). +To record state changes over time, you can use [`InputStateHistory`](../api/UnityEngine.InputSystem.LowLevel.InputStateHistory.html) or [`InputStateHistory`](../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. @@ -158,7 +158,7 @@ history.RecordStateChange(Touchscreen.current.primaryTouch.position, history.Dispose(); ``` -Say you want to have the last 100 samples of the left stick on the gamepad available. +For example, if you want to have the last 100 samples of the left stick on the gamepad available, you can use this code: ``` var history = new InputStateHistory(Gamepad.current.leftStick); @@ -166,9 +166,9 @@ history.historyDepth = 100; history.StartRecording(); ``` -## Control Actuation +## 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. Whether a control is currently actuated can be queried through [`IsActuated`](../api/UnityEngine.InputSystem.InputControlExtensions.html#UnityEngine_InputSystem_InputControlExtensions_IsActuated_UnityEngine_InputSystem_InputControl_System_Single_). +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. @@ -176,11 +176,11 @@ 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 the amount by which it is actuated. This is termed its magnitude. For a [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html), for example, this would be the length of the vector whereas for a button, it is simply the raw, absolute floating-point value. +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 a [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html), for example, 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 may not have a meaningful magnitude, in which case it will return -1 (any negative value should be considered an invalid magnitude). +In general, the current magnitude of a Control is always >= 0. However, a Control may not have a meaningful magnitude, in which case it will return -1. Any negative value should be considered an invalid magnitude. -The current amount of actuation can be queried using [`EvaluateMagnitude`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude). +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. @@ -188,26 +188,26 @@ 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: +There are two mechanisms that most notably make use of Control actuation: -- [Interactive rebinding](ActionBindings.md#runtime-rebinding) (`InputActionRebindingExceptions.RebindOperation`) uses it to select between multiple suitable controls to find the one that is actuated the most. -- [Disambiguation](ActionBindings.md#disambiguation) between multiple controls that are bound to the same action uses it to decide which control gets to drive the action. +- [Interactive rebinding](ActionBindings.md#runtime-rebinding) (`InputActionRebindingExceptions.RebindOperation`) uses it to select between multiple suitable Controls to find the one that is actuated the most. +- [Disambiguation](ActionBindings.md#disambiguation) between multiple Controls that are bound to the same action uses it to decide which control gets to drive the action. ## Noisy Controls -A control may be identified as being "noisy" in nature. This is indicated by the [`InputControl.noisy`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_noisy) property being true. +A Control can be labelled as being noisy by the Input System. You can query this using the [`InputControl.noisy`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_noisy) property. -Being noisy has two primary effects: +If a Control is marked as noisy, that means that: -1. The control is not considered for [interactive rebinding](ActionBindings.md#runtime-rebinding). I.e. [`InputActionRebindingExceptions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) will ignore the control by default (this can be bypassed using [`WithoutIgnoringNoisyControls`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithoutIgnoringNoisyControls)). -2. The system will perform additional event filtering before calling [`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. +1. The Control is not considered for [interactive rebinding](ActionBindings.md#runtime-rebinding). [`InputActionRebindingExceptions.RebindingOperation`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html) ignores the Control by default (you can be bypass this using [`WithoutIgnoringNoisyControls`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.RebindingOperation.html#UnityEngine_InputSystem_InputActionRebindingExtensions_RebindingOperation_WithoutIgnoringNoisyControls)). +2. The system will perform additional event filtering before calling [`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. ->NOTE: If __any__ control on a device is noisy, the device itself is flagged as noisy. +>*Note*: If any control on a device is noisy, the device itself is flagged as noisy. ## Synthetic Controls -A "synthetic" control is a control that does not correspond to an actual physical control on a device. An example are the `left`, `right`, `up`, and `down` direction buttons on a stick. These controls synthesize input from actual physical controls for the sake of presenting it in a different way (in this case, for allowing to treat the individual directions of a stick as buttons). +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. +Whether a given Control is synthetic is indicated by its [`InputControl.synthetic`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_synthetic) property. -Synthetic controls will be considering for [interactive rebinding](ActionBindings.md#runtime-rebinding) but non-synthetic controls will always be favored over synethetic ones. I.e. if there is both a synthetic and a non-synthetic control that are a potential match, the non-synthetic control will win out by default. This makes it possible to interactively bind to `/leftStick/left`, for example, but at the same time makes it possible to bind to `/leftStickPress` without getting interference from the synthetic buttons on the stick. +The system considers synthetic Controls for [interactive rebinding](ActionBindings.md#runtime-rebinding) but always favors non-synthetic Controls over synthetic ones. If both a synthetic and a non-synthetic Control that are a potential match exist, the non-synthetic Control wins out by default. This makes it possible to interactively bind to `/leftStick/left`, for example, but also makes it possible to bind to `/leftStickPress` without getting interference from the synthetic buttons on the stick. diff --git a/Packages/com.unity.inputsystem/Documentation~/Debugging.md b/Packages/com.unity.inputsystem/Documentation~/Debugging.md index 525c73b1e4..034a62bf94 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Debugging.md +++ b/Packages/com.unity.inputsystem/Documentation~/Debugging.md @@ -3,87 +3,87 @@ * [Input Debugger](#input-debugger) * [Debugging Devices](#debugging-devices) * [Debugging Actions](#debugging-actions) - * [Debugging Users/PlayerInput](#debugging-usersplayerinput) - * [Debugging Layouts](#debugging-layouts) + * [Debugging users and PlayerInput](#debugging-users-and-playerinput) + * [Debugging layouts](#debugging-layouts) * [Debugging Remotely](#debugging-remotely) -When something isn't working as expected, the best first stop is usually the "Input Debugger" in the Unity editor. This is a Unity editor window that is designed to provide access to the activity of the input system in both the editor and in connected players. +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` in Unity's main menu in the editor. +To open the Input Debugger, go to __Window > Analysis > Input Debugger__ from Unity's main menu. ## Input Debugger ![Input Debugger](Images/InputDebugger.png) -The debugger shows a tree breakdown of the state of the input system. +The Input Debugger shows a tree breakdown of the state of the Input System. |Item|Description| |----|-----------| -|Devices|[Input devices](Devices.md) that are currently added to the system as well as a list of unsupported/unrecognized devices.| -|Layouts|A breakdown of all registered control and device layouts. This is essentially the database of supported hardware and the knowledge of how to represent a given piece of input hardware.| -|Actions|Only visible in play mode and only if there are [actions](Actions.md) that are currently enabled.

Shows the list of all currently enabled actions and the controls they are bound to.

See [Debugging Actions](#debugging-actions).| -|Users|Only visible when there is one or more `InputUser` instances. See [documentation](UserManagement.md).

Lists all currently active uers along with their active control schemes and devices, all their associated actions as well as the controls they are bound to.

Note that `PlayerInput` uses `InputUser` underneath. This means that when using `PlayerInput` components, each player will have an entry here.

See [Debugging Users/PlayerInput](#debugging-usersplayerinput).| +|Devices|[Input Devices](Devices.md) that are currently added to the system as well as a list of unsupported/unrecognized Devices.| +|Layouts|A breakdown 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 [Actions](Actions.md) is currently enabled.

Shows the list of all currently enabled Actions and the Controls they are bound to.

See [Debugging Actions](#debugging-actions).| +|Users|Only visible when there one or more `InputUser` instances exist. See documentation on [user management](UserManagement.md).

Lists all currently active users along with their active Control Schemes and Devices, all their associated Actions and the Controls these Actions are bound to.

Note that `PlayerInput` uses `InputUser` to run. When using `PlayerInput` components, each player has an entry in this list.

See [Debugging users and PlayerInput](#debugging-users-and-playerinput).| |Settings|Shows the currently active Input System [settings](Settings.md).| |Metrics|Shows some statics about Input System resource usage.| ### Debugging Devices -You can double-click on any [input device](Devices.md) in the `Devices` list in the debugger window to open a window showing information about the device, including real-time state information for its controls. +Double-click any [input device](Devices.md) in the __Devices__ list in the Input Debugger window to open a window showing information about the Device, including real-time state information for its Controls. ![Device in Input Debugger](Images/DeviceInDebugger.png) -The top of the device window shows some general information about the specific device (such as name, manufacturer, serial number, etc). +The top of the Device window shows general information about the specific Device such as name, manufacturer, serial number, etc. -Below that, you you see a view listing the devices controls, and their state. This is very useful when debugging input issues, as it allows you to verify if the data the input system is receiving from the input device is what you'd expect it to be in the first place. At the top of this view you will see the following buttons: +Below that, the window lists the Device's Controls and their individual state. This is useful when debugging input issues, as it allows you to verify if the data the Input System is receiving from the Input Device is what you expect it to be. There are two buttons at the top of this panel: -* `State`: Show the current state of the device in a new window. This is identical to the information as shown in this view, but is not updated, so you can take a slice of input state data and take the time to inspect it as needed. +* __State__: Show the current state of the Device in a new window. This is identical to the information shown in this view, but doesn't update in real time, so you can take a snapshop of input state data and take the time to inspect it as needed. -* `HID Descriptor`: Only shown for devices connected using the HID protocol. This will open a window showing the detailed [HID](HID.md) specifications for the device and each of it's logical controls. +* __HID Descriptor__: Only shown for devices connected using the HID protocol. This opens a window showing the detailed [HID](HID.md) specifications for the Device and each of it's logical controls. -Finally, in the bottom of the window, you can inspect the event stream coming from the device. Any [Input Event](Events.md) generated by the device will be shown here. You can double-click any event in the list to inspect the full device state at the time of the event. You can also select multiple events, and right click and choose "Compare" in the context menu to get a side-by-side difference between the state of the device at two different points in time. +Finally, at the bottom of the window, you can inspect the event stream coming from the Device. This is where Unity shows 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. You can also select multiple events, right click them, and click Compare from the context menu that appears to get a side-by-side difference between the state of the Device at different points in time. ### Debugging Actions -Any enabled [actions](Actions.md) are listed in the Actions list in the debugger window (only shown if any actions are 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 them in the list. This is useful to debug whether your bindings correctly map to the controls you want them to bind to. See ["Binding Resolution"](ActionBindings.md#binding-resolution) for more info on how bindings are mapped to controls. +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 belonging to [`InputUsers`](UserManagement.md) will not be shown here, but will be shown in the [Users](#debugging-usersplayerinput) list instead. +>__Note__: Actions belonging to [`InputUsers`](UserManagement.md) don't appear here. They appear in the [__Users__](#debugging-usersplayerinput) list instead. -### Debugging Users/PlayerInput +### Debugging users and PlayerInput -When there are multiple [`InputUser`](UserManagement.md) instances – each `PlayerInput` will implicitly create one –, the debugger will list each user along with its paired devices and active actions. The listed devices and actions work the same way as those shown in the [devices](#debugging-devices) and [actions](#debugging-actions) lists in the debugging window. +When there are any [`InputUser`](UserManagement.md) instances (If you are using `PlayerInput`, each `PlayerInput` instance will implicitly create one), the Input Debugger lists each instance along with its paired Devices and active Actions in the __Users__ list. The listed devices and actions work the same way as those shown in the [__Devices__](#debugging-devices) and [__Actions__](#debugging-actions) lists in the debugging window. ![Users in Input Debugger](Images/UsersInputDebugger.png) -### Debugging Layouts +### Debugging layouts -The [`Layouts`](Layouts.md) list in the Debugger window shows a breakdown of all registered [control and device layouts](Layouts.md). This is essentially the database of supported hardware and the knowledge of how to represent a given piece of input hardware. This is mostly handy when you want to [create a new device mapping](HowDoI.md#-create-my-own-custom-devices), and want to see how it gets represented by the input system. +The [__Layouts__](Layouts.md) list in the Input Debugger window shows 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. This is mostly handy when you want to [create a new Device mapping](HowDoI.md#-create-my-own-custom-devices), and want to see how it gets represented by the Input System. ![Layouts in Input Debugger](Images/LayoutsInDebugger.png) -### Debugging Remotely +### Debugging remotely -You can connect input debugger to a player running on a device. This makes input activity from the player observable in the editor. The mechanism used by this is Unity's `PlayerConnection`, i.e. the same mechanism by which the Unity profiler can be connected to a player. +You can connect Input Debugger to a Player running on a remote computer or device. This makes input activity from the Player observable in the Editor. The mechanism used by this is Unity's `PlayerConnection`, that is, the same mechanism by which the Unity profiler can be connected 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 yet for seeing other input-related data such as actions and input users from players. +>__Note__: At the moment, debugging input in Players is restricted to seeing Devices and events from connected Players. There is no support yet for seeing other input-related data such as Actions and input users from Players. -To see remote devices from built players, click the `Remote Devices…` pop-up button in the Debugger window. You will see a list of remote player instance you can connect to (if there are any) - this is the same list as you will see in the Profiler and Console windows, and any connections are share between those windows. If any player(s) are connected, you can enable `Show remote devices` in the same popup button. If players are connected, and `Show remote devices` is enabled, the [`Devices`](#debugging-devices) list in the debugger window will be split into a `Local` section and a `Remote` section. The `Remote` section will show any input device from any connected player, and lets you inspect device state and events in real time, just as if it were a local device. +To see remote Devices from built Players, click the __Remote Devices…__ drop-down list in the Input Debugger window. You will see a list of remote Player instance you can connect to (if there are any) - this is the same list as you will see 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 will be split into a __Local__ section and a __Remote__ section. The __Remote__ section will show any Input Device from any connected Player, and lets you inspect Device state and events in real time, just as if it were a local Device. -## Input Visualizers +## 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. +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 click "Import in project" next to the "Visualizers" sample. +To install the sample, navigate to the Input System package in the Package Manager window ([see "Installation"](Installation.md)), and click __Import in project__ next to the __Visualizers__ sample. -The sampler provides two visualizer components: +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. +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. ![InputControlVisualizer](Images/InputControlVisualizer.png) ### `InputActionVisualizer` -Visualizes the current state of a single action in real-time. You can have multiple action visualizers to visualize the state of multiple action. Can show the current value of the action, the control currently driving the action, as well as track the state of [interactions](Interactions.md) over time. Check the `SimpleControlsVisualizer` scene in the sample for examples. +Visualizes the current state of a single Action in real time. You can have multiple Action visualizers to visualize the state of multiple Action. Can show the current value of the Action, the Control currently driving the Action, as well as track the state of [Interactions](Interactions.md) over time. Check the `SimpleControlsVisualizer` Scene in the sample for examples. ![InputActionVisualizer](Images/InputActionVisualizer.png) diff --git a/Packages/com.unity.inputsystem/Documentation~/Devices.md b/Packages/com.unity.inputsystem/Documentation~/Devices.md index 2313690ae7..933bdbaf90 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Devices.md +++ b/Packages/com.unity.inputsystem/Documentation~/Devices.md @@ -1,48 +1,48 @@ # Devices -* [Device Descriptions](#device-descriptions) - * [Hijacking the Matching Process](#hijacking-the-matching-process) +* [Device descriptions](#device-descriptions) + * [Hijacking the matching process](#hijacking-the-matching-process) * [Native Devices](#native-devices) * [Disconnected Devices](#disconnected-devices) * [Device IDs](#device-ids) -* [Device Usages](#device-usages) -* [Device Commands](#device-commands) +* [Device usages](#device-usages) +* [Device commands](#device-commands) * [Working with Devices](#working-with-devices) * [Monitoring Devices](#monitoring-devices) - * [Adding and Removing Devices](#adding-and-removing-devices) - * [Creating Custom Devices](#creating-custom-devices) + * [Adding and removing Devices](#adding-and-removing-devices) + * [Creating custom Devices](#creating-custom-devices) -Logically, devices are the top-level container for [controls](Controls.md). An [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) is itself a specialization of [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html). Physically, devices represent input devices attached to the computer, which can be used to control the content. See [supported devices](SupportedDevices.md) to see what kind of devices the input system currently supports. +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). Physically, Input Devices represent devices attached to the computer, which can be used to control the app. See [supported Devices](SupportedDevices.md) to see what kind of Devices the Input System currently supports. -The set of all currently present devices can be queried through [`InputSystem.devices`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_devices). +You can query the set of all currently present Devices using [`InputSystem.devices`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_devices). -## Device Descriptions +## Device descriptions -An [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) describes a device. This is primarily used during the device discovery process. When a new device is reported present (by the runtime or by the user), it is reported along with a device description. Based on the description, the system will then attempt to find a device [layout](Layouts.md) that matches the description. This process is based on ["device matchers"](#matching). +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, the description it was created from can be retrieved through the [`InputDevice.description`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_description) property. +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
bar
RawInput
XInput
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 describing device/interface-specific capabilities. See the [section on capabililities](#capabilities).| +|[`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).
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 describing Device/interface-specific capabilities. See the [section on capabililities](#capabilities).| ### Capabilities -Aside from a number of standardized fields, such as `product` and `manufacturer`, a device description may contain a [`capabilities`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html#UnityEngine_InputSystem_Layouts_InputDeviceDescription_capabilities) string in JSON format. This string is used to describe characteristics which help the input system with interpreting the data coming from a device and with mapping it to control representations. Not all device interfaces will 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. +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 with interpreting the data coming from a Device, and mapping it to Control representations. Not all Device interfaces will 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 -Matching an [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) to a registered layout is facilitated by [`InputDeviceMatcher`](../api/UnityEngine.InputSystem.Layouts.InputDeviceMatcher.html). Each matcher loosely functions as a kind of regular expression. Each field can be independently matched with either a plain string or regular expression. Matching is case-insensitive. For a matcher to apply, all its individual expressions have to match. +[`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 case-insensitive. For a matcher to apply, all its individual expressions have to match. -Matchers can be added to any layout by calling [`InputSystem.RegisterLayoutMatcher`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterLayoutMatcher_System_String_UnityEngine_InputSystem_Layouts_InputDeviceMatcher_) or supplied when registering a layout. +Matchers can be added to any layout by calling [`InputSystem.RegisterLayoutMatcher`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterLayoutMatcher_System_String_UnityEngine_InputSystem_Layouts_InputDeviceMatcher_). You can also supply them when registering a layout. ```CSharp // Register a new layout and supply a matcher for it. @@ -59,75 +59,73 @@ InputSystem.RegisterLayoutMatcher( ``` -If multiple matchers are matching the same [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html), the matcher that has the larger number of properties to match against will be chosen to pick the layout for the device. +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 +### Hijacking the matching process -It is possible to overrule the internal matching process from outside and thus select a different layout for a device than the system would normally choose. This also makes it possible to build new layouts on the fly. 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 this layout will be used. +You can overrule the internal matching process from outside and thus select a different layout for a Device than the system would normally choose. This also makes it possible to build new layouts on the fly. 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 will use this layout. ## Native Devices -Devices that are reported by the runtime are considered "native". These devices come in through the `IInputRuntime.onDeviceDiscovered` callback which is handled internally by the input system. Externally, devices created this way can be told apart from others by them having their [`InputDevice.native`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_native) property be true. +Devices that the [native backend](Architecture.md#native-backend) reports are considered native (as opposed to Devices created from script code). You can identify these Devices by checking the [`InputDevice.native`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_native) property. -A native device will be remembered by the input system. This means that, for example, if at the time the device was reported the system has no matching layout but a layout is registered later which matches the device, the device will be re-created using this layout. +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 recreates the Device using this layout. ### Disconnected Devices -If you want to get notified when input devices get disconnected, 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). +If you want to get notified when Input Devices get disconnected, 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 gets reconnected later, the input system can detect that the device was connected before, and will reuse it's [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) instance. This allows things like the [`PlayerInputManager`](Components.md) knowing to reassigning the device to the same [user](UserManagement.md) again. +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 gets reconnected later, the Input System can detect that the Device was connected before, and will reuse its [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) instance. This allows the [`PlayerInputManager`](Components.md) to reassign the Device to the same [user](UserManagement.md) again. ## Device IDs -Each device that is created will receive a unique, numeric ID. The ID can be accessed through [`InputDevice.deviceId`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId). +Each Device that is created will receive a unique numeric ID. You can access this ID through [`InputDevice.deviceId`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId). -The IDs are managed by the runtime and allocated through `IInputRuntime.AllocateDeviceId`. The runtime itself does not keep a record about which ID corresponds to which device. +All IDs are only used once per Unity session. -During a session of Unity, no ID will get used a second time. +## Device usages -## 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 set them using [`InputSystem.SetDeviceUsage()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_SetDeviceUsage_UnityEngine_InputSystem_InputDevice_System_String_). 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. -Like any [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html), a device may have one or more usages associated with it. Usages can be queried with the [`usages`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_usages) property, and they can be set using [`InputSystem.SetDeviceUsage()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_SetDeviceUsage_UnityEngine_InputSystem_InputDevice_System_String_). 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 -## Device Commands +While input [events](Events.md) deliver data coming from a Device, commands send data back to the Device. This is used for retrieving specific information from the Device, for triggering functions on the Device (such as rumble effects), or for a variety of other needs. -While input [events](Events.md) deliver data coming __from__ a device, commands are used to communicate in the opposite direction, i.e. to talk back at the device. This can be used for retrieving specific information from the device, for triggering functions on the device (such as rumble effects), or for a variety of other needs. +### Sending commands to Devices -### Sending Commands to Devices +A command is send to a Device through [`InputDevice.ExecuteCommand`](../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). -A command is send to a device through [`InputDevice.ExecuteCommand`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_ExecuteCommand__1___0__) which, for native devices, will relay the command to `IInputRuntime.DeviceCommand`. It is possible to intercept/monitor device commands through [`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 implementing 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. -Each device command implements the [`IInputDeviceCommandInfo`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html) interface, which only requires implementing the [`typeStatic`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html#UnityEngine_InputSystem_LowLevel_IInputDeviceCommandInfo_typeStatic) property, which identifies the type of the command. The native implementation of the device should then understand how to handle that command. One common case is they `"HIDO"` command type which is used to send [HID output reports](HID.md#hid-output) to HIDs. +### Adding custom device Comands -### Adding Custom Device Comands +To create custom Device commands (for instance to support some functionality for a specific HID), create a `struct` containing all the data to be sent to the Device, and make that struct implement the [`IInputDeviceCommandInfo`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html) interface by adding a [`typeStatic`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html#UnityEngine_InputSystem_LowLevel_IInputDeviceCommandInfo_typeStatic) property. To send data to a HID, this property should return `"HIDO"`. -To create custom device commands (for instance to support some functionality for a specific HID), create a `struct` containing all the data to be sent to the device, and make that struct implement the [`IInputDeviceCommandInfo`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html) interface by adding a [`typeStatic`](../api/UnityEngine.InputSystem.LowLevel.IInputDeviceCommandInfo.html#UnityEngine_InputSystem_LowLevel_IInputDeviceCommandInfo_typeStatic) property (which should return `"HIDO"` to send data to a HID). +You can then create an instance of this struct and populate all its fields, and send it to the Device using [`InputDevice.ExecuteCommand`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_ExecuteCommand__1___0__). The data layout of the struct must match the native representation of the data as the device interprets it. -You can then create an instance of this struct and populate all it's fields, and send it to the device using [`InputDevice.ExecuteCommand`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_ExecuteCommand__1___0__). The data layout of the struct must match the native representation of the data understood by the device. +## Device state -## 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. -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 +State changes are usually initiated through [state events](Events.md#state-events) coming from the native backend, but you can manually overwrite the state of any Control using [`InputControl<>.WriteValueIntoState()`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_WriteValueIntoState__0_System_Void__). -State changes are usually initiated through [state events](Events.md#state-events) coming from the native backend, but you can overwrite the state of any control manually using [`InputControl<>.WriteValueIntoState()`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_WriteValueIntoState__0_System_Void__). +#### Monitoring state changes -#### 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). -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 -#### Synthesizing State +The Input System can synthesize new state from existing state. An example of such 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. -It can be desirable to make up new state from existing state. An example of such a use case is the [`press`](../api/UnityEngine.InputSystem.Pointer.html#UnityEngine_InputSystem_Pointer_press) control that [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) inherits from [`Pointer`](../api/UnityEngine.InputSystem.Pointer.html). Unlike for the mouse where this is a real button, for [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) this is a [synthetic control](Controls.md#synthetic-controls) that does not correspond to actual data coming in from the device backend. Instead, the button is considered press if any touch is currently ongoing and released otherwise. - -This can be achieved by using [`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 state changes will be directly and synchronously incorporated. State change [monitors](#monitoring-state-changes), however, will still trigger as expected. +This is achieved by using [`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 -In many situations, it is useful to know when new devices are added or when existing devices are removed. To be notified of such changes, use [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange). +In many situations, it is useful to know when new Devices are added or existing Devices are removed. To be notified of such changes, use [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange). ```CSharp InputSystem.onDeviceChange += @@ -146,33 +144,33 @@ InputSystem.onDeviceChange += }; ``` -Notifications through [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange) are always delivered for a host of other device-related changes. See the [`InputDeviceChange` enum](../api/UnityEngine.InputSystem.InputDeviceChange.html) for more details. +[`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 +### Adding and removing Devices -Devices can be manually added and removed through the API, using [`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_). +You can manually add and remove Devices through the API, using [`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. An example for this are the [on-screen controls](OnScreen.md) offered by the input system (while these are provided by the input system, the input devices used for on-screen controls are completely created in code and have no [native representation](#native-devices)). +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. An example for this are the [on-screen Controls](OnScreen.md) provided by the Input System. The Input Devices used for on-screen Controls are created entirely in code and have no [native representation](#native-devices). -### Creating Custom Devices +### Creating custom Devices ->NOTE: Here we will deal only with devices that have fixed layouts, i.e. with the case where we know exactly the specific model or models that we are dealing with. This is different from an interface such as HID where devices can describe themselves through the interface and may thus take a wide variety of forms. In this case, no fixed device layout will likely suffice. This more complicated case requires what in the input system is called a [Layout Builder](Layouts.md#layout-builders) which can build device layouts on the fly from information obtained at runtime. +>__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#layout-builders) to build Device layouts on the fly from information you obtain at run time. -The need to create a custom device generally arises in one of two ways: +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 that you want to reflect into the input system. -2. You have a HID that is either ignored entirely by the input system or gets an auto-generated layout that does not work well enough for your needs. +1. You have an existing API that generates input and that you want to reflect into the Input System. +2. You have a HID that is either ignored entirely by the Input System, or gets an auto-generated layout that does not work well enough for your needs. -In case 2), see [Overriding the HID Fallback](HID.md#overriding-the-hid-fallback) for details. +For the second scenario, see [Overriding the HID Fallback](HID.md#overriding-the-hid-fallback). -Here we will deal with case 1) where we want to create a new input device entirely from scratch and feed it input that we receive from a third-party API. +The steps below deal with the first scenario, where you want to create a new Input Device entirely from scratch and feed it input from a third-party API. -#### Step 1: The State Struct +#### Step 1: The state struct -The first step is to create a C# `struct` that represents the form in which input is received and stored and also describes the `InputControl` instances that should be created for the device in order to retrieve said state. +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 should be created for the Device in order to retrieve said state. ```CSharp -// A "state struct" describes the memory format used by a device. Each device can +// A "state struct" describes the memory format used by a Device. Each Device can // receive and store memory in its custom format. InputControls are then connected // the individual pieces of memory and read out values from them. // @@ -184,10 +182,10 @@ public struct MyDeviceState : IInputStateTypeInfo { // Every state format is tagged with a FourCC code that is used for type // checking. The characters can be anything. Choose something that allows - // you do easily recognize memory belonging to your own device. + // you do easily recognize memory belonging to your own Device. public FourCC format => return new FourCC('M', 'Y', 'D', 'V'); - // InputControlAttributes on fields tell the input system to create controls + // 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 @@ -206,62 +204,60 @@ public struct MyDeviceState : IInputStateTypeInfo } ``` -The [`InputControlAttribute`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html) annotations are used by the input system's layout mechanism to add controls to the layout of your device. For details, see the [documentation of the layout system](Layouts.md). +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, we now have a way to send input data to the input system and to store it there. The next thing we need is an [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) that uses our custom state struct and represents our custom device. +With the state struct in place, you now have a way to send input data to the Input System and to 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 +#### Step 2: The Device class -Next, we need a class derived from one of the [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) base classes. We can either base our device directly on [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) or we can go and pick one of the more specific types of devices like [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html), for example. +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 types like [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html). -Let's assume that our device isn't really like any of the existing device classes and thus derive directly from [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html). +Let's assume that your Device doesn't fit into any of the existing Device classes and thus derive directly from [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html). ```CSharp // InputControlLayoutAttribute attribute is only necessary if you want -// to override default behavior that occurs when registering your device +// to override default behavior that occurs when registering 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, we added two controls that we now want to - // surface on the device. This is for convenience only. The controls will - // get added to the device either way. Exposing them as properties will - // simply make it easier to get to the controls in code. + // In the state struct, we added two Controls that we now want to + // surface on the Device. This is for convenience only. The Controls will + // get added to the Device either way. Exposing them as properties will + // simply make it easier to get to the Controls in code. public ButtonControl button { get; private set; } public AxisControl axis { get; private set; } - // This method is called by the input system after the device has been + // This method is called by the Input System after the Device has been // constructed but before it is added to the system. Here you can do // any last minute setup. protected override void FinishSetup() { base.FinishSetup(); - // NOTE: The controls are *created* by the input system automatically. + // NOTE: The Controls are *created* by the Input System automatically. // This is why don't do `new` here but rather just look - // the controls up. + // the Controls up. button = GetChildControl("button"); axis = GetChildControl("axis"); } } ``` -#### Step 3: The Update Method +#### Step 3: The Update method -By now, we have a device in place along with its associated state format, but if we now create the device like so +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(); ``` -While this creates a fully set up device with our two controls on it, the device will simply sit there and not do anything. It will not receive input as right now, we don't yet have code that actually generates input. So, let's take care of that next. - -Queuing input is easy. We can do that from pretty much anywhere (even from a thread) using [`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_). For this demonstration, we will make use of [`IInputUpdateCallbackReceiver`](../api/UnityEngine.InputSystem.LowLevel.IInputUpdateCallbackReceiver.html) which, when implemented by any [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html), will add 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 thus can feed input events into the current input update. +However, this Device doesn't receive input yet, because you haven't added any code that actually 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 virtually 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 feeds input events into the current input update. ->NOTE: To reemphasize, you don't need to do it this way. If you already have a place where input for your device becomes available, you can simply queue input events from there instead of using [`IInputUpdateCallbackReceiver`](../api/UnityEngine.InputSystem.LowLevel.IInputUpdateCallbackReceiver.html). +>__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 @@ -278,11 +274,11 @@ public class MyDevice : InputDevice, IInputUpdateCallbackReceiver } ``` -#### Step 4: Registration and Creation +#### Step 4: Device registration and creation -Now we have a functioning device but there is not yet a place where the device will actually get added to the system. Also, because we are not yet registering our new type of device, we won't see it in the editor when, for example, creating bindings in the [action editor](ActionAssets.md#editing-input-action-assets). +You now have a functioning device, but you haven't added it to the system yet. Also, because the device hasn't been registered, you won't see it in the editor when, for example, you create bindings in the [action editor](ActionAssets.md#editing-input-action-assets). -One way to register out type of device with the system is to do some from within code that runs automatically as part of Unity starting up. To do so, we can modify the definition of `MyDevice` like so. +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 @@ -296,10 +292,10 @@ 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 - // control) like in our case. + // 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 + // Control) like in our case. InputSystem.RegisterLayout(); } @@ -311,9 +307,9 @@ public class MyDevice : InputDevice, IInputUpdateCallbackReceiver } ``` -This registers the device type with the system and we will see it in the control picker, for example. However, we still need a way to actually add an instance of the device when it is connected. +This registers the Device type with the system and makes it available in the Control picker. However, you still need a way to actually add an instance of the Device when it is connected. -We could just call [`InputSystem.AddDevice()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_AddDevice__1_System_String_) somewhere but in a real-world setup, you will likely have to correlate the InputDevices you create with their identities in the third-party API. It may be tempting to do something like this +In theory, you could call [`InputSystem.AddDevice()`](../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. Itmight be tempting to do something like this ```CSharp public class MyDevice : InputDevice, IInputUpdateCallbackReceiver @@ -325,11 +321,9 @@ public class MyDevice : InputDevice, IInputUpdateCallbackReceiver } ``` -and then set that on the device after calling [`AddDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_AddDevice__1_System_String_) but this will not work as expected. At least not in the editor. - -The reason for this is rather technical in nature. The input system requires that devices can be created solely from their [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) in combination with the chosen layout (and layout variant). In addition to that, a fixed set of mutable per-device properties are supported such as device usages (i.e. [`InputSystem.SetDeviceUsage()`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_SetDeviceUsage_UnityEngine_InputSystem_InputDevice_System_String_) and related methods). This is what allows the system to easily re-create devices after domain reloads in the editor as well as to create replicas of remote devices when connecting to a player. +and then set that on the Device after calling [`AddDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_AddDevice__1_System_String_) but this doesn't work as expected in the editor. -To comply with this requirement is actually rather simple. We simply cast that information provided by the third-party API into an [`InputDeviceDescription`](../api/UnityEngine.InputSystem.Layouts.InputDeviceDescription.html) and then use what's referred to as an [`InputDeviceMatcher`](../api/UnityEngine.InputSystem.Layouts.InputDeviceMatcher.html) to match the description to our custom `MyDevice` layout. +This is 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. Let's assume that the third-party API has two callbacks like this: @@ -337,14 +331,14 @@ Let's assume that the third-party API has two callbacks like this: public static ThirdPartyAPI { // Let's assume that the argument is a string that contains the - // name of the device and no two devices will have the + // name of the Device and no two Devices will have the // same name in the external API. public static Action deviceAdded; public static Action deviceRemoved; } ``` -Now we can hook into those callbacks and create and destroy devices in response. +You can hook into those callbacks and create and destroy devices in response. ```CSharp // For this demonstration, we use a MonoBehaviour with [ExecuteInEditMode] @@ -366,8 +360,8 @@ public class MyDeviceSupport : MonoBehaviour private void OnDeviceAdded(string name) { - // Feed a description of the device into the system. In response, the - // system will match it to the layouts it has and create a device. + // Feed a description of the Device into the system. In response, the + // system will match it to the layouts it has and create a Device. InputSystem.AddDevice( new InputDeviceDescription { @@ -394,7 +388,7 @@ public class MyDeviceSupport : MonoBehaviour // we change the registration to also supply a matcher. protected void Awake() { - // Add a match that catches any input device that reports its + // Add a match that catches any Input Device that reports its // interface as being "ThirdPartyAPI". InputSystem.RegisterLayout( matches: new InputDeviceMatcher() @@ -403,9 +397,9 @@ public class MyDeviceSupport : MonoBehaviour } ``` -#### Step 5: `current` and `all` (Optional) +#### Step 5: `current` and `all` (optional) -It can be very convenient to quickly access the last used device of a given type or to quickly list all devices of a specific type. We can do this by simply adding support for a `current` and for an `all` getter to the API of `MyDevice`. +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 @@ -437,5 +431,5 @@ public class MyDevice : InputDevice, IInputCallbackReceiver } ``` [//]: # (#### 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, i.e. it is data traveling __to__ the input device – and which may optionally also return data as part of the operation (much like a function call). This can be used to communicate with the backend of the device to query configuration or initiate effects such as haptics.) +[//]: # (A final, but optional, step is to add support for Device commands. A "device command" is that opposite of input, i.e. it is data traveling __to__ the input device – and which may optionally also return data as part of the operation (much like a function call). This can be used to communicate with the backend of the device to query configuration or initiate effects such as haptics.) [//]: # (TODO: ATM we're missing an overridable method to make this work) diff --git a/Packages/com.unity.inputsystem/Documentation~/Events.md b/Packages/com.unity.inputsystem/Documentation~/Events.md index 92ad48fbf8..c1161ce789 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Events.md +++ b/Packages/com.unity.inputsystem/Documentation~/Events.md @@ -1,80 +1,84 @@ ->NOTE: Events are an advanced, mostly internal feature of the input system. It is not necessary to understand this feature to use the input system. Knowledge of the event system is mostly useful when wanting to support custom devices or when wanting to modify the behavior of existing devices. +>__Note____: Events are an advanced, mostly internal feature of the Input System. You don't need to understand them to use 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 +# 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) - * [Monitoring Events](#monitoring-events) - * [Reading State Events](#reading-state-events) - * [Creating Events](#creating-events) - * [Capturing Events](#capturing-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) + * [Monitoring events](#monitoring-events) + * [Reading state events](#reading-state-events) + * [Creating events](#creating-events) + * [Capturing events](#capturing-events) -The input system is event-driven. All input is delivered as events and custom input can be generated by injecting events. Also, by listening in on the events flowing through the system, all source input can be observed. +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. -Input events are a low-level mechanism. You will usually not need to deal with events yourself when all you want to do is receive input for your game. Events are stored in unmanaged memory buffers and not converted to C# heap objects. Wrapper APIs are provided but for more involved event manipulations, unsafe code is required. +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 is no routing mechanism. Events are delivered from the runtime straight to the input system where they are incorporated directly into device state. +Note that there is no routing mechanism. Events are delivered from the runtime straight to the Input System, where they are incorporated directly into Device state. -Input events are represented by the [`InputEvent`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html) struct. Each event has a set of properties common to all events: +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 of the event.| +|[`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.| -|[`deviceId`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_deviceId)|ID of the device that the event is targeted at.| +|[`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.| -The events received for a specific input device can be observed in the [input debugger](Debugging.md#debugging-devices). +You can observe the events received for a specific input device in the [input debugger](Debugging.md#debugging-devices). -## Types of Events +## Types of events -### State Events +### State events -A state event contains input state for a device. These events are what gets new input into the system. +A state event contains 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 the device. The [`stateFormat`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html#UnityEngine_InputSystem_LowLevel_StateEvent_stateFormat) field identifies the type of the data in the event. The raw data can be accessed using the [`state`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html#UnityEngine_InputSystem_LowLevel_StateEvent_state) pointer and is [`stateSizeInBytes`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html#UnityEngine_InputSystem_LowLevel_StateEvent_stateSizeInBytes) long. +[`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). -[`DeltaStateEvent`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html) are like [`StateEvent`](../api/UnityEngine.InputSystem.LowLevel.StateEvent.html), but a [`DeltaStateEvent`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html) will only contain a partial snapshot of the state of a device. This is usually sent by the backend for devices requiring a large state record to reduce the amount of memory which needs to be updated if only some of the controls change their state. The raw data can be accessed using the [`deltaState`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html#UnityEngine_InputSystem_LowLevel_DeltaStateEvent_deltaState) pointer and is [`deltaStateSizeInBytes`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html#UnityEngine_InputSystem_LowLevel_DeltaStateEvent_deltaStateSizeInBytes) long. The data should be applied to the device's state at the offset at [`stateOffset`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html#UnityEngine_InputSystem_LowLevel_DeltaStateEvent_stateOffset). +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 backend usually sends this for Devices requiring a large state record to reduce the amount of memory which needs to be updated if only some of the Controls change their state. You can access the raw data using 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 data should be applied to the Device's state at the offset at [`stateOffset`](../api/UnityEngine.InputSystem.LowLevel.DeltaStateEvent.html#UnityEngine_InputSystem_LowLevel_DeltaStateEvent_stateOffset). -### Device Events +### Device events -Device events indicate a change that is relevant to a device as a whole. If you are 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. +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 two types of Device events: * [`DeviceRemoveEvent`](../api/UnityEngine.InputSystem.LowLevel.DeviceRemoveEvent.html) (`'DREM'`) * [`DeviceConfigurationEvent`](../api/UnityEngine.InputSystem.LowLevel.DeviceConfigurationEvent.html) (`'DCFG'`) -`DeviceRemovedEvent` indicates that a device has been removed/disconnected. The device which has been removed can be queried from the common [`deviceId`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_deviceId) field. This event does not have any additional data. +`DeviceRemovedEvent` indicates that a Device has been removed or disconnected. You can query the device which has been removed from 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 may 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 does not have any additional data. -`DeviceConfigurationEvent` indicates that the configuration of a device has changed. The meaning of this is device-specific. This may 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. The device which has been changed can be queried from the common [`deviceId`](../api/UnityEngine.InputSystem.LowLevel.InputEvent.html#UnityEngine_InputSystem_LowLevel_InputEvent_deviceId) field. This event does not have any additional data. +### Text events -### 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. -These events are sent by [Keyboard](Keyboard.md) devices to handle text input. If you are interested in these events, it is usually more convenient to subscribe to the higher-level [callbacks on the Keyboard class](Keyboard.md#text-input) rather then 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 +## Working with events -### Monitoring Events +### Monitoring 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. -### Reading State Events +### 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. +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 the state is meant for. Any control can be asked to read its value from a given event rather than from its own internally stored state. +The easiest way to access state contained in a state event is to rely on the Device 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). @@ -97,17 +101,17 @@ InputSystem.onEvent += }; ``` -### Creating Events +### Creating events -New input events can be created and queued by anyone and against any existing device. Queueing an input event is thread-safe meaning that event generation can happen in background threads. +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: Memory allocated to events coming from background threads is limited. If too many events are produced by background threads, queueing an event from a thread will block the thread until the main thread has flushed out the background event queue. +>__Note__: Memory allocated to events coming from background threads is limited. If too many events are produced by background threads, queueing an event from a thread will block the thread until the main thread has flushed out the background event queue. -Note that queuing an event will not immediately consume the event. Processing of events happens on the next update (depending [`InputSettings.updateMode`](Settings.md#update-mode), either manually triggered via [`InputSystem.Update`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update) or triggered automatically as part of the player loop). +Note that queuing an event will not immediately consume the event. Processing of events happens on the next update (depending [`InputSettings.updateMode`](Settings.md#update-mode), it can be either manually triggered via [`InputSystem.Update`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_Update) or triggered automatically as part of the Player loop). -#### Sending State Events +#### Sending state events -The easiest way to create a state event is directly from the device. +The easiest way to create a state event is directly from the Device. ``` // `StateEvent.From` creates a temporary buffer in unmanaged memory holding @@ -121,7 +125,7 @@ using (StateEvent.From(myDevice, out eventPtr)) } ``` -Another way for sending state is to send events for individual controls. +Alternatively, you can send events for individual Controls. ``` // Send event to update leftStick on the gamepad. @@ -129,7 +133,7 @@ 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. It is not supported to, for example, send a delta state event for a button control that is stored as a single bit. +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 diff --git a/Packages/com.unity.inputsystem/Documentation~/Gamepad.md b/Packages/com.unity.inputsystem/Documentation~/Gamepad.md index f09413547c..826519be2e 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Gamepad.md +++ b/Packages/com.unity.inputsystem/Documentation~/Gamepad.md @@ -1,24 +1,24 @@ # Gamepad Support -A [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) is narrowly defined as a device with two thumbsticks, a dpad, and four face buttons. Additionally, they will usually have two shoulder and two trigger buttons. Most gamepads also have two buttons in the middle section of the gamepad. +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 may have additional controls (such as a gyro) which are exposed from the device but each gamepad is guaranteed to at least have the above-mentioned minimum set of controls. +A gamepad may have additional Controls, such as a gyro, which are exposed from the Device. However, all gamepads are guaranteed to have at least the minimum set of Controls described above. -The goal of gamepad support is to guarantee correct location and functioning of controls across platforms and hardware. A PS4 DualShock controller, for example, is meant to look identical regardless of which platform it is supported on. And a gamepad's south face button, for example, is meant to be expected to always indeed be the bottom-most face button. +Gamepad support guarantees the correct location and functioning of Controls across platforms and hardware. A PS4 DualShock controller, for example, is meant to look identical regardless of which platform it is supported on. A gamepad's south face button is meant to be expected to always be the lowermost face button. ## Controls -The following controls are present on every gamepad: +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 in dpad-like fashion.| -|[`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 in dpad-like fashion.| -|[`dpad`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_dpad)|Dpad|| -|[`buttonNorth`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_buttonNorth)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The upper one of the four actions buttons (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 one of the four actions buttons (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 one of the four actions buttons (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 one of the four actions buttons (usually located on the right side of the gamepad). Labelled "B" on Xbox controllers and "Circle" on PlayStation controllers.| +|[`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 in D-pad-like fashion.| +|[`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 in D-pad-like fashion.| +|[`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 one of the four actions 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 one of the four actions 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 one of the four actions 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 one of the four actions 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.| @@ -28,15 +28,15 @@ The following controls are present on every gamepad: |[`leftStickButton`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_leftStickButton)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The button pressed by pressing down the left stick.| |[`rightStickButton`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightStickButton)|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|The button pressed by pressing down the right stick.| ->NOTE: Be aware that buttons are also full floating-point axes. This means that, for example, the left and right triggers can function both as buttons as well as full floating-point axes. +>__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. -Gamepad buttons can also be accessed 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: +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. The following four accessors all retrieve the same "north" face button, for example: +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] @@ -47,16 +47,16 @@ Gamepad.current["Triangle"] ## Polling -On Windows (XInput controllers only), UWP and Switch, gamepads are polled explicitly by Unity, rather than delivered as events. +On Windows (XInput controllers only), UWP and Switch, Unity polls gamepads explicitly rather than deliver updates as events. -The frequency of the polling can be controlled 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. +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 following the spacing dicated by the polling frequency. Note, however, that the asynchronous background polling depends on OS thread scheduling and is thus susceptible to variance. +Increased frequency should lead to an increased number of events on the respective Devices. The timestamps provided on the events should roughly following the spacing dicated by the polling frequency. Note, however, that the asynchronous background polling depends on OS thread scheduling and can vary. ## Rumble @@ -68,17 +68,17 @@ The [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) class implements th 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 (requires console-specific packages to be installed in your project). +>__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 +### 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, and allows you to 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. +[`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. This allows you to 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 can be desirable to globally pause or stop haptics for all devices in certain situation. For example, if the player enters the in-game menu, it can make sense to pauses haptics while the player is in the menu and then resume haptics effects once the player resumes the game. You can use the corresponding methods on [`InputSystem`](../api/UnityEngine.InputSystem.InputSystem.html) for that (which work the same way as the per-device methods, but affect all devices): +In certain situations, you might want to globally pause or stop haptics for all Devices. For example, if the player enters the 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. @@ -91,39 +91,38 @@ InputSystem.ResumeHaptics(); 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 will reset haptics playback state on each device to its initial state whereas [`PauseHaptics`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_PauseHaptics) will preserve playback state in memory and only stop playback on the hardware. +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 will reset haptics playback state on each Device to its initial state whereas [`PauseHaptics`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_PauseHaptics) will preserve playback state in memory and only stop playback on the hardware. ## PlayStation controllers -PlayStation controllers are well supported on different devices. They are implemented as different derived types of the [`DualShockGamepad`](../api/UnityEngine.InputSystem.DualShock.DualShockGamepad.html) base class (which itself derives from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html)): +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, and does not support [rumble](#rumble). +* [`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). +* [`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. [`DualShock4GamepadHID`](../api/UnityEngine.InputSystem.DualShock.DualShock4GamepadHID.html) implements additional, DualShock-specific functionality on top the general support in the [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) class: * [`SetLightBarColor(Color)`](../api/UnityEngine.InputSystem.DualShock.DualShockGamepad.html#UnityEngine_InputSystem_DualShock_DualShockGamepad_SetLightBarColor_Color_): Lets you set the color of the light bar on the controller. ->NOTES: ->* We support PlayStation controllers on WebGL in some browser/OS configs, but they will always be represented as basic [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) or [`Joystick`](../api/UnityEngine.InputSystem.Joystick.html) devices, and we do not support Rumble or any other DualShock specific functionality. ->* We do not support the "DualShock 4 USB Wireless Adaptor" to connect a PlayStation controller to a desktop machine. Use USB or Bluetooth to connect it. +>__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 -Xbox controllers are well supported on different devices. They are implemented using the [`XInputController`](../api/UnityEngine.InputSystem.XInput.XInputController.html) class, (which derives from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html)). On Windows/UWP, any type of supported XInput controller (which includes all Xbox One or Xbox 360 compatible controllers) will be connected to using the XInput API and is represented directly 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 (wheel, gamepad, etc). +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 connects to any type of supported XInput controller, including all Xbox One or Xbox 360-compatible controllers, using the XInput API. 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 we use specific derived classes to represent Xbox controllers: +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). No additional driver is needed for this case. - ->NOTES: ->* XInput controllers on Mac currently require the installation of the [Xbox Controller Driver for macOS](https://github.com/360Controller/360Controller). Only USB connections are supported, no wireless dongles. However, the latest generation of Xbox One controllers natively supported Bluetooth, and are natively supported on Macs as HID devices without any additional driver when connected via Bluetooth. ->* We support Xbox controllers on WebGL in some browser/OS configs, but they will always be represented as basic [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) or [`Joystick`](../api/UnityEngine.InputSystem.Joystick.html) devices, and we do not support Rumble or any other Xbox specific functionality. +* [`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. +>__Note__: +>* XInput controllers on Mac currently require the installation of the [Xbox Controller Driver for macOS](https://github.com/360Controller/360Controller). Only USB connections are supported by this driver, no wireless dongles. However, the latest generation of Xbox One controllers natively supported 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 -We support Switch Pro controllers on desktop computers via the [`SwitchProControllerHID`](../api/UnityEngine.InputSystem.Switch.SwitchProControllerHID.html) class, which implements the basic gamepad functionality. +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. diff --git a/Packages/com.unity.inputsystem/Documentation~/HID.md b/Packages/com.unity.inputsystem/Documentation~/HID.md index 41ea17b7d3..06315f88f7 100644 --- a/Packages/com.unity.inputsystem/Documentation~/HID.md +++ b/Packages/com.unity.inputsystem/Documentation~/HID.md @@ -1,49 +1,49 @@ # HID Support -HID ("Human interface device") 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, Racing Wheels, etc. +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. -HIDs (both via USB and via Bluetooth) are directly supported by the input system on Windows, MacOS, and UWP. On other platforms, HIDs may be supported but not delivered through HID-specific APIs (example: on Linux, gamepad and joystick HIDs are supported through SDL; other HIDs are not supported). +The Input System directly supports HIDs (connected via both USB and Bluetooth) on Windows, MacOS, and UWP. The system might support HIDs 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 descriptor that describes the device. The descriptor of a HID can be browsed through from the input debugger by pressing the "HID Descriptor" button in the device debugger window. The HID descriptor specifies the type of the device (by reporting 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. +Every HID comes with a device descriptor. You can browse through the descriptor of an HID from the Input Debugger by pressing the __HID Descriptor__ button in the device debugger window. The HID descriptor specifies the type of the device by reporting 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. ![HID Descriptor](Images/HIDDescriptor.png) -HIDs are handled in one of two ways: +The Input System handles HIDs in one of two ways: 1. The system has a known layout for the specific HID. 2. A layout is auto-generated for the HID on the fly. ## Auto-generated layouts -By default, the input system will create layouts and device representations for any HID which reports it's 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 info). You can change the list of supported usages by setting [`HIDSupport.supportedHIDUsages`](../api/UnityEngine.InputSystem.HID.HIDSupport.html#UnityEngine_InputSystem_HID_HIDSupport_supportedHIDUsages). +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). You can change the list of supported usages by setting [`HIDSupport.supportedHIDUsages`](../api/UnityEngine.InputSystem.HID.HIDSupport.html#UnityEngine_InputSystem_HID_HIDSupport_supportedHIDUsages). -Nor when the input system automatically create a layouts for a HID, these devices are currently always reported 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. Then controls are added for all further HID axis or button elements, using the control names reported by the HID specification (which tend to be rather generic). The first control with a HID usage of `Button/Button 1` will be assigned to the joystick's [`trigger`](../api/UnityEngine.InputSystem.Joystick.html#UnityEngine_InputSystem_Joystick_trigger) control. +When the Input System automatically creates a layouts for a 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. As the way HIDs describe themselves as per standard is too ambiguous in practice, generated layouts may lead to controls that do not work the way they should. 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 are not assigned any meaning in HID. +The auto-generated layouts represent a "best effort" on the part of the Input System. As the way HIDs describe themselves as per standard is too ambiguous in practice, generated layouts may lead to Controls that do not work the way they should. 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 are not assigned any meaning in HID. -The best way to resolve the situation of HIDs not working as expected is to add a custom layout and thus by-pass auto-generation altogether. See [Overriding the HID Fallback](#overriding-the-hid-fallback) for details. +The best way to resolve the situation of HIDs not working as expected is to add a custom layout, bypassing auto-generation altogether. See [Overriding the HID fallback](#overriding-the-hid-fallback) for details. -## HID Output +## HID output -HIDs can support output, for instance to toggle lights or force feedback motors on a gamepad. Output is controlled by sending commands known as "HID Output Reports" to a device. Output reports use device-specific data formats. You can send a HID Output Reports to a device by calling [`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""`. The command struct will then contain the device-specific data sent out to the HID. +HIDs can support output, for instance 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. You can use HID Output Reports by calling [`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. -## Overriding the HID Fallback +## Overriding the HID fallback -Often, when using the layouts auto-generated for HIDs, the result will be suboptimal. Controls will not receive proper names specific to the device, some controls may not work as expected, and some controls that use vendor-specific formats may not appear altogether. +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 set up a custom device layout specifically for your device. This will override the default auto-generation and give you full control over how the device is exposed. +The best way to deal with this is to 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. -For this demonstration, we pretend that the input system does not already have a custom layout for the PS4 DualShock controller and that we want to add such a layout. +The following example assumes that the Input System didn't already have a custom layout for the PS4 DualShock controller, and that you would want to add such a layout. -We know that we want to expose the controller as a [`Gamepad`](Gamepad.md) and we roughly know the HID data format from various sources on the web. So, let's take it step by step from here. +You want to expose the controller as a [`Gamepad`](Gamepad.md) and you roughly know the HID data format used by the Device. ->NOTE: In case you do __not__ know the format of a given HID you want to support, a good strategy can be to just open the input debugger with the device plugged in and pop up both the debugger view for the device as well as 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. It can also be useful to 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 and choose "Compare" to get a view that shows only the differences between the two events. +>__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 +### Step 1: The state struct -First step is describing to the input system in detail the format that input data for the device comes in as well as describing the [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html) instances that should read out individual pieces of information from that data. +The first step is describing 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. -We know that the HID input reports we get from the PS4 controller roughly look like this: +The HID input reports you get from the PS4 controller roughly look like this: ```C++ struct PS4InputReport @@ -74,7 +74,7 @@ struct PS4InputReport } ``` -Based on this, we can quite straightforwardly translate this into a C# struct: +You can translate this into a C# struct: ```CSharp // We receive data as raw HID input reports. Thus this struct @@ -161,18 +161,16 @@ struct DualShock4HIDInputReport : IInputStateTypeInfo } ``` -Assembling that struct was quite involved. Luckily, this concludes the hard part. The rest is just some easy setup code. - ### Step 2: The InputDevice -Next, we need an `InputDevice` to represent our device. Given that we are dealing with a gamepad, we do so by creating a new subclass of `Gamepad`. +Next, you need an `InputDevice` to represent your device. Since you are dealing with a gamepad, you must create a new subclass of `Gamepad`. ->For simplicity's sake we ignore the fact here that there is a class `DualShockGamepad` that the actual `DualShockGamepadHID` is based on. +For simplicity's sake, this example ignores the fact here that there is a class `DualShockGamepad` that the actual `DualShockGamepadHID` is based on. ```CSharp // Using InputControlLayoutAttribute, we tell the system about the state // struct we created and thus also about where to find all the InputControl -// attributes that we placed on there. This is how the input system knows +// 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 @@ -182,11 +180,11 @@ public DualShock4GamepadHID : Gamepad ### Step 3: Registering the Device -The last step is to register our new type of device with the system and set things up such that when a PS4 controller is connected, it will get picked up by our custom device and not by the default HID fallback. +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, it will generate your custom Device instead of using the default HID fallback. -In essence, all this requires is a call to [`InputSystem.RegisterLayout`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterLayout__1_System_String_System_Nullable_UnityEngine_InputSystem_Layouts_InputDeviceMatcher__) and giving it an [`InputDeviceMatcher`](../api/UnityEngine.InputSystem.Layouts.InputDeviceMatcher.html) that matches the description for a PS4 DualShock HID. We can theoretically place this call anywhere but the best point for registering layouts is generally during startup. Doing so ensures that our custom layout is visible to the Unity editor and thus can be seen, for example, in the input control picker. +This only requires a call to [`InputSystem.RegisterLayout`](../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. -We can do insert our registration into the startup sequence by modifying the code for our `DualShock4GamepadHID` device slightly. +You can insert your registration into the startup sequence by modifying the code for your `DualShock4GamepadHID` Device slightly. ```CSharp [InputControlLayout(stateType = typeof(DualShock4HIDInputReport)] @@ -197,7 +195,7 @@ public DualShock4GamepadHID : Gamepad { static DualShock4GamepadHID() { - // This is one way to match the device. + // This is one way to match the Device. InputSystem.RegisterLayout( new InputDeviceMatcher() .WithInterface("HID") @@ -220,4 +218,4 @@ public DualShock4GamepadHID : Gamepad } ``` -Now, any device matching the manufacturer and product name strings or the vendor and product IDs in its HID descriptor will be picked up by our custom layout, and be represented in the system as a `DualShock4GamepadHID` device instance. Also check the documentation about [device matching](Devices.md#matching). +Your custom layout now picks up any Device matching the manufacturer and product name strings or the vendor and product IDs in its HID descriptor, and the Input System represents as a `DualShock4GamepadHID` Device instance. For more information, you can also read the documentation on [Device matching](Devices.md#matching). diff --git a/Packages/com.unity.inputsystem/Documentation~/HowDoI.md b/Packages/com.unity.inputsystem/Documentation~/HowDoI.md index 3a812908d0..da8e94b672 100644 --- a/Packages/com.unity.inputsystem/Documentation~/HowDoI.md +++ b/Packages/com.unity.inputsystem/Documentation~/HowDoI.md @@ -1,31 +1,36 @@ -# How Do I...? +# How do I…? Devices: -* [... check if the space key has been pressed this frame?](#-check-if-the-space-key-has-been-pressed-this-frame) -* [... find all connected gamepads?](#-find-all-connected-gamepads) -* [... find the gamepad currently used by the player?](#-find-the-gamepad-currently-used-by-the-player) -* [... know when a new device has been plugged in?](#-know-when-a-new-device-has-been-plugged-in) +* […check if the space key has been pressed this frame?](#check-if-the-space-key-has-been-pressed-this-frame) +* […find all connected gamepads?](#find-all-connected-gamepads) +* […find the gamepad currently used by the player?](#find-the-gamepad-currently-used-by-the-player) +* […know when a new device has been plugged in?](#know-when-a-new-device-has-been-plugged-in) Actions: -UIs: +* […create a simple Fire-type Action?](#create-a-simple-fire-type-action) +* […require a button to be held for 0.4 seconds before triggering an Action?](#require-a-button-to-be-held-for-0.4-seconds-before-triggering-an-action) +* […use a "positive" and a "negative" button to drive an axis?](#use-a-positive-and-a-negative-button-to-drive-an-axis) +* […create a UI to rebind input in my game?](#create-a-ui-to-rebind-input-in-my-game) -## ... check if the space key has been pressed this frame? +## …check if the space key has been pressed this frame? + +Use this code: ```CSharp Keyboard.current.space.wasPressedThisFrame ``` -Same deal works for other devices. +You can adapt this code to other Devices that have buttons or other types of input: ```CSharp Gamepad.current.aButton.wasPressedThisFrame ``` -## ... find all connected gamepads? +## …find all connected gamepads? -You can ask [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html). +Use the [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) class: ```CSharp var allGamepads = Gamepad.all; @@ -34,7 +39,7 @@ You can ask [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html). var allPS4Gamepads = DualShockGamepadPS4.all; ``` -Or you have some more involved options: +Alternatively, you can use more generic Device queries using LINQ expressions or [control paths](Controls.md#control-paths): ```CSharp @@ -46,9 +51,9 @@ Or you have some more involved options: InputSystem.FindControls(""); ``` -The last solution uses [control paths](Controls.md#control-paths). +## …find the gamepad currently used by the player? -## ... find the gamepad currently used by the player? +Use this code: ```CSharp var gamepad = Gamepad.current; @@ -58,7 +63,9 @@ The last solution uses [control paths](Controls.md#control-paths). var mouse = Mouse.current; ``` -# ... know when a new device has been plugged in? +# …know when a new Device has been plugged in? + +Use this code: ```CSharp InputSystem.onDeviceChange += @@ -76,7 +83,7 @@ The last solution uses [control paths](Controls.md#control-paths). // Plugged back in break; case InputDeviceChange.Removed: - // Remove from input system entirely; by default, devices stay in the system once discovered + // Remove from Input System entirely; by default, devices stay in the system once discovered break; default: // See InputDeviceChange reference for other event types. @@ -85,11 +92,11 @@ The last solution uses [control paths](Controls.md#control-paths). } ``` -For more details, see ["Monitoring Devices"](Devices.md#monitoring-devices). +For more details, see documentation on ["Monitoring Devices"](Devices.md#monitoring-devices). -# ... create a simple fire-type action? +# …create a simple Fire-type Action? -One way to do so is directly in code: +Use this code: ```C# // Create action that binds to the primary action control on all devices. @@ -102,7 +109,7 @@ One way to do so is directly in code: action.Enable(); ``` -The second way is to simply have a serialized field of type InputAction in your MonoBehaviour like this: +You can also have a serialized field of type `InputAction` in your `MonoBehaviour`, like this: ```C# @@ -114,9 +121,9 @@ public class MyControllerComponent : MonoBehaviour ``` -In the editor, you will be presented with a nice inspector that allows you to add bindings to the actions and choose where the bindings go without having to fiddle around with path strings. +The Editor lets you add and edit Bindings for the Actions in the Inspector window. -Note that you still need to enable the action in code and hook up your response. You can do so in the `Awake` method of your component. +>__Note__: You still need to enable the action in code and hook up your response. You can do so in the `Awake` method of your component: ```C# @@ -150,7 +157,7 @@ Note that you still need to enable the action in code and hook up your response. ``` -If you are worried about GC from the delegates, you can also use a polling approach rather than a callback-driven approach. +If you are worried about allocations from the delegates, you can use a polling approach rather than a callback-driven approach. ```C# @@ -186,7 +193,13 @@ If you are worried about GC from the delegates, you can also use a polling appro ``` -Typically you need to deal with multiple actions. In this case you may want to put these into an Input Actions asset file. Create an Input Actions asset by selecting `Input Actions` in the `Create` popup button in the Project view. Double click the asset to create and edit one of multiple Input Action maps containing Input Actions. If you then click `Generate C# Class` in the inspector for the asset, Unity will generate a wrapper class for your actions which you can use like this: +Typically, you need to deal with more than one action. In this case, you might want to put these into an Input Actions Asset file. To create an Input Actions Asset, follow these steps: + +1. In the Project view, click __Create__ +2. Select __Input Actions__ +3. Double click the Asset to create and edit one or multiple Input Action Maps containing Input Actions. + +If you then click __Generate C# Class__ in the Inspector for that Asset, Unity generates a wrapper class for your Actions which you can use like this: ```C# MyInputActionAssetClass actions; @@ -199,11 +212,11 @@ Typically you need to deal with multiple actions. In this case you may want to p } ``` -For more details, see ["Actions"](Actions.md). +For more details, see documentation on ["Actions"](Actions.md). -# ... require a button to be held for 0.4 seconds before triggering an action? +# …require a button to be held for 0.4 seconds before triggering an Action? -Put a Hold interaction on the action. In code, this works like so: +Put a [hold Interaction](Interactions.md#hold) on the action, like this: ```C# @@ -222,9 +235,9 @@ To display UI feedback when the button starts being held, use the [`started`](.. ``` -# ... use a "positive" and a "negative" button to drive an axis? +# …use a "positive" and a "negative" button to drive an axis? -Use an "Axis" composite binding in the UI or in code and bind its parts to the respective buttons. +Use an [axis composite](ActionBindings.md#1d-axis) binding in the UI or in code, and bind its parts to the respective buttons. ```CSharp var accelerateAction = new InputAction("Accelerate"); @@ -233,9 +246,7 @@ accelerateAction.AddCompositeBinding("Axis") .With("Negative", "/leftTrigger"); ``` -There are parameters available to tweak the axis' behavior. See [here](ActionBindings.md#1d-axis) for details. - -# ... create a UI to rebind input in my game? +# …create a UI to rebind input in my game? Create a UI with a button to trigger rebinding. If the user clicks the button to bind a control to an action, use [`InputAction.PerformInteractiveRebinding`](../api/UnityEngine.InputSystem.InputActionRebindingExtensions.html#UnityEngine_InputSystem_InputActionRebindingExtensions_PerformInteractiveRebinding_UnityEngine_InputSystem_InputAction_) to handle the rebinding: @@ -250,21 +261,23 @@ Create a UI with a button to trigger rebinding. If the user clicks the button to } ``` -[//]: # (TODO: Link the remap screen from tanks demo once that has a linkable home) +You can install the Tanks Demo sample for the Input System package using the Package Manager, which has an example of an interactive rebinding UI. + +# …set up an action to specifically target the left-hand XR controller? -# ... set up an action to specifically target the left-hand XRController? +Use this code: ```CSharp var action = new InputAction(binding: "/{leftHand}/position"); ``` -Again, the inspector allows setting this up without having to deal with paths directly. +You can also set this up for any Input Bindings in the Inspector or the Input Action Asset editor window without having to deal with paths directly. -# ... wait for any button to be pressed on any device? +# …wait for any button to be pressed on any device? [//]: # (TODO this needs work) -One way is to use actions. +Use this code: ```CSharp var myAction = new InputAction(binding: "/*/