Skip to content
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

Merged
merged 15 commits into from
Jan 30, 2025

Conversation

duckets
Copy link
Collaborator

@duckets duckets commented Jan 23, 2025

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:

* [Action and control types](action-and-control-types.md)
  * [About action and control types](about-action-control-types.md)
  * [Configure action type](configure-action-type.md)
  * [Action types reference](action-type-reference.md)
  * [Configure control type](configure-control-type.md)
* [Bindings](bindings.md)
  * [Introduction to bindings](introduction-to-bindings.md)
  * [Binding types](binding-types.md)
  * [Composite bindings](composite-bindings.md)
  * [Add, duplicate or delete a binding](add-duplicate-delete-binding.md)
  * [Select a control for binding](select-control-binding.md)
  * [Edit composite bindings](edit-composite-bindings.md)
  * [Group bindings to control schemes](group-binding-to-control-scheme.md)
  * [Binding resolution](binding-resolution.md)
  * [Restrict binding to a specific device](restrict-binding-specific-device.md)
  * [Binding conflicts](binding-conflicts.md)
  * [Initial state checks](binding-initial-state-checks.md)

@duckets duckets changed the base branch from develop to docs-content-model-reorg January 23, 2025 15:05
Copy link
Collaborator

@jo-unity jo-unity left a 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


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
Copy link
Collaborator

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:

  1. Open the Input window
  2. Select the setting
  3. Choose Button if you want to do blah
  4. 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.

Copy link
Collaborator Author

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.
Copy link
Collaborator

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.

Copy link
Collaborator Author

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)
Copy link
Collaborator

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)

Copy link
Collaborator Author

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.
Copy link
Collaborator

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.

Copy link
Collaborator Author

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)
Copy link
Collaborator

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 😄

@@ -0,0 +1,17 @@
# Binding types

Bindings have a **type** which can be **simple** or **composite**.
Copy link
Collaborator

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.

Copy link
Collaborator Author

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 @@

Copy link
Collaborator

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

Copy link
Collaborator Author

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.
Copy link
Collaborator

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

Copy link
Collaborator Author

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
Copy link
Collaborator

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

Copy link
Collaborator Author

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**,
Copy link
Collaborator

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addressed in new changes


```
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).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Collaborator Author

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.
Copy link
Collaborator

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addressed in new changes

duckets and others added 3 commits January 27, 2025 15:22
Co-authored-by: Jo Dawes <49957016+jo-unity@users.noreply.github.com>
@duckets duckets merged commit 4362972 into docs-content-model-reorg Jan 30, 2025
2 checks passed
@duckets duckets deleted the docs-cm-reorg-DOCF-6476-DOCF-6393 branch January 30, 2025 13:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants