DOCS: How to use processors #2171

ritamerkl · 2025-04-23T15:02:53Z

Description

This adds more documentation on how to use processors.

Testing status & QA

No testing

Overall Product Risks

Complexity: low
Halo Effect: low

Comments to reviewers

Checklist

Before review:

Changelog entry added.
- Explains the change in Changed, Fixed, Added sections.
- For API change contains an example snippet and/or migration example.
- JIRA ticket linked, example (case %%). If it is a private issue, just add the case ID without a link.
- Jira port for the next release set as "Resolved".
Tests added/changed, if applicable.
- Functional tests Area_CanDoX, Area_CanDoX_EvenIfYIsTheCase, Area_WhenIDoX_AndYHappens_ThisIsTheResult.
- Performance tests.
- Integration tests.
Docs for new/changed API's.
- Xmldoc cross references are set correctly.
- Added explanation how the API works.
- Usage code examples added.
- The manual is updated, if needed.

During merge:

Commit message for squash-merge is prefixed with one of the list:
- NEW: ___.
- FIX: ___.
- DOCS: ___.
- CHANGE: ___.
- RELEASE: 1.1.0-preview.3.

After merge:

Create forward/backward port if needed. If you are blocked from creating a forward port now please add a task to ISX-1444.

…es/InputSystem into docs-processors

lilisha-unity

I did my first pass on the PR. Please fix the note formatting and replace the placeholder image alt text with something more descriptive. Also, there are quite a few sentences written in passive voice—please rewrite them in active voice where appropriate. You can refer to the Unity style guide for reference: https://docs-style-guide.unity.com/style/use-active-voice.

Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md

Packages/com.unity.inputsystem/Documentation~/ProcessorTypes.md

Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md

Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

jfreire-unity · 2025-05-15T07:55:55Z

Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

+
+![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).


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

I think it would be good to have an example or expand an existing one to show examples of order of execution of processors. Always better to have an example than saying it in words IMO.

Do you have a specific example in mind?

…sors.md Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

…sors.md Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

codecov-github-com · 2025-05-27T17:33:31Z

Codecov Report

All modified and coverable lines are covered by tests ✅

@@             Coverage Diff             @@
##           develop    #2171      +/-   ##
===========================================
+ Coverage    67.78%   67.80%   +0.02%     
===========================================
  Files          367      367              
  Lines        53505    53505              
===========================================
+ Hits         36268    36280      +12     
+ Misses       17237    17225      -12

Flag	Coverage Δ
mac_2021.3_pkg	`5.41% <ø> (ø)`
mac_2021.3_project	`70.42% <ø> (ø)`
mac_2022.3_pkg	`5.19% <ø> (ø)`
mac_2022.3_project	`65.29% <ø> (ø)`
mac_6000.0_pkg	`5.20% <ø> (ø)`
mac_6000.0_project	`67.72% <ø> (+0.02%)`	⬆️
mac_6000.1_pkg	`5.20% <ø> (ø)`
mac_6000.1_project	`67.70% <ø> (ø)`
mac_6000.2_pkg	`5.20% <ø> (ø)`
mac_6000.2_project	`67.71% <ø> (+0.01%)`	⬆️
mac_trunk_pkg	`5.20% <ø> (ø)`
mac_trunk_project	`67.70% <ø> (ø)`
win_2021.3_pkg	`5.42% <ø> (ø)`
win_2021.3_project	`70.49% <ø> (ø)`
win_2022.3_pkg	`5.20% <ø> (ø)`
win_2022.3_project	`65.36% <ø> (ø)`
win_6000.0_pkg	`5.20% <ø> (ø)`
win_6000.0_project	`67.68% <ø> (-0.11%)`	⬇️
win_6000.1_pkg	`5.20% <ø> (ø)`
win_6000.1_project	`67.78% <ø> (ø)`
win_6000.2_pkg	`5.20% <ø> (ø)`
win_6000.2_project	`67.78% <ø> (-0.01%)`	⬇️
win_trunk_pkg	`5.20% <ø> (ø)`
win_trunk_project	`67.78% <ø> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 3 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

lilisha-unity

Finished my review with some suggestions.

Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

…es/InputSystem into docs-processors

ekcoh

Looks good to me, added some minor comments

ekcoh · 2025-06-11T13:56:12Z

Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md

+
+## 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.


Minor: Y-axis?

ekcoh · 2025-06-11T13:56:59Z

Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md

+
+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:
+
+1. Select the Binding you want to add Processors to so that the right pane of the window displays the properties for that Binding.


Minor: "right pane" or "right panel"? Maybe call it by its UI title instead?

ekcoh · 2025-06-11T14:05:49Z

Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

+
+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.
+
+#### Example: Racing game speend control


Typo: "speed"

ekcoh · 2025-06-11T14:07:11Z

Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

+
+#### Example: Racing game speend control
+
+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.


Generally, IMO this to be game-logic and not input logic, but its fine as-is to show as example.

ekcoh · 2025-06-11T14:09:37Z

Looks like there is some CI issues that needs attention

ritamerkl added 2 commits April 17, 2025 16:42

restructure processors documentation

55f2803

added scenarios for each processor

8472341

ritamerkl marked this pull request as draft April 23, 2025 15:05

ritamerkl added 6 commits April 25, 2025 17:32

uniforming scenarios & explanation and adding more details

1bfff7b

added pictures and code

db25dc2

refined scenarios and added pictures

5e9ee17

added example for clamp processor with picture

d37dcd5

replaced image for clamp processor

c824127

corrected grammar and spelling

32317b2

ritamerkl marked this pull request as ready for review April 29, 2025 13:32

Merge branch 'develop' into docs-processors

c365673

ritamerkl requested a review from jfreire-unity April 29, 2025 13:32

ritamerkl added 5 commits April 29, 2025 15:46

fixed formatting

1218ba0

Merge branch 'docs-processors' of https://github.com/Unity-Technologi…

bbea9d6

…es/InputSystem into docs-processors

updated file references to processors

3bc0a6e

fixed docs link

58a726e

Fixed Doc link

bc03750

LeoUnity requested a review from JonMUnity May 1, 2025 12:26

lilisha-unity requested changes May 9, 2025

View reviewed changes

jfreire-unity reviewed May 15, 2025

View reviewed changes

ritamerkl and others added 10 commits May 27, 2025 15:39

Update Packages/com.unity.inputsystem/Documentation~/HowToApplyProces…

0c8f1db

…sors.md Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/ProcessorTypes.md

518e2dc

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/ProcessorTypes.md

cda1e1d

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/HowToApplyProces…

bda4aba

…sors.md Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/HowToApplyProces…

80d8410

…sors.md Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

31b1c1e

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

4b22e08

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

45e2105

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

c1b6852

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

9dab870

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

ritamerkl and others added 14 commits May 27, 2025 15:41

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

f25ebc5

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

d2e51b1

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

06a2074

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

185ddae

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/ActionBindings.md

67be9c1

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

f50c2e6

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

deee7ff

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

bfa2d22

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

Update Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md

75fb0e0

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

remove TOC for autogenerated TOC

72361ec

fixed alt text for normalize example

8f5bf2c

fixed clamp picture alt text

834e2c4

reworked alt text for images

8988c27

Merge branch 'develop' into docs-processors

9393fbc

lilisha-unity approved these changes May 28, 2025

View reviewed changes

ritamerkl and others added 7 commits May 28, 2025 18:13

added formatting to Notes

801884f

Apply suggestions from code review

542f977

Co-authored-by: lilisha-unity <94024889+lilisha-unity@users.noreply.github.com>

fixed note comment

58d212b

Merge branch 'docs-processors' of https://github.com/Unity-Technologi…

c90e7fb

…es/InputSystem into docs-processors

change to active language

cf18c91

fix formatting

3e09334

Merge branch 'develop' into docs-processors

9a47d3b

ekcoh approved these changes Jun 11, 2025

View reviewed changes


		![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).


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

		1. Select the Binding you want to add Processors to so that the right pane of the window displays the properties for that Binding.


		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.

		#### Example: Racing game speend control


		#### Example: Racing game speend control

		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.

DOCS: How to use processors #2171

Are you sure you want to change the base?

DOCS: How to use processors #2171

Uh oh!

Conversation

ritamerkl commented Apr 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing status & QA

Overall Product Risks

Comments to reviewers

Checklist

Uh oh!

lilisha-unity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jfreire-unity May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ritamerkl May 28, 2025

Choose a reason for hiding this comment

Uh oh!

codecov-github-com bot commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

lilisha-unity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ekcoh left a comment

Choose a reason for hiding this comment

Uh oh!

ekcoh Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

ekcoh Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

ekcoh Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

ekcoh Jun 11, 2025

Choose a reason for hiding this comment

Uh oh!

ekcoh commented Jun 11, 2025

Uh oh!

Uh oh!

pFad - (p)hone/(F)rame/(a)nonymizer/(d)eclutterfier! Saves Data!

ritamerkl commented Apr 23, 2025 •

edited

Loading

jfreire-unity May 15, 2025 •

edited

Loading

codecov-github-com bot commented May 27, 2025 •

edited

Loading