DOCS: Documentation edits for clarity, usability, and conformation to doc standards #2253
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Content was not modified: this was only to make everything consistent and leverage the extended Markdown feature
# Conflicts: # Packages/com.unity.inputsystem/Documentation~/PlayerInput.md
- Applied consistent sizing for most component windows - Updated the alt text to comply with accessibility standards (not an exhaustive search; just the ones I happened to find) - Removed some images that were redundant or purely screen shots describing the UI elements that appear in the Editor (future-proofing)
- Also replaced "see <reference>" with "refer to <>" in compliance with style guide guidance
- Similar data but somewhat conflicting information on structure & syntax for InputControl paths - Merged the information from API to Manual topic on the subject, preferring the API information when it diverged - Also restructured the table a little to include links to related APIs and manual topics instead of examples - Removed only the control path information from the InputControlPath class and left a link to the manual topic behind
- Updated the installation instructions to use steps and make it standard compliant - Also changed the titles to be doc standard compliant (and updated external links pointing there)
- These weren't doc standard compliant and weren't automated (some were missing added sections) - The sidebar TOCs are already automatically generated by DocFx
- Similar to DOCATT-8578, I merged some of the manual & API documentation for InputControl & PlayerInput classes as part of edits - Also corrected some links to anchors that didn't exist in Sensors.md, HID.md, and Testing.md
# Conflicts: # Packages/com.unity.inputsystem/Documentation~/ActionBindings.md
unitALG
requested review from
LeoUnity and
jfreire-unity
and removed request for
LeoUnity
ekcoh
reviewed
Oct 14, 2025
| An Input Action Asset is an Asset which contains a set of [Input Actions](Actions.md) definitions and their associated [Bindings](ActionBindings.md) and [Control Schemes](ActionBindings.md#control-schemes). These Assets have the `.inputactions` file extension and are stored in a plain JSON format. | ||
|
|
||
| The input system creates an Action Asset when you set up the [default project-wide actions](ProjectWideActions.md), but you can also create new Action Assets directly in the Project window. | ||
| The input system creates an Action Asset when you set up the [default project-wide actions](xref:project-wide-actions), but you can also create new Action Assets directly in the Project window. |
There was a problem hiding this comment.
We say "Action Asset" in this paragraph but "Input Action Asset" in the previous paragraph, shouldn't they be consistent?
| To bring up the Action editor, double-click an `.inputactions` Asset in the Project Browser, or select the __Edit Asset__ button in the Inspector for that Asset. You can have more than one editor window open at the same time, but not for the same Asset. | ||
|
|
||
| The Actions Editor which opens is identical to the [Actions Editor in the Project Settings window](ActionsEditor.md). | ||
| The Actions Editor which opens is identical to the [Actions Editor in the Project Settings window](xref:input-system-configuring-input). |
There was a problem hiding this comment.
Here we call it Actions Editor again. Just looking for what they should be called for consistency.
| ### Creating Actions using the Action editor | ||
|
|
||
| For information on how to create and edit Input Actions in the editor, see the [Input Actions editor](ActionsEditor.md). This is the recommended workflow if you want to organise all your input actions and bindings in one place, which applies across the whole of your project. This often the case for most types of game or app. | ||
| For information on how to create and edit Input Actions in the editor, see the [Input Actions editor](xref:input-system-configuring-input). This is the recommended workflow if you want to organise all your input actions and bindings in one place, which applies across the whole of your project. This often the case for most types of game or app. |
There was a problem hiding this comment.
Typo: "This often the case....", another typo: ".....most types of game or app"
| The result is similar to using an Actions defined in the Input Actions editor, except the Actions are defined in the GameObject's properties and saved as Scene or Prefab data, instead of in a dedicated Asset. | ||
|
|
||
| When you embed actions like this, by defining serialized InputAction fields in a MonoBehaviour, the GameObject's Inspector window displays an interface similar to the Actions column of the [Actions Editor](./ActionsEditor.md), which allows you to set up the bindings for those actions. For example: | ||
| When you embed actions like this, by defining serialized InputAction fields in a MonoBehaviour, the GameObject's Inspector window displays an interface similar to the Actions column of the [Actions Editor](xref:input-system-configuring-input), which allows you to set up the bindings for those actions. For example: |
There was a problem hiding this comment.
Should it be InputAction with code formatting or even link?
Should it be MonoBehaviour with code formatting or even link?
| When you enable an Action, the Input System resolves its bindings, unless it has done so already, or if the set of devices that the Action can use has not changed. For more details about this process, see the documentation on [binding resolution](xref:input-system-action-bindings#binding-resolution). | ||
|
|
||
| You can't change certain aspects of the configuration, such Action Bindings, while an Action is enabled. To stop Actions or Action Maps from responding to input, call [`Disable`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_Disable). | ||
| You can't change certain aspects of the configuration, such Action Bindings, while an Action is enabled. To stop Actions or Action Maps from responding to input, call [`Disable`](xref:UnityEngine.InputSystem.InputAction.Disable). |
There was a problem hiding this comment.
Typo "such Action Bindings"
ekcoh
reviewed
Oct 14, 2025
|
|
||
| - [Interactive rebinding](ActionBindings.md#interactive-rebinding) (`InputActionRebindingExceptions.RebindOperation`) uses it to select between multiple suitable Controls to find the one that is actuated the most. | ||
| - [Conflict resolution](ActionBindings.md#conflicting-inputs) between multiple Controls that are bound to the same action uses it to decide which Control gets to drive the action. | ||
| For example, the PS4 controller has a gyroscope sensor built into the device which constantly feeds data about the angular velocity of the device, even if the device just sits there without user interaction. Conversely, the controller's sticks and buttons require user interaction to produce non-default values. |
There was a problem hiding this comment.
The latter part of this paragraph isn't true. The most general reason for noise in a signal is electric noise in the sensor itself. For devices where this is not filtered in firmware, driver, or OS, such controls are always noisy. E.g. gamepad sticks always produce some noise unless already filtered when they are reported to the Input System. Hence, why sticks have a dead-zone filter by default.
|
@unitALG I merged develop into this branch since it was outdated. |
ekcoh
reviewed
Oct 14, 2025
| On Windows (XInput controllers only), Universal Windows Platform (UWP), and Switch, Unity polls gamepads explicitly rather than deliver updates as events. | ||
|
|
||
| You can control polling frequency manually. The default polling frequency is 60 Hz. Use [`InputSystem.pollingFrequency`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_pollingFrequency) to get or set the frequency. | ||
| You can control polling frequency manually. The default polling frequency is 60 Hz. Use [`InputSystem.pollingFrequency`](xref:UnityEngine.InputSystem.InputSystem.pollingFrequency) to get or set the frequency. |
There was a problem hiding this comment.
I realise this is currently missing a recent change we have done in this area. Hence I would suggest we change this to something like "The default polling frequency is set by the platform to provide a good user experience for the devices supported on the platform. This frequency is guaranteed to be at least 60 Hz. You may override the polling frequency suggested by the target platform by setting InputSystem.pollingFrequency explicitly in run-time."
| ## PlayStation controllers | ||
|
|
||
| PlayStation controllers are well supported on different Devices. The Input System implements these as different derived types of the [`DualShockGamepad`](../api/UnityEngine.InputSystem.DualShock.DualShockGamepad.html) base class, which derives from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html)): | ||
| PlayStation controllers are well supported on different Devices. The Input System implements these as different derived types of the [`DualShockGamepad`](xref:UnityEngine.InputSystem.DualShock.DualShockGamepad) base class, which derives from [`Gamepad`](xref:UnityEngine.InputSystem.Gamepad)): |
There was a problem hiding this comment.
Typo? I do not think we should have capitalised Devices here? We are talking about "devices" as in "target device" (platform) and not input devices.
| * [`SetLightBarColor(Color)`](xref:UnityEngine.InputSystem.DualShock.DualShockGamepad.SetLightBarColor(UnityEngine.Color)): Used to set the color of the light bar on the controller. | ||
|
|
||
| Note that, due to limitations in the USB driver and/or the hardware, only one IOCTL (input/output control) command can be serviced at a time. [`SetLightBarColor(Color)`](../api/UnityEngine.InputSystem.DualShock.DualShockGamepad.html#UnityEngine_InputSystem_DualShock_DualShockGamepad_SetLightBarColor_UnityEngine_Color_) and [`SetMotorSpeeds(Single, Single)`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_SetMotorSpeeds_System_Single_System_Single_) functionality on Dualshock 4 is implemented using IOCTL commands, and so if either method is called in quick succession, it is likely that only the first command will successfully complete. The other commands will be dropped. If there is a need to set both lightbar color and rumble motor speeds at the same time, use the [`SetMotorSpeedsAndLightBarColor(Single, Single, Color)`](../api/UnityEngine.InputSystem.DualShock.DualShock4GamepadHID.html#UnityEngine_InputSystem_DualShock_DualShock4GamepadHID_SetMotorSpeedsAndLightBarColor_System_Single_System_Single_UnityEngine_Color_) method. | ||
| Note that, due to limitations in the USB driver and/or the hardware, only one IOCTL (input/output control) command can be serviced at a time. [`SetLightBarColor(Color)`](xref:UnityEngine.InputSystem.DualShock.DualShockGamepad.SetLightBarColor(UnityEngine.Color)) and [`SetMotorSpeeds(Single, Single)`](xref:UnityEngine.InputSystem.Gamepad.SetMotorSpeeds(System.Single,System.Single)) functionality on Dualshock 4 is implemented using IOCTL commands, and so if either method is called in quick succession, it is likely that only the first command will successfully complete. The other commands will be dropped. If there is a need to set both lightbar color and rumble motor speeds at the same time, use the [`SetMotorSpeedsAndLightBarColor(Single, Single, Color)`](xref:UnityEngine.InputSystem.DualShock.DualShock4GamepadHID.SetMotorSpeedsAndLightBarColor(System.Single,System.Single,UnityEngine.Color)) method. |
There was a problem hiding this comment.
This paragraph contains some disinformation, since it is not introduced in this PR we can leave it for now and handle it outside this PR but wanted to point this out.
| ## Xbox controllers | ||
|
|
||
| Xbox controllers are well supported on different Devices. The Input System implements these using the [`XInputController`](../api/UnityEngine.InputSystem.XInput.XInputController.html) class, which derives from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html). On Windows and UWP, Unity uses the XInput API to connect to any type of supported XInput controller, including all Xbox One or Xbox 360-compatible controllers. These controllers are represented as an [`XInputController`](../api/UnityEngine.InputSystem.XInput.XInputController.html) instance. You can query the [`XInputController.subType`](../api/UnityEngine.InputSystem.XInput.XInputController.html#UnityEngine_InputSystem_XInput_XInputController_subType) property to get information about the type of controller (for example, a wheel or a gamepad). | ||
| Xbox controllers are well supported on different Devices. The Input System implements these using the [`XInputController`](xref:UnityEngine.InputSystem.XInput.XInputController) class, which derives from [`Gamepad`](xref:UnityEngine.InputSystem.Gamepad). On Windows and UWP, Unity uses the XInput API to connect to any type of supported XInput controller, including all Xbox One or Xbox 360-compatible controllers. These controllers are represented as an [`XInputController`](xref:UnityEngine.InputSystem.XInput.XInputController) instance. You can query the [`XInputController.subType`](xref:UnityEngine.InputSystem.XInput.XInputController.subType) property to get information about the type of controller (for example, a wheel or a gamepad). |
There was a problem hiding this comment.
Also here it looks like we have capitalised "Devices" without clear reason?
|
|
||
| >__Tip__: If you don't know the format of a given HID you want to support, you can open the Input Debugger with the Device plugged in and pop up both the debugger view for the Device and the window showing the HID descriptor. Then, you can go through the Controls one by one, see what happens in the debug view, and correlate that to the Controls in the HID descriptor. You can also double-click individual events and compare the raw data coming in from the Device. If you select two events in the event trace, you can then right-click them and choose __Compare__ to open a window that shows only the differences between the two events. | ||
| > [!TIP] | ||
| > If you don't know the format of a given HID you want to support, you can open the Input Debugger with the Device plugged in and pop up both the debugger view for the Device and the window showing the HID descriptor. Then, you can go through the Controls one by one, see what happens in the debug view, and correlate that to the Controls in the HID descriptor. You can also double-click individual events and compare the raw data coming in from the Device. If you select two events in the event trace, you can then right-click them and choose __Compare__ to open a window that shows only the differences between the two events. |
There was a problem hiding this comment.
Not sure if it is part of language guidelines but "pop up" sounds a bit too relaxed and unclear compared to "open" or similar?
ekcoh
reviewed
Oct 15, 2025
ekcoh
approved these changes
Oct 15, 2025
Removed <para> that seemed accidental causing package validation error.
|
Attempted to fix package validation error for PlayerInput.cs in #a02dd90. |
|
I currently do not see what might be causing " |
|
There seems to be a lot of errors for images that are not being used in the docs anymore? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Based on the following feedback tickets, I edited some of the pages in the manual:
<layoutName>{usageName}controlName#(displayName)was the composition of the path, while the InputControlPath class said it was<Layout>{Usage}#(DisplayName)Name).In addition to those content changes, I also performed a number of changes across several pages that were either structural or more global fixes, which I made in separate commits for clarity:
Testing status & QA
Overall Product Risks
Low risk, since no code was modified.
Comments to reviewers
Checklist
DOCS:.