diff --git a/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md b/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md index 9c164e2439..44636aed3a 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md +++ b/Packages/com.unity.inputsystem/Documentation~/ActionBindings.md @@ -48,7 +48,7 @@ Each Binding has the following properties: |[`action`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_action)|The name or ID of the Action that the Binding should trigger. Note that this can be null or empty (for instance, for [composites](#composite-bindings)). Not case-sensitive.

Example: `"fire"`| |[`groups`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_groups)|A semicolon-separated list of Binding groups that the Binding belongs to. Can be null or empty. Binding groups can be anything, but are mostly used for [Control Schemes](#control-schemes). Not case-sensitive.

Example: `"Keyboard&Mouse;Gamepad"`| |[`interactions`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_interactions)|A semicolon-separated list of [Interactions](Interactions.md) to apply to input on this Binding. Note that Unity appends Interactions applied to the [Action](Actions.md) itself (if any) to this list. Not case-sensitive.

Example: `"slowTap;hold(duration=0.75)"`| -|[`processors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_processors)|A semicolon-separated list of [Processors](Processors.md) to apply to input on this Binding. Note that Unity appends Processors applied to the [Action](Actions.md) itself (if any) to this list. Not case-sensitive.

Processors on Bindings apply in addition to Processors on Controls that are providing values. For example, if you put a `stickDeadzone` Processor on a Binding and then bind it to `/leftStick`, you 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)"`| +|[`processors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_processors)|A semicolon-separated list of [Processors](UsingProcessors.md) to apply to input on this Binding. Note that Unity appends Processors applied to the [Action](Actions.md) itself (if any) to this list. Not case-sensitive.

Processors on Bindings apply in addition to Processors on Controls that are providing values. For example, if you put a `stickDeadzone` Processor on a Binding and then bind it to `/leftStick`, you 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. Identifies 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).| @@ -87,7 +87,7 @@ myAction.AddCompositeBinding("Axis") .With("Negative", "/leftShoulder"); ``` -Composites can have parameters, just like [Interactions](Interactions.md) and [Processors](Processors.md). +Composites can have parameters, just like [Interactions](Interactions.md) and [Processors](UsingProcessors.md). ```CSharp myAction.AddCompositeBinding("Axis(whichSideWins=1)"); @@ -466,7 +466,7 @@ You can override aspects of any Binding at run-time non-destructively. Specific |Property|Override|Description| |--------|--------|-----------| |[`path`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_path)|[`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath)|Replaces the [Control path](./Controls.md#control-paths) that determines which Control(s) are referenced in the binding. If [`overridePath`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overridePath) is set to an empty string, the binding is effectively disabled.

Example: `"/leftStick"`| -|[`processors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_processors)|[`overrideProcessors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overrideProcessors)|Replaces the [processors](./Processors.md) applied to the binding.

Example: `"invert,normalize(min=0,max=10)"`| +|[`processors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_processors)|[`overrideProcessors`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overrideProcessors)|Replaces the [Processors](./UsingProcessors.md) applied to the binding.

Example: `"invert,normalize(min=0,max=10)"`| |[`interactions`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_interactions)|[`overrideInteractions`](../api/UnityEngine.InputSystem.InputBinding.html#UnityEngine_InputSystem_InputBinding_overrideInteractions)|Replaces the [interactions](./Interactions.md) applied to the binding.

Example: `"tap(duration=0.5)"`| >NOTE: The `override` property values will not be saved along with the Actions (for example, when calling [`InputActionAsset.ToJson()`](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_ToJson)). See [Saving and loading rebinds](#saving-and-loading-rebinds) for details about how to persist user rebinds. @@ -527,7 +527,7 @@ playerInput.actions["move"] ### Setting parameters -A Binding may, either through itself or through its associated Action, lead to [processor](Processors.md), [interaction](Interactions.md), and/or [composite](#composite-bindings) objects being created. These objects can have parameters you can configure through in the [Binding properties view](ActionsEditor.md#bindings) of the Action editor or through the API. This configuration will give parameters their default value. +A Binding may, either through itself or through its associated Action, lead to [processor](UsingProcessors.md), [interaction](Interactions.md), and/or [composite](#composite-bindings) objects being created. These objects can have parameters you can configure through in the [Binding properties view](ActionsEditor.md#bindings) of the Action editor or through the API. This configuration will give parameters their default value. ```CSharp // Create an action with a "Hold" interaction on it. diff --git a/Packages/com.unity.inputsystem/Documentation~/Architecture.md b/Packages/com.unity.inputsystem/Documentation~/Architecture.md index 427ab04ac5..6b764ab258 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Architecture.md +++ b/Packages/com.unity.inputsystem/Documentation~/Architecture.md @@ -31,4 +31,4 @@ The high-level Input System code interprets the data in a Device's state buffers Based on the information in the layouts, the Input System then creates [Control](Controls.md) representations for each of the Device's controls, which let you read the state of each individual Control in a Device. -As part of the high-level system, you can also build another abstraction layer to map Input Controls to your application mechanics. Use [Actions](Actions.md) to [bind](ActionBindings.md) one or more Controls to an input in your application. The Input System then monitors these Controls for state changes, and notifies your game logic using [callbacks](RespondingToActions.md#responding-to-actions-using-callbacks). You can also specify more complex behaviors for your Actions using [Processors](Processors.md) (which perform processing on the input data before sending it to you) and [Interactions](Interactions.md) (which let you specify patterns of input on a Control to listen to, such as multi-taps). +As part of the high-level system, you can also build another abstraction layer to map Input Controls to your application mechanics. Use [Actions](Actions.md) to [bind](ActionBindings.md) one or more Controls to an input in your application. The Input System then monitors these Controls for state changes, and notifies your game logic using [callbacks](RespondingToActions.md#responding-to-actions-using-callbacks). You can also specify more complex behaviors for your Actions using [Processors](UsingProcessors.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~/Controls.md b/Packages/com.unity.inputsystem/Documentation~/Controls.md index 19292386ea..a728fb5d1a 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/Controls.md @@ -121,7 +121,7 @@ Gamepad.current.leftStick.x.ReadValue(); Each type of Control has a specific type of values that it returns, regardless of how many different types of formats it supports for its state. You can access this value type through the [`InputControl.valueType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_valueType) property. -Reading a value from a Control might apply one or more value Processors. See documentation on [Processors](Processors.md) for more information. +Reading a value from a Control might apply one or more value Processors. See documentation on [Processors](UsingProcessors.md) for more information. [//]: # (#### Default State - TODO) @@ -243,7 +243,7 @@ Use [`InputControl.value`](../api/UnityEngine.InputSystem.InputControl-1.html ### Control Value Caching -When the `'USE_READ_VALUE_CACHING'` internal feature flag is set, the Input System will switch to an optimized path for reading control values. This path efficiently marks controls as 'stale' when they have been actuated. Subsequent calls to [`InputControl.ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) will only apply control processing when there have been changes to that control or in case of control processing. Control processing in this case can mean any hard-coded processing that might exist on the control, such as with [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) which has built-in inversion, normalisation, scaling etc, or any processors that have been applied to the controls' [processor stack](Processors.md#processors-on-controls). +When the `'USE_READ_VALUE_CACHING'` internal feature flag is set, the Input System will switch to an optimized path for reading control values. This path efficiently marks controls as 'stale' when they have been actuated. Subsequent calls to [`InputControl.ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) will only apply control processing when there have been changes to that control or in case of control processing. Control processing in this case can mean any hard-coded processing that might exist on the control, such as with [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) which has built-in inversion, normalisation, scaling etc, or any processors that have been applied to the controls' [processor stack](HowToApplyProcessors.md#processors-on-controls). > Note: Performance improvements **are currently not guaranteed** for all use cases. Even though this performance path marks controls as "stale" in an efficient way, it still has an overhead which can degrade performance in some cases. A positive performance impact has been seen when: diff --git a/Packages/com.unity.inputsystem/Documentation~/Gamepad.md b/Packages/com.unity.inputsystem/Documentation~/Gamepad.md index ad4acf19cf..d5456c7266 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Gamepad.md +++ b/Packages/com.unity.inputsystem/Documentation~/Gamepad.md @@ -67,7 +67,7 @@ Gamepad.current["Triangle"] Deadzones prevent accidental input due to slight variations in where gamepad sticks come to rest at their centre point. They allow a certain small inner area where the input is considered to be zero even if it is slightly off from the zero position. -To add a deadzone to gamepad stick, put a [stick deadzone Processor](Processors.md#stick-deadzone) on the sticks, like this: +To add a deadzone to gamepad stick, put a [stick deadzone Processor](ProcessorTypes.md#stick-deadzone) on the sticks, like this: ```JSON { diff --git a/Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md b/Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md new file mode 100644 index 0000000000..3950c655fd --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md @@ -0,0 +1,79 @@ +--- +uid: input-system-processors +--- +# How to apply Processors + +The particularities between the three different ways of applying Processors to input events. For more information on the general usage of Processors refer to [Using Processors](UsingProcessors.md). + +* [Processors on Bindings](#processors-on-bindings) +* [Processors on Actions](#processors-on-actions) +* [Processors on Controls](#processors-on-controls) + +## Processors on Bindings + +When you create Bindings for your [actions](Actions.md), you can choose to add Processors to the Bindings. These process the values from the controls they bind to, before the system applies them to the Action value. For instance, you might want to invert the `Vector2` values from the controls along the Y axis before passing these values to the Action that drives the input logic for your application. To do this, you can add an [Invert Vector2](ProcessorTypes.md#invert-vector-2) Processor to your Binding. + +If you're using Actions defined in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md), you can add any Processor to your Bindings in the Input Action editor. Select the Binding you want to add Processors to so that the right pane of the window displays the properties for that Binding. Select the Add (+) icon on the __Processors__ foldout to open a list of all available Processors that match your control type, then choose a Processor type to add a Processor instance of that type. The Processor now appears under the __Processors__ foldout. If the Processor has any parameters, you can edit them in the __Processors__ foldout. + +![Binding Processors](Images/BindingProcessors.png) + +To remove a Processor, click the Remove (-) icon next to it. You can also use the up and down arrows to change the order of Processors. This affects the order in which the system processes values. + +If you create your Bindings in code, you can add Processors like this: + +```CSharp +var action = new InputAction(); +action.AddBinding("/leftStick") + .WithProcessor("invertVector2(invertX=false)"); +``` + +## Processors on Actions + +Processors on Actions work in the same way as Processors on Bindings, but they affect all controls bound to an Action, rather than just the controls from a specific Binding. If there are Processors on both the Binding and the Action, the system processes the ones from the Binding first. + +You can add and edit Processors on Actions in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md) the [same way](#processors-on-bindings) as you would for Bindings: select an Action to edit, then add one or more Processors in the right window pane. + +If you create your Actions in code, you can add Processors like this: + +```CSharp +var action = new InputAction(processors: "invertVector2(invertX=false)"); +``` + +## Processors on Controls + +You can have any number of Processors directly on an [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html), which then process the values read from the Control. Whenever you call [`ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) on a Control, all Processors on that Control process the value before it gets returned to you. You can use [`ReadUnprocessedValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValue) on a Control to bypass the Processors. + +The Input System adds Processors to a Control during device creation, if they're specified in the Control's [layout](Layouts.md). You can't add Processors to existing Controls after they've been created, so you can only add Processors to Controls when you're [creating custom devices](Devices.md#creating-custom-devices). The devices that the Input System supports out of the box already have some useful Processors added on their Controls. For instance, sticks on gamepads have a [Stick Deadzone](ProcessorTypes.md#stick-deadzone) Processor. + +If you're using a layout generated by the Input System from a [state struct](Devices.md#step-1-the-state-struct) using [`InputControlAttributes`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html), you can specify the Processors you want to use via the [`processors`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_processors) property of the attribute, like this: + +```CSharp +public struct MyDeviceState : IInputStateTypeInfo +{ + public FourCC format => return new FourCC('M', 'Y', 'D', 'V'); + + // Add an axis deadzone to the Control to ignore values + // smaller then 0.2, as our Control does not have a stable + // resting position. + [InputControl(layout = "Axis", processors = "AxisDeadzone(min=0.2)")] + public short axis; +} +``` + +If you [create a layout from JSON](Layouts.md#layout-from-json), you can specify Processors on your Controls like this: + +```CSharp +{ + "name" : "MyDevice", + "extend" : "Gamepad", // Or some other thing + "controls" : [ + { + "name" : "axis", + "layout" : "Axis", + "offset" : 4, + "format" : "FLT", + "processors" : "AxisDeadzone(min=0.2)" + } + ] +} +``` diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Clamp-Editor.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Clamp-Editor.png new file mode 100644 index 0000000000..5e8ef1355c Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Clamp-Editor.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Deadzone-Editor.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Deadzone-Editor.png new file mode 100644 index 0000000000..8114f31bf5 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Deadzone-Editor.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Invert-Editor.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Invert-Editor.png new file mode 100644 index 0000000000..5f4eb69a59 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Invert-Editor.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Normalize-Fast.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Normalize-Fast.png new file mode 100644 index 0000000000..5aaf978ddf Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Normalize-Fast.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Normalize-Slow.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Normalize-Slow.png new file mode 100644 index 0000000000..6e4fa8eb70 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Normalize-Slow.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-NormalizeAsset.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-NormalizeAsset.png new file mode 100644 index 0000000000..074a5ecf75 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-NormalizeAsset.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look-Pointer.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look-Pointer.png new file mode 100644 index 0000000000..594dc9a8d7 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look-Pointer.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look-Stick.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look-Stick.png new file mode 100644 index 0000000000..f5e587314a Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look-Stick.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look.png new file mode 100644 index 0000000000..9e397510b2 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Scale-Look.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Left.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Left.png new file mode 100644 index 0000000000..1ded1026fe Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Left.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Neutral.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Neutral.png new file mode 100644 index 0000000000..f22ed5c121 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Neutral.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Right.png b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Right.png new file mode 100644 index 0000000000..68b4ac92af Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/Processors-Ship-Right.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Layouts.md b/Packages/com.unity.inputsystem/Documentation~/Layouts.md index a01f3523b1..2a239a6605 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Layouts.md +++ b/Packages/com.unity.inputsystem/Documentation~/Layouts.md @@ -282,7 +282,7 @@ The following table details the properties that a Control item can have. These c |[`sizeInBits`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_sizeInBits)|The total size of the Control's state, in bits.| |[`arraySize`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_arraySize)|If this is set to a non-zero value, the system will create an array of Controls of this size.| |[`parameters`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_parameters)|Any parameters to be passed to the Control. The system will apply these to any fields the Control type might have, such as [`AxisControl.scaleFactor`](../api/UnityEngine.InputSystem.Controls.AxisControl.html#UnityEngine_InputSystem_Controls_AxisControl_scaleFactor).| -|[`processors`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_processors)|[Processors](Processors.md) to apply to the Control.| +|[`processors`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_processors)|[Processors](UsingProcessors.md) to apply to the Control.| |[`noisy`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_noisy)|Whether the Control is to be considered [noisy](Controls.md#noisy-controls).| |[`synthetic`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_synthetic)|Whether the Control is to be considered [synthetic](Controls.md#synthetic-controls).| |[`defaultState`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_defaultState)|Default initial value of the state __memory__ Control.| @@ -369,7 +369,7 @@ A precompiled layout will automatically be unregistered in the following cases: * A [layout override](#layout-overrides) is applied to one of the layouts used by the precompiled Device. This also extends to [controls](Controls.md) used by the Device. * A layout with the same name as one of the layouts used by the precompiled Device is registered (which replaces the layout already registered under the name). -* A [processor](Processors.md) is registered that replaces a processor used by the precompiled Device. +* A [processor](UsingProcessors.md) is registered that replaces a processor used by the precompiled Device. This causes the Input System to fall back to the non-precompiled version of the layout. Note also that a precompiled layout will not be used for layouts [derived](#layout-inheritance) from the layout the precompiled version is based on. In the example above, if someone derives a new layout from `MyDevice`, the precompiled version is unaffected (it will not be unregistered) but is also not used for the newly created type of device. diff --git a/Packages/com.unity.inputsystem/Documentation~/Migration.md b/Packages/com.unity.inputsystem/Documentation~/Migration.md index 8f313acd08..7eddc553c1 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Migration.md +++ b/Packages/com.unity.inputsystem/Documentation~/Migration.md @@ -72,7 +72,7 @@ Then, to read the action values, use the following: [`Input.GetButton`](https://docs.unity3d.com/ScriptReference/Input.GetButton.html)
Example:
`bool jumpValue = Input.GetButton("Jump");`

|Use [`IsPressed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_IsPressed_) on the reference to the action to read the button value.
Example:
`bool jumpValue = jumpAction.IsPressed();`.

[`Input.GetButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetButtonDown.html)
Example: `bool jump = Input.GetButtonDown("Jump");`

|Use [`WasPressedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame_) on the reference to the action to read if the button was pressed this frame.
Example: `bool jumpValue = jumpAction.WasPressedThisFrame();`.

[`Input.GetButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetButtonUp.html)
Example: `bool jump = Input.GetButtonUp("Jump");`

|Use [`WasReleasedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame_) on the reference to the action to read whether the button was released this frame.
Example: `bool jumpValue = jumpAction.WasReleasedThisFrame();`.

-[`Input.GetAxisRaw`](https://docs.unity3d.com/ScriptReference/Input.GetAxisRaw.html)
For example, to read the raw values of the horizontal and vertical axes:
`float h = Input.GetAxisRaw("Horizontal");`
`float v = Input.GetAxisRaw("Vertical");`

|No direct equivalent, but if there are [processors](Processors.md) associated with the action, you can use [`InputControl<>.ReadUnprocessedValue()`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValue) to read unprocessed values.
Example: `Vector2 moveVector = moveAction.ReadUnprocessedValue();`
Note: This returns the same value as ReadValue when there are no processors on the action. +[`Input.GetAxisRaw`](https://docs.unity3d.com/ScriptReference/Input.GetAxisRaw.html)
For example, to read the raw values of the horizontal and vertical axes:
`float h = Input.GetAxisRaw("Horizontal");`
`float v = Input.GetAxisRaw("Vertical");`

|No direct equivalent, but if there are [processors](UsingProcessors.md) associated with the action, you can use [`InputControl<>.ReadUnprocessedValue()`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValue) to read unprocessed values.
Example: `Vector2 moveVector = moveAction.ReadUnprocessedValue();`
Note: This returns the same value as ReadValue when there are no processors on the action. diff --git a/Packages/com.unity.inputsystem/Documentation~/Processors.md b/Packages/com.unity.inputsystem/Documentation~/ProcessorTypes.md similarity index 56% rename from Packages/com.unity.inputsystem/Documentation~/Processors.md rename to Packages/com.unity.inputsystem/Documentation~/ProcessorTypes.md index 05d1740ed3..ce37d3d74a 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Processors.md +++ b/Packages/com.unity.inputsystem/Documentation~/ProcessorTypes.md @@ -1,16 +1,10 @@ --- uid: input-system-processors --- -# Processors +# Processor Types -An Input Processor takes a value and returns a processed result for it. The received value and result value must be of the same type. For example, you can use a [clamp](#clamp) Processor to clamp values from a control to a certain range. +Below you will find predefined processors, furthermore it's possible to create custom Processors. For more information on when to use which type of processor please refer to [Using Processors](UsingProcessors.md). ->__Note__: To convert received input values into different types, see [composite Bindings](ActionBindings.md#composite-bindings). - -* [Using Processors](#using-processors) - * [Processors on Bindings](#processors-on-bindings) - * [Processors on Actions](#processors-on-actions) - * [Processors on Controls](#processors-on-controls) * [Predefined Processors](#predefined-processors) * [Clamp](#clamp) * [Invert](#invert) @@ -26,97 +20,6 @@ An Input Processor takes a value and returns a processed result for it. The rece * [Stick deadzone](#stick-deadzone) * [Writing custom Processors](#writing-custom-processors) -## Using Processors - -You can install Processors on [bindings](ActionBindings.md), [actions](Actions.md) or on [controls](Controls.md). - -Each Processor is [registered](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterProcessor__1_System_String_) using a unique name. To replace an existing Processor, register your own Processor under an existing name. - -Processors can have parameters which can be booleans, integers, or floating-point numbers. When created in data such as [bindings](./ActionBindings.md), processors are described as strings that look like function calls: - -```CSharp - // This references the processor registered as "scale" and sets its "factor" - // parameter (a floating-point value) to a value of 2.5. - - "scale(factor=2.5)" - - // Multiple processors can be chained together. They are processed - // from left to right. - // - // Example: First invert the value, then normalize [0..10] values to [0..1]. - - "invert,normalize(min=0,max=10)" -``` - -### Processors on Bindings - -When you create Bindings for your [actions](Actions.md), you can choose to add Processors to the Bindings. These process the values from the controls they bind to, before the system applies them to the Action value. For instance, you might want to invert the `Vector2` values from the controls along the Y axis before passing these values to the Action that drives the input logic for your application. To do this, you can add an [Invert Vector2](#invert-vector-2) Processor to your Binding. - -If you're using Actions defined in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md), you can add any Processor to your Bindings in the Input Action editor. Select the Binding you want to add Processors to so that the right pane of the window displays the properties for that Binding. Select the Add (+) icon on the __Processors__ foldout to open a list of all available Processors that match your control type, then choose a Processor type to add a Processor instance of that type. The Processor now appears under the __Processors__ foldout. If the Processor has any parameters, you can edit them in the __Processors__ foldout. - -![Binding Processors](Images/BindingProcessors.png) - -To remove a Processor, click the Remove (-) icon next to it. You can also use the up and down arrows to change the order of Processors. This affects the order in which the system processes values. - -If you create your Bindings in code, you can add Processors like this: - -```CSharp -var action = new InputAction(); -action.AddBinding("/leftStick") - .WithProcessor("invertVector2(invertX=false)"); -``` - -### Processors on Actions - -Processors on Actions work in the same way as Processors on Bindings, but they affect all controls bound to an Action, rather than just the controls from a specific Binding. If there are Processors on both the Binding and the Action, the system processes the ones from the Binding first. - -You can add and edit Processors on Actions in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md) the [same way](#processors-on-bindings) as you would for Bindings: select an Action to edit, then add one or more Processors in the right window pane. - -If you create your Actions in code, you can add Processors like this: - -```CSharp -var action = new InputAction(processors: "invertVector2(invertX=false)"); -``` - -### Processors on Controls - -You can have any number of Processors directly on an [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html), which then process the values read from the Control. Whenever you call [`ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) on a Control, all Processors on that Control process the value before it gets returned to you. You can use [`ReadUnprocessedValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValue) on a Control to bypass the Processors. - -The Input System adds Processors to a Control during device creation, if they're specified in the Control's [layout](Layouts.md). You can't add Processors to existing Controls after they've been created, so you can only add Processors to Controls when you're [creating custom devices](Devices.md#creating-custom-devices). The devices that the Input System supports out of the box already have some useful Processors added on their Controls. For instance, sticks on gamepads have a [Stick Deadzone](#stick-deadzone) Processor. - -If you're using a layout generated by the Input System from a [state struct](Devices.md#step-1-the-state-struct) using [`InputControlAttributes`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html), you can specify the Processors you want to use via the [`processors`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_processors) property of the attribute, like this: - -```CSharp -public struct MyDeviceState : IInputStateTypeInfo -{ - public FourCC format => return new FourCC('M', 'Y', 'D', 'V'); - - // Add an axis deadzone to the Control to ignore values - // smaller then 0.2, as our Control does not have a stable - // resting position. - [InputControl(layout = "Axis", processors = "AxisDeadzone(min=0.2)")] - public short axis; -} -``` - -If you [create a layout from JSON](Layouts.md#layout-from-json), you can specify Processors on your Controls like this: - -```CSharp -{ - "name" : "MyDevice", - "extend" : "Gamepad", // Or some other thing - "controls" : [ - { - "name" : "axis", - "layout" : "Axis", - "offset" : 4, - "format" : "FLT", - "processors" : "AxisDeadzone(min=0.2)" - } - ] -} -``` - ## Predefined Processors The Input System package comes with a set of useful Processors you can use. diff --git a/Packages/com.unity.inputsystem/Documentation~/Settings.md b/Packages/com.unity.inputsystem/Documentation~/Settings.md index e7a129913c..15cc0f08e6 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Settings.md +++ b/Packages/com.unity.inputsystem/Documentation~/Settings.md @@ -96,8 +96,8 @@ This setting affects the following sensors: |Property|Description| |----|-----------| -|Default Deadzone Min|The default minimum value for [Stick Deadzone](Processors.md#stick-deadzone) or [Axis Deadzone](Processors.md#axis-deadzone) processors when no `min` value is explicitly set on the processor.| -|Default Deadzone Max|The default maximum value for [Stick Deadzone](Processors.md#stick-deadzone) or [Axis Deadzone](Processors.md#axis-deadzone) processors when no `max` value is explicitly set on the processor.| +|Default Deadzone Min|The default minimum value for [Stick Deadzone](ProcessorTypes.md#stick-deadzone) or [Axis Deadzone](ProcessorTypes.md#axis-deadzone) processors when no `min` value is explicitly set on the processor.| +|Default Deadzone Max|The default maximum value for [Stick Deadzone](ProcessorTypes.md#stick-deadzone) or [Axis Deadzone](ProcessorTypes.md#axis-deadzone) processors when no `max` value is explicitly set on the processor.| |Default Button Press Point|The default [press point](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_pressPointOrDefault) for [Button Controls](../api/UnityEngine.InputSystem.Controls.ButtonControl.html), and for various [Interactions](Interactions.md). For button Controls which have analog physics inputs (such as triggers on a gamepad), this configures how far they need to be held down for the system to consider them pressed.| |Default Tap Time|Default duration for [Tap](Interactions.md#tap) and [MultiTap](Interactions.md#multitap) Interactions. Also used by by touchscreen Devices to distinguish taps from to new touches.| |Default Slow Tap Time|Default duration for [SlowTap](Interactions.md#tap) Interactions.| diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index 360f1e60e3..13609af73e 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -17,7 +17,10 @@ * [Interactions](Interactions.md) * [Devices](Devices.md) * [Controls](Controls.md) - * [Processors](Processors.md) + * [Processors]() + * [Processors and their use](UsingProcessors.md) + * [How to apply Processors](HowToApplyProcessors.md) + * [Processor Types](ProcessorTypes.md) * [Player Input Component](PlayerInput.md) * [Player Input Manager Component](PlayerInputManager.md) * [Input settings](Settings.md) diff --git a/Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md b/Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md new file mode 100644 index 0000000000..843dc2191d --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md @@ -0,0 +1,152 @@ +--- +uid: input-system-processors +--- +# Processors + +An Input Processor takes a value and returns a processed result for it. The received value and result value must be of the same type. For example, you can use a [clamp](#clamp) Processor to clamp values from a control to a certain range. + +>__Note__: To convert received input values into different types, see [composite Bindings](ActionBindings.md#composite-bindings). + +* [Using Processors](#using-processors) +* [When to use which Processor](#when-to-use-which-processor) + * [Invert](#invert) + * [Normalize](#normalize) + * [Scale](#scale) + * [Deadzone](#deadzone) + * [Clamp](#clamp) + +## Using Processors + +You can install Processors on [bindings](ActionBindings.md), [actions](Actions.md) or on [controls](Controls.md). See [How to apply Processors](HowToApplyProcessors.md) to learn more. + +Each Processor is [registered](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterProcessor__1_System_String_) using a unique name. To replace an existing Processor, register your own Processor under an existing name. + +Processors can have parameters which can be booleans, integers, or floating-point numbers. When created in data such as [bindings](./ActionBindings.md), processors are described as strings that look like function calls: + +```CSharp + // This references the processor registered as "scale" and sets its "factor" + // parameter (a floating-point value) to a value of 2.5. + + "scale(factor=2.5)" + + // Multiple processors can be chained together. They are processed + // from left to right. + // + // Example: First invert the value, then normalize [0..10] values to [0..1]. + + "invert,normalize(min=0,max=10)" +``` + +## When to use which Processor + +The following sections contain a brief explanation and various example scenarios for the different Processor types. Note that there are additional cases where Processors may apply; the scenarios described here illustrate only some of them. In some situations, it might be useful to combine multiple Processors to achieve a specific goal. +If you don’t find a scenario similar to your use case, please refer to the [Processor Types](ProcessorTypes.md) section. You can also find more information on how to write your own custom Processors there. + +### Invert + +The [Invert Processor](ProcessorTypes.md#invert) inverts input values of any type (e.g. float, Vector2, or Vector3) by multiplying them by -1. This results in effects such as reversing player navigation, for example, the left arrow would be interpreted as a right arrow, and vice versa. + +#### Ship navigation scenario + +To use an axis control to mimic a ship's rudder, inverting the input will produce the desired effect. Pulling the stick to the left will steer the ship to the right, while pulling it to the right will steer the ship to the left. + +![image alt text](./Images/Processors-Ship-Neutral.png) +![image alt text](./Images/Processors-Ship-Left.png) +![image alt text](./Images/Processors-Ship-Right.png) + +This can be achieved by using an Invert Processor on the Action or the Binding. In this scenario, the Processor is applied to the Binding. Note that inversion is enabled for the X axis but not for the Y axis. Inverting the Y axis would cause the ship to move backward when the joystick is pulled upward. The following image shows the setup in the Action Asset Editor. + +![image alt text](./Images/Processors-Invert-Editor.png) + +Finally, the following code can be used in a script attached to a GameObject that has a PlayerInput component referencing the corresponding Action Asset. + +```c# +using UnityEngine; +using UnityEngine.InputSystem; + +public class Boat : MonoBehaviour +{ + void OnMove(InputValue value) + { + // The X value will be used to rotate the boat + var stick = value.Get(); + var direction = stick.x; + transform.Rotate(Vector3.up, direction); + // To move the boat forwards, this code block uses the Y value of the stick + var speed = stick.y; + transform.Translate(new Vector3(0,0,speed),Space.Self); + } +} +``` + +### Normalize + +The [Normalize Processors](ProcessorTypes.md#normalize) normalizes the magnitude of the input vector so that it always has a length of 1. This extracts the direction of the input while removing additional information that may not be needed. +In the case of float input values, the values are normalized between a defined minimum, zero, and maximum. +Normalized input is particularly useful in scenarios where the specific magnitude of an input might distort the consistency of an intended action. + +#### A steady running player + +To ensure the player always moves at a constant speed where the input simply triggers the action and controls the direction, the Normalize Processor is a suitable choice. This is achieved by retrieving the input vector while ignoring its magnitude and focusing solely on its direction. + +![image alt text](./Images/Processors-Normalize-Slow.png) +![image alt text](./Images/Processors-Normalize-Fast.png) + +In the images shown above, the player moves forward at a constant speed, regardless of how far the joystick is pushed upward. + +To apply the Processor, it can be added to the Binding, as shown in the image below. + +![This should be a picture of the Asset editor](./Images/Processors-NormalizeAsset.png) + +Note: This scenario uses the [Starter Assets](https://assetstore.unity.com/packages/essentials/starter-assets-thirdperson-updates-in-new-charactercontroller-pa-196526?srsltid=AfmBOoqLWdW2pU5Wt2reGYdWVodc1e0ko3cBKtfMQuPSgVqmL7yVA3dB), and the included PlayerScript is utilized to move the player. + +### Scale + +The [Scale Processor](ProcessorTypes.md#scale) multiplies the input value by a given factor X. This applies to float values as well as vectors, where each axis is multiplied by the corresponding factor specified for that axis. +This allows you to assign weight to input values, which can, for example, make a particular type of control easier to use. + +#### Horizontally aligned Camera + +To make the look-around movement smoother and improve ease of use, it may be helpful to reduce the vertical rotation and scale the input values for horizontal rotation. For in-game landscapes that are primarily horizontally aligned, this is a useful feature to prevent the camera from rotating vertically too quickly or in unintended ways. +To apply this effect to all bindings, the Processor is applied to the Action itself (Look in this scenario). The following image shows the setup using the Starter Assets example: + +![Here should be a picture of the Input Action Editor](./Images/Processors-Scale-Look.png) + +There are two Bindings attached to the Action. The input value ranges of the two bindings are very different. To mitigate this difference, it helps to use a Scale Processor on each of the Bindings. See how the Scale Processor normalizes the input data values for a joystick and a pointer (e.g., a mouse) in the images below. + +![Here should be a picture of the Input Action Editor](./Images/Processors-Scale-Look-Pointer.png) +![Here should be a picture of the Input Action Editor](./Images/Processors-Scale-Look-Stick.png) + +Note: This scenario uses the [Starter Assets](https://assetstore.unity.com/packages/essentials/starter-assets-thirdperson-updates-in-new-charactercontroller-pa-196526?srsltid=AfmBOoqLWdW2pU5Wt2reGYdWVodc1e0ko3cBKtfMQuPSgVqmL7yVA3dB), and the included PlayerScript is utilized to rotate the camera. + +#### Customizing mouse input + +Another example of when Scale Processors can be very useful is customizing input via a game settings window. To allow a custom setup for the speed of the mouse in the X and Y directions, a Scale Processor can be applied to a Binding that is limited to a Pointer device. + +### Deadzone + +To filter noise from controls that are rarely in a default state, constantly send input values, or seldom report the maximum value, a [Deadzone Processor](ProcessorTypes.md#axis-deadzone) might be the right choice. +The specified minimum value can filter out small movements or noise from the control, while the maximum value can mitigate the difference between the control's maximum value and the reported maximum values. + +#### The Deadzone Processor for Accesibility + +The Deadzone Processor can be used to improve accessibility for physically challenging input gestures, such as very small movements on an input device. This can be made configurable through a game menu, for example. To filter out input events from tiny movements on a joystick (e.g., for trembling hands), here’s how the right stick binding of a gamepad can be modified to ignore input events for small input values: + +![Here should be a picture of the Input Action Editor](./Images/Processors-Deadzone-Editor.png) + +The default minimum value is overridden to allow a higher threshold for minimum input values. For the maximum value, the default is used to standardize the values across all gamepads (since not all gamepads may ever send the maximum value). + +Note: This scenario uses the [Starter Assets](https://assetstore.unity.com/packages/essentials/starter-assets-thirdperson-updates-in-new-charactercontroller-pa-196526?srsltid=AfmBOoqLWdW2pU5Wt2reGYdWVodc1e0ko3cBKtfMQuPSgVqmL7yVA3dB), and the included PlayerScript is utilized to rotate the camera. + +### Clamp + +The [Clamp Processor](ProcessorTypes.md#clamp) clamps the input value to a specified range. The minimum value of the Processor defines the lowest input value that will be accepted, while the value cannot exceed the given maximum value. In combination with the Scale Processor, it is easy to standardize the input value ranges of different devices and place them within a well-defined value spectrum. + +#### Racing car + +In a case where the player is not supposed to fall below a certain base speed, but also cannot exceed a certain maximum speed, the Clamp Processor is the one you may want to use. +In the following image, you can see how a Clamp Processor can be used to restrict input values within a defined minimum and maximum range. + +![Here should be a picture of the Input Action Editor](./Images/Processors-Clamp-Editor.png) + +Note that the Bindings can contain input values with very different ranges. In that case, a Scale Processor on the Bindings can help preprocess the values before clamping them (Processors on Actions are applied after Processors on Bindings).