-
Notifications
You must be signed in to change notification settings - Fork 317
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
DOCS: cm reorg docf-6476 docf-6393 #2113
DOCS: cm reorg docf-6476 docf-6393 #2113
Conversation
Also added table to action types page
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've not finished my review but thought I would leave these comments to get you started with
Packages/com.unity.inputsystem/Documentation~/configure-action-type.md
Outdated
Show resolved
Hide resolved
|
||
The action type influences how the Input System processes state changes for the action, and relate to whether this action represents a discrete on/off button-style interaction or a value that can change gradually over time. | ||
|
||
## Action types |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is still a mixture of task and reference - I would expect this table to be on a page that is a reference for the whole Input Actions window, called something like "Input Actions reference". That window is quite big so if the page was too long, perhaps you'd divide it into smaller pages like "Action maps reference" "Action properties reference" and so on.
Then, I think I would frame this page as something like "Configure input state changes" (make it more outcome focused than ui focused - Action Type is a thing that doesn't mean much by itself).
Then make it more task focused e.g
To configure how the input system changes state, use action types. To do this:
- Open the Input window
- Select the setting
- Choose Button if you want to do blah
- Choose Value to do other thing
For more information on these settings, refer to the Actions reference.
If available, I would also mention how you could configure this in code with APIs, but if we don't have that info it's fine.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
|
||
The third option, **Pass Through**, is also a value type, and as such is suitable for the same types of device controls as described for **Value**. The difference is that if your action is set to PassThrough, the Input System only provides basic information about the values incoming from the device controls bound to it, and does not provide the extra data relating to the phase of the action, nor does it perform [conflict resolution](./binding-conflicts.md). | ||
|
||
Because pass-through actions don't perform conflict resolution, it means they don't use concept of a specific control driving the action. Instead, any change to any of the controls bound to the action triggers a callback with that Control's value. This is useful if you want to process all input from a set of controls at once on the same action, rather than only the most actuated from the set. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The content model requires we have an Additional Resources section at the end of each page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should do a pass at the end to add these, along with the link checking pass
* [Create an empty action asset](create-empty-action-asset.md) | ||
* [Assign a project-wide action asset](assign-project-wide-actions.md) | ||
* [Default actions](default-actions.md) | ||
* [Generate C# API from actions](generate-cs-api-from-actions.md) | ||
* [Create action maps](create-edit-delete-action-maps.md) | ||
* [Create, edit and delete actions](create-edit-delete-actions.md) | ||
* [Configure actions](configure-actions.md) | ||
* [Action and control types](action-and-control-types.md) | ||
* [Configure action type](configure-action-type.md) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This might be a bit overkill for such a short section, but I think it's lacking a little overview explaining what action and control types are. I feel like an intro page might be useful here. I also wonder if both task pages could be combined somehow so you have something like:
- Action and control types (potentially rename this to something more outcome based like, "Configure how actions are triggered" ?)
- Action and control types overview (you can configure how actions are triggered with action types and control types...)
- Configure action and control types (to set the types, open the window and do XYZ...)
- Action and control types reference (Unsure if you need the reference here or if you have this somewhere else in an overarching window reference page)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
@@ -1 +1,15 @@ | |||
# Configure Control Type | |||
|
|||
When you select an Action in the [Actions Editor window](./actions-editor.md), you can edit its properties in the right-hand pane of the window. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have no idea if Action should be capitalised or not, but later on this page we refer to it with a small A. Might be something to align on - I keep on seeing a mis-mash of capitals all over the place in these docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've tried to capitalize it based on whether I'm referring to the UI or not, in this case I think you're right it's not, but there's lots of left-over capitalization from the devs who capitalized Everything 😅
* [Action and control types](action-and-control-types.md) | ||
* [Configure action type](configure-action-type.md) | ||
* [Configure control type](configure-control-type.md) | ||
* [Bindings](bindings.md) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, "Bindings" is a feature based term - I'm trying to think of a good outcome-based name for this but I think it needs to be along the lines of "Configure what actions are performed." or "Connect actions to input" or similar.
These titles are absolutely terrible though and it might be better to brainstorm as a group - @siobhan-unity is usually better at these things than I am 😄
Packages/com.unity.inputsystem/Documentation~/introduction-to-bindings.md
Outdated
Show resolved
Hide resolved
@@ -0,0 +1,17 @@ | |||
# Binding types | |||
|
|||
Bindings have a **type** which can be **simple** or **composite**. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd perhaps reformat this a little bit so it's like:
You can configure how bindings map to actions with binding types. The following binding types are available:
- Simple: A single control maps directly to an action. For example, a gamepad stick to a "move" action, or a gamepad button to a "jump" action.
- Composite: Construct a binding from multiple simple bindings.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
@@ -2,318 +2,21 @@ | |||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This page should probably be called Composite bindings reference seeing as its a reference table page
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
@@ -1 +1,24 @@ | |||
# Add, duplicate or delete a binding | |||
|
|||
Open the [Actions Editor window](actions-editor.md) to add, duplicate, or delete bindings. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could probably provide directions on where the actions editor is here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The problem with this is that the actions editor appears in multiple places (in the project settings, and as a separate window if you open directly from an action asset - so the way you open it isn't a single thing like a typical menu > window > windowname thing), which is described on that page, but if we add that info to everywhere that says to open the actions editor I feel it'll end up with too much duplicate information.
@@ -0,0 +1,52 @@ | |||
# Pick a control for a binding |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The title of this page is different from what's in the TOC
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
|
||
There are three ways to specify the control path for a binding in the [Actions Editor window](./actions-editor.md). These are: | ||
|
||
- **Select the control path from a list**, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think this needs to be bold
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
Packages/com.unity.inputsystem/Documentation~/select-control-binding.md
Outdated
Show resolved
Hide resolved
|
||
``` | ||
var actionMap = new InputActionMap(); | ||
Adding or removing a device – either [globally](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_devices) or to/from the [device list](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_devices) of an Action – will remain transparent __except__ if an Action is in progress and it is the device of its [active Control](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_activeControl) that is being removed. In this case, the Action will automatically be [cancelled](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_canceled). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It might be tidier to make these xref links https://docs.unity3d.com/Packages/com.unity.package-manager-doctools@3.9/manual/ExternalLinks.html#finding-xrefs-and-uids
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
|
||
You can override this behavior by restricting an [action asset](./action-assets.md) or individual [action maps](./create-edit-delete-action-maps.md) to a specific set of Devices. If you do this, binding resolution only takes the controls of the specified devices into account. | ||
|
||
>__Note__: The Input System's [user management](user-management.md) feature and [Player Input component](player-input-component.md) make use of this automatically. They set the [`InputActionMap.devices`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_devices) for each player automatically, based on the device that is paired to each user. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can use the fancy docfx note block if you like https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#alerts
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
addressed in new changes
Co-authored-by: Jo Dawes <49957016+jo-unity@users.noreply.github.com>
Based on peer review comments
Description
Part of the Input Docs Re-org, mainly including action and control types pages, and the bindings section.
https://jira.unity3d.com/browse/DOCF-6393
https://jira.unity3d.com/browse/DOCF-6476
Testing status & QA
Built locally and checked.
Overall Product Risks
Docs only changes, no risk.
Comments to reviewers
The following pages are included in this review: