diff --git a/Packages/com.unity.inputsystem/Documentation~/Processors.md b/Packages/com.unity.inputsystem/Documentation~/Processors.md index ee5506e07b..98fac029f7 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Processors.md +++ b/Packages/com.unity.inputsystem/Documentation~/Processors.md @@ -3,28 +3,12 @@ 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) - * [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) - * [Invert Vector 2](#invert-vector-2) - * [Invert Vector 3](#invert-vector-3) - * [Normalize](#normalize) - * [Normalize Vector 2](#normalize-vector-2) - * [Normalize Vector 3](#normalize-vector-3) - * [Scale](#scale) - * [Scale Vector 2](#scale-vector-2) - * [Scale Vector 3](#scale-vector-3) - * [Axis deadzone](#axis-deadzone) - * [Stick deadzone](#stick-deadzone) -* [Writing custom Processors](#writing-custom-processors) - - - +Use an input processor to apply processing to input values and return the result. For example, you can use a [clamp](built-in-processors.md#clamp) processor to clamp values to within a certain range. + +|Topic|Description| +|-|-| +|[Introduction to processors](introduction-to-processors.md) |Learn what processors can do to alter input values, and how they interact with bindings, actions, and controls. | +|[Built-in processors](built-in-processors.md) | Explore the processors that come built into the Input System. | +|[Write custom processors](write-custom-processors.md) | Create and register your own processors for use with bindings, actions, and controls. | +|[Add processors to bindings and actions](add-processors-bindings-actions.md) |Add processors to individual bindings, or to all bindings on an action, via the Editor or via code. | +|[Add processors to controls](add-processors-controls.md) | Add processors to specific control inputs, including custom controls. | \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index 813b79ee27..665b44ee4c 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -58,7 +58,11 @@ * [Controls schemes](control-schemes.md) * [Interactions](interactions.md) * [Processors](processors.md) - * [Configure sctions](configure-actions.md) + * [Introduction to processors](introduction-to-processors.md) + * [Built-in processors](built-in-processors.md) + * [Write custom processors](write-custom-processors.md) + * [Add processors to bindings and actions](add-processors-bindings-actions.md) + * [Add processors to controls](add-processors-controls.md) * [Input Actions Editor reference](actions-editor.md) * [Input Actions Editor window reference](input-actions-editor-window-reference.md) * [Action Properties panel reference](action-properties-panel-reference.md) @@ -84,7 +88,6 @@ * [Write custom interactions](write-custom-interactions.md) * [Devices](Devices.md) * [Controls](controls.md) - * [Processors](Processors.md) * [Player Input Component](player-input-component.md) * [Player Input Manager Component](PlayerInputManager.md) * [Input settings](Settings.md) diff --git a/Packages/com.unity.inputsystem/Documentation~/add-processors-bindings-actions.md b/Packages/com.unity.inputsystem/Documentation~/add-processors-bindings-actions.md new file mode 100644 index 0000000000..71cd3cdc6c --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/add-processors-bindings-actions.md @@ -0,0 +1,31 @@ +# Add processors to bindings and actions + +To add a processor to an [action](actions.md) or [binding](ActionBindings.md) via the Input Actions Editor: + +1. Select the action or binding you want to add processors to. The Properties panel opens in the right pane of the window. +1. In the Properties panel, navigate to the **Processors** foldout. Select the **Add (+)** icon on the header to open a list of all available processors that match your control type. +1. From the drop-down list, select a processor type. A processor of that type appears in the __Processors__ foldout. +1. In the __Processors__ foldout, edit any parameters of the processor. + +
![An example of the Processors foldout in the Properties panel, displaying processors called Stick Deadzone and Scale Vactor 2](Images/BindingProcessors.png) + +To remove a processor, select 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. + +To add a processor to an action or binding via code, use the following code examples as templates: + +**Actions:** + +```CSharp +var action = new InputAction(processors: "invertVector2(invertX=false)"); +``` + +**Bindings:** + +```CSharp +var action = new InputAction(); +action.AddBinding("/leftStick") + .WithProcessor("invertVector2(invertX=false)"); +``` + +>[!NOTE] +>The received value and result value must be of the same type. To convert received input values into different types, see [composite Bindings](ActionBindings.md#composite-bindings). \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/add-processors-controls.md b/Packages/com.unity.inputsystem/Documentation~/add-processors-controls.md new file mode 100644 index 0000000000..a4275c85de --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/add-processors-controls.md @@ -0,0 +1,38 @@ +# Add processors to controls + +The Input System automatically 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. You can only add processors to Controls when you're [creating custom devices](Devices.md#creating-custom-devices). + +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: + +```json +{ + "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~/built-in-processors.md b/Packages/com.unity.inputsystem/Documentation~/built-in-processors.md new file mode 100644 index 0000000000..a4b956de17 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/built-in-processors.md @@ -0,0 +1,20 @@ +# Built-in Processors + +The Input System package comes with a set of built-in Processors, which you can use with [bindings](ActionBindings.md), [actions](actions.md) and [controls](controls.md). + + +|**Processor name**|**Description**|**Operand type**|**Parameters**| +|---|---|---|---| +|[`Clamp`](../api/UnityEngine.InputSystem.Processors.ClampProcessor.html)|Clamps input values to the [`min`..`max`] range.|`float`|| +|[`Invert`](../api/UnityEngine.InputSystem.Processors.InvertProcessor.html)|Inverts the values from a Control (that is, multiplies the values by −1).|`float`|None| +|[`InvertVector2`](../api/UnityEngine.InputSystem.Processors.InvertVector2Processor.html)|Inverts the values from a Control (that is, multiplies the values by −1). Inverts the x-axis of the vector if `invertX` is true, and the y-axis if `invertY` is true.|`Vector2`|| +|[`Invert Vector 3`](../api/UnityEngine.InputSystem.Processors.InvertVector3Processor.html)|Inverts the values from a Control (that is, multiplies the values by −1). Inverts the x-axis of the vector if `invertX` is true, the y-axis if `invertY` is true, and the z-axis if `invertZ` is true.|`Vector3`|| +|[`Normalize`](../api/UnityEngine.InputSystem.Processors.NormalizeProcessor.html)|Normalizes input values in the range [`min`..`max`] to unsigned normalized form [0..1] if `min` is >= `zero`, and to signed normalized form [-1..1] if `min` < `zero`.|`float`|| +|[`NormalizeVector2`](../api/UnityEngine.InputSystem.Processors.NormalizeVector2Processor.html)|Normalizes input vectors to be of unit length (1). This is the same as calling `Vector2.normalized`.|`Vector2`|None| +|[`NormalizeVector3`](../api/UnityEngine.InputSystem.Processors.NormalizeVector3Processor.html)|Normalizes input vectors to be of unit length (1). This is the same as calling `Vector3.normalized`.|`Vector3`|None| +|[`Scale`](../api/UnityEngine.InputSystem.Processors.ScaleProcessor.html)|Multiplies all input values by `factor`.|`float`|`float factor`| +|[`ScaleVector2`](../api/UnityEngine.InputSystem.Processors.ScaleVector2Processor.html)|Multiplies all input values by `x` along the x-axis and by `y` along the y-axis.|`Vector2`|| +|[`ScaleVector3`](../api/UnityEngine.InputSystem.Processors.ScaleVector3Processor.html)|Multiplies all input values by `x` along the x-axis, by `y` along the y-axis, and by `z` along the z-axis.|`Vector3`|| +|[`AxisDeadzone`](../api/UnityEngine.InputSystem.Processors.AxisDeadzoneProcessor.html)|Scales the values of a Control so that any value with an absolute value smaller than `min` is 0, and any value with an absolute value larger than `max` is 1 or −1.

Many Controls don't have a precise resting point (that is, they don't always report exactly 0 when the Control is in the center). Using the `min` value on a deadzone Processor avoids unintentional input from such Controls. Also, some Controls don't consistently report their maximum values when moving the axis all the way. Using the `max` value on a deadzone Processor ensures that you always get the maximum value in such cases.|`float`|| +|[`StickDeadzone`](../api/UnityEngine.InputSystem.Processors.StickDeadzoneProcessor.html)|Scales the values of a Vector2 Control, such as a stick, so that any input vector with a magnitude smaller than `min` results in (0,0), and any input vector with a magnitude greater than `max` is normalized to length 1.

Many Controls don't have a precise resting point (that is, they don't always report exactly 0,0 when the Control is in the center). Using the `min` value on a deadzone Processor avoids unintentional input from such Controls. Also, some Controls don't consistently report their maximum values when moving the axis all the way. Using the `max` value on a deadzone Processor ensures that you always get the maximum value in such cases.|`Vector2`| + diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-to-processors.md b/Packages/com.unity.inputsystem/Documentation~/introduction-to-processors.md new file mode 100644 index 0000000000..0ef98dbc9e --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-to-processors.md @@ -0,0 +1,37 @@ +# Introduction to processors + +Input processors apply processing to input values, and return the result. The Input System’s [built-in processors](built-in-processors.md) can apply value clamping, scaling, normalization, inversion, and deadzones. You can also create [custom processors](write-custom-processors.md) to apply additional data processing to input values. + +You can install processors on [bindings](ActionBindings.md), [actions](actions.md) or [controls](controls.md). The Input System [registers](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterProcessor__1_System_String_) each processor with a unique name. This means that if you need to replace an existing processor, you need to register the new processor under the name of the existing processor. + +Processors can have boolean, integer, and floating-point number parameters. When created in data such as [bindings](./ActionBindings.md), processors are described as strings that look like function calls. + +For example, the following string references the processor registered as "scale" and sets its "factor" parameter to a floating-point value of 2.5: + +```CSharp + "scale(factor=2.5)" +``` + +Multiple processors can be chained together. The Input System processes them in the order they appear in code. For example, the following string inverts a value, then normalizes [0..10] values to [0..1]: + +```CSharp + "invert,normalize(min=0,max=10)" +``` + +## Processors on bindings and actions + +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 example, you could invert the `Vector2` values from the controls along the Y axis before passing the values to the associated action. + +Processors on actions work the same way, but affect all bindings on an action. + +If there are processors on both the binding and the action, the Input System processes the processors from the binding first. + +To apply a processor to a binding or action, refer to [Add processors to bindings and actions](add-processors-bindings-actions.md). + +## 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 devices that the Input System supports out of the box already have some useful processors added to their controls by default. For example, sticks on gamepads have a [Stick Deadzone](built-in-processors.md#stick-deadzone) processor. + +To apply a processor to a control, refer to [Add processors to controls](add-processors-controls.md) diff --git a/Packages/com.unity.inputsystem/Documentation~/predefined-processors.md b/Packages/com.unity.inputsystem/Documentation~/predefined-processors.md deleted file mode 100644 index f748abd684..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/predefined-processors.md +++ /dev/null @@ -1,108 +0,0 @@ -# Predefined Processors - -The Input System package comes with a set of useful Processors you can use. - -### Clamp - -|__Name__|[`Clamp`](../api/UnityEngine.InputSystem.Processors.ClampProcessor.html)| -|---|---| -|__Operand Type__|`float`| -|__Parameters__|`float min`
`float max`| - -Clamps input values to the [`min`..`max`] range. - -### Invert - -|__Name__|[`Invert`](../api/UnityEngine.InputSystem.Processors.InvertProcessor.html)| -|---|---| -|__Operand Type__|`float`| - -Inverts the values from a Control (that is, multiplies the values by -1). - -### Invert Vector 2 - -|__Name__|[`InvertVector2`](../api/UnityEngine.InputSystem.Processors.InvertVector2Processor.html)| -|---|---| -|__Operand Type__|`Vector2`| -|__Parameters__|`bool invertX`
`bool invertY`| - -Inverts the values from a Control (that is, multiplies the values by -1). Inverts the x axis of the vector if `invertX` is true, and the y axis if `invertY` is true. - -### Invert Vector 3 - -|__Name__|[`Invert Vector 3`](../api/UnityEngine.InputSystem.Processors.InvertVector3Processor.html)| -|---|---| -|__Operand Type__|`Vector3`| -|__Parameters__|`bool invertX`
`bool invertY`
`bool invertZ`| - -Inverts the values from a Control (that is, multiplies the values by -1). Inverts the x axis of the vector if `invertX` is true, the y axis if `invertY` is true, and the z axis if `invertZ` is true. - -### Normalize - -|__Name__|[`Normalize`](../api/UnityEngine.InputSystem.Processors.NormalizeProcessor.html)| -|---|---| -|__Operand Type__|`float`| -|__Parameters__|`float min`
`float max`
`float zero`| - -Normalizes input values in the range [`min`..`max`] to unsigned normalized form [0..1] if `min` is >= `zero`, and to signed normalized form [-1..1] if `min` < `zero`. - -### Normalize Vector 2 - -|__Name__|[`NormalizeVector2`](../api/UnityEngine.InputSystem.Processors.NormalizeVector2Processor.html)| -|---|---| -|__Operand Type__|`Vector2`| - -Normalizes input vectors to be of unit length (1). This is the same as calling `Vector2.normalized`. - -### Normalize Vector 3 - -|__Name__|[`NormalizeVector3`](../api/UnityEngine.InputSystem.Processors.NormalizeVector3Processor.html)| -|---|---| -|__Operand Type__|`Vector3`| - -Normalizes input vectors to be of unit length (1). This is the same as calling `Vector3.normalized`. - -### Scale - -|__Name__|[`Scale`](../api/UnityEngine.InputSystem.Processors.ScaleProcessor.html)| -|---|---| -|__Operand Type__|`float`| -|__Parameters__|`float factor`| - -Multiplies all input values by `factor`. - -### Scale Vector 2 - -|__Name__|[`ScaleVector2`](../api/UnityEngine.InputSystem.Processors.ScaleVector2Processor.html)| -|---|---| -|__Operand Type__|`Vector2`| -|__Parameters__|`float x`
`float y`| - -Multiplies all input values by `x` along the X axis and by `y` along the Y axis. - -### Scale Vector 3 - -|__Name__|[`ScaleVector3`](../api/UnityEngine.InputSystem.Processors.ScaleVector3Processor.html)| -|---|---| -|__Operand Type__|`Vector3`| -|__Parameters__|`float x`
`float y`
`float x`| - -Multiplies all input values by `x` along the X axis, by `y` along the Y axis, and by `z` along the Z axis. - -### Axis deadzone - -|__Name__|[`AxisDeadzone`](../api/UnityEngine.InputSystem.Processors.AxisDeadzoneProcessor.html)| -|---|---| -|__Operand Type__|`float`| -|__Parameters__|`float min`
`float max`| - -An axis deadzone Processor scales the values of a Control so that any value with an absolute value smaller than `min` is 0, and any value with an absolute value larger than `max` is 1 or -1. Many Controls don't have a precise resting point (that is, they don't always report exactly 0 when the Control is in the center). Using the `min` value on a deadzone Processor avoids unintentional input from such Controls. Also, some Controls don't consistently report their maximum values when moving the axis all the way. Using the `max` value on a deadzone Processor ensures that you always get the maximum value in such cases. - -### Stick deadzone - -|__Name__|[`StickDeadzone`](../api/UnityEngine.InputSystem.Processors.StickDeadzoneProcessor.html)| -|---|---| -|__Operand Type__|`Vector2`| -|__Parameters__|`float min`
`float max`| - -A stick deadzone Processor scales the values of a Vector2 Control, such as a stick, so that any input vector with a magnitude smaller than `min` results in (0,0), and any input vector with a magnitude greater than `max` is normalized to length 1. Many Controls don't have a precise resting point (that is, they don't always report exactly 0,0 when the Control is in the center). Using the `min` value on a deadzone Processor avoids unintentional input from such Controls. Also, some Controls don't consistently report their maximum values when moving the axis all the way. Using the `max` value on a deadzone Processor ensures that you always get the maximum value in such cases. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/processors-on-actions.md b/Packages/com.unity.inputsystem/Documentation~/processors-on-actions.md deleted file mode 100644 index 044d001bc9..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/processors-on-actions.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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)"); -``` diff --git a/Packages/com.unity.inputsystem/Documentation~/processors-on-bindings.md b/Packages/com.unity.inputsystem/Documentation~/processors-on-bindings.md deleted file mode 100644 index 798836eea6..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/processors-on-bindings.md +++ /dev/null @@ -1,17 +0,0 @@ -### 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)"); -``` diff --git a/Packages/com.unity.inputsystem/Documentation~/processors-on-controls.md b/Packages/com.unity.inputsystem/Documentation~/processors-on-controls.md deleted file mode 100644 index 9cf10d909c..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/processors-on-controls.md +++ /dev/null @@ -1,39 +0,0 @@ - -### 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)" - } - ] -} -``` diff --git a/Packages/com.unity.inputsystem/Documentation~/using-processors.md b/Packages/com.unity.inputsystem/Documentation~/using-processors.md deleted file mode 100644 index d2c25d8d0a..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/using-processors.md +++ /dev/null @@ -1,21 +0,0 @@ -## 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)" -``` diff --git a/Packages/com.unity.inputsystem/Documentation~/write-custom-processors.md b/Packages/com.unity.inputsystem/Documentation~/write-custom-processors.md index f618d8766d..281cc66a84 100644 --- a/Packages/com.unity.inputsystem/Documentation~/write-custom-processors.md +++ b/Packages/com.unity.inputsystem/Documentation~/write-custom-processors.md @@ -1,8 +1,16 @@ -# Writing custom Processors +# Write custom processors -You can also write custom Processors to use in your Project. Custom Processors are available in the UI and code in the same way as the built-in Processors. Add a class derived from [`InputProcessor`](../api/UnityEngine.InputSystem.InputProcessor-1.html), and implement the [`Process`](../api/UnityEngine.InputSystem.InputProcessor-1.html#UnityEngine_InputSystem_InputProcessor_1_Process__0_UnityEngine_InputSystem_InputControl_) method: +You can write custom processors to use with [bindings](ActionBindings.md), [actions](actions.md) and [controls](controls.md) in your Project. Custom processors are available in the UI and code in the same way as the [built-in processors](built-in-processors.md). ->__IMPORTANT__: Processors must be __stateless__. This means you cannot store local state in a processor that will change depending on the input being processed. The reason for this is because processors are not part of the [input state](./controls.md#control-state) that the Input System keeps. +To create a custom processor: + +1. [Add a processor class and method](#add-a-processor-class-and-method) +1. [Register the new processor to the Input System](#register-the-new-processor-to-the-input-system) +1. [Customize the Editor UI](#customize-the-editor-ui) for the new processor, if necessary. + +## Add a processor class and method + +**1.** Add a class derived from [`InputProcessor`](../api/UnityEngine.InputSystem.InputProcessor-1.html), and implement the [`Process`](../api/UnityEngine.InputSystem.InputProcessor-1.html#UnityEngine_InputSystem_InputProcessor_1_Process__0_UnityEngine_InputSystem_InputControl_) method: ```CSharp public class MyValueShiftProcessor : InputProcessor @@ -17,7 +25,12 @@ public class MyValueShiftProcessor : InputProcessor } ``` -Now, you need to tell the Input System about your Processor. Call [`InputSystem.RegisterProcessor`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterProcessor__1_System_String_) in your initialization code. You can do so locally within the Processor class like this: +>[!IMPORTANT] +>Processors must be __stateless__, because they are not part of the [input state](./Controls.md#control-state) that the Input System keeps. For this reason, you can't store local states in a processor if the processor changes based on the input value. + +## Register the new processor to the Input System + +Register the new processor to the Input System. Call [`InputSystem.RegisterProcessor`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterProcessor__1_System_String_) in your initialization code. You can do this locally within the Processor class: ```CSharp #if UNITY_EDITOR @@ -48,11 +61,13 @@ Your new Processor is now available in the in the [Input Actions Editor](Actions var action = new InputAction(processors: "myvalueshift(valueShift=2.3)"); ``` -If you want to customize the UI for editing your Processor, create a custom [`InputParameterEditor`](../api/UnityEngine.InputSystem.Editor.InputParameterEditor-1.html) class for it: +## Customize the Editor UI + +To customize the UI for editing your Processor, create a custom [`InputParameterEditor`](../api/UnityEngine.InputSystem.Editor.InputParameterEditor-1.html) class for it: ```CSharp // No registration is necessary for an InputParameterEditor. -// The system will automatically find subclasses based on the +// The system automatically finds subclasses based on the // <..> type parameter. #if UNITY_EDITOR public class MyValueShiftProcessorEditor : InputParameterEditor