Docs/responding to input reorg docf 5906

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

@@ -66,11 +66,17 @@
     * [Control Schemes and Devices menu reference](control-schemes-devices-menu-reference.md)
   * [Devices](devices.md)
     * [Get information about devices](get-information-about-devices.md)
+* [Responding to input](respond-to-input.md)
+  * [About responding to input](about-responding-to-input.md)
+  * [Enable actions](enable-actions.md)
+  * [Polling actions](polling-actions.md)
+  * [Set callbacks on actions](set-callbacks-on-actions.md)
+  * [Read devices directly](read-devices-directly.md)
+  * [API Overview](api-overview.md)
 * [Using the Input System]()
   * [Project-Wide Actions](about-project-wide-actions.md)
   * [Configuring Input](ActionsEditor.md)
   * [Actions](actions.md)
-  * [Enabling Actions](enable-actions.md)
   * [Responding to Actions](RespondingToActions.md)
   * [Input Action Assets](ActionAssets.md)
   * [Input Bindings](ActionBindings.md)

Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md

@@ -0,0 +1,35 @@
+# About responding to input
+
+The Input System offers various ways to respond to input at runtime, from the recommended workflow using [actions](Actions.md) and [bindings](bindings.md), to more direct techniques such as reading device controls directly.
+
+## Recommended workflow
+
+Working with the Input System's [recommended workflow](Workflows.md) in your project involves two phases which you must approach in this order:
+
+1. Configure your project's actions.
+2. Implement responses to actions. 
+
+### Configure your project's actions
+
+You must first [configure input for your project](setting-up-input.md) as [actions](Actions.md), before you can respond to those actions.
+
+In some situations you might find the configuration in the [default project-wide actions](default-actions.md) covers all your needs, and you can go straight to implementing responses to input. In other cases you might want to start with the default configuration and [add or modify actions](configure-actions.md), or you can [start with an empty configuration and define your own](create-empty-action-asset.md).
+
+### Implement responses to actions
+
+Once you have your actions set up, you can implement responses to those actions.
+
+There are two main techniques you can use to respond to actions in your project. These are to either use **polling** or an **event-driven** approach.
+
+- The **polling** approach refers to the technique of repeatedly checking the current state of your actions. Typically you do this in the `Update()` method of a `MonoBehaviour` script. See [polling actions](polling-actions.md) for further information.
+
+- The **event-driven** approach involves creating your own methods in code that are automatically called when an action is performed. See [Set callbacks on actions](set-callbacks-on-actions.md) for further information.
+
+For most common scenarios, especially action games where the user's input has a continuous centralized effect on an in-game character, **polling** is usually simpler and easier to implement. For other situations where input is less continuous, or directed to many different areas in your scene, an event-driven approach might be more appropriate.
+
+## Other workflows
+
+The Input System also allows you to read device states directly, which bypasses many of the features such as actions and bindings. This workflow is suitable for fast prototyping, or single fixed platform scenarios, but is a less flexible workflow because it bypasses some useful Input System features.
+
+See [Read devices directly](read-devices-directly.md) for further information about this workflow.
+

Packages/com.unity.inputsystem/Documentation~/api-overview.md

@@ -1,15 +1,35 @@
+# API Overview
 
-## API Overview
+When scripting with Actions in the Input System, there are number of important API you can use, listed here:
 
-When scripting with Actions in the Input System, there are number of important API you can use, which are described here:
+## Namespace
+
+The Input System's API is contained in the `UnityEngine.InputSystem` namespace. To use it, include the namespace as follows:
+
+```
+using UnityEngine.InputSystem;
+```
+
+## Important API
 
 |API name|Description|
 |-----|-----------|
 |[`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html)|A reference to the set of actions assigned as the [project-wide Actions](./about-project-wide-actions.md).|
-|[`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html)|A named collection of Actions. The API equivalent to an entry in the "Action Maps" column of the [Input Actions editor](ActionsEditor.md).|
-|[`InputAction`](../api/UnityEngine.InputSystem.InputAction.html)|A named Action that can return the current value of the controls that it is bound to, or can trigger callbacks in response to input. The API equivalent to an entry in the "Actions" column of the [Input Actions editor](ActionsEditor.md).|
-|[`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html)|The relationship between an Action and the specific device controls for which it receives input. For more information about Bindings and how to use them, see [Action Bindings](ActionBindings.md).|
+|[`InputAction`](../api/UnityEngine.InputSystem.InputAction.html)|The class which represents an action. You can use a reference to an action to read the current value of the controls that it is bound to, or to trigger callbacks in response to input. This class corresponds to an entry in the **Actions**"** column of the [Input Actions editor](actions-editor.md).|
+|[`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html)|The class which represents an [action map](create-edit-delete-action-maps.md). The API equivalent to an entry in the "Action Maps" column of the [Input Actions editor](actions-editor.md).|
+|[`InputBinding`](../api/UnityEngine.InputSystem.InputBinding.html)|The relationship between an action and the specific device controls for which it receives input. For more information about Bindings and how to use them, see [bindings](bindings.md).|
+
+## Actions
+
+The [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) class represents an action in the Input System. These are the same actions that you [create in the actions editor](Actions.md).
 
-Each Action has a name ([`InputAction.name`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_name)), which must be unique within the Action Map that the Action belongs to, if any (see [`InputAction.actionMap`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_actionMap)). Each Action also has a unique ID ([`InputAction.id`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id)), which you can use to reference the Action. The ID remains the same even if you rename the Action.
+With a reference to an action, you can then read values and state changes using eeither the [polling](polling-actions.md) or [callbacks](set-callbacks-on-actions.md) workflow.
+
+Each action has a name ([`InputAction.name`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_name)), which must be unique within the Action Map that the Action belongs to, if any (see [`InputAction.actionMap`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_actionMap)). Each Action also has a unique ID ([`InputAction.id`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id)), which you can use to reference the Action. The ID remains the same even if you rename the Action.
+
+## Action maps
 
 Each Action Map has a name ([`InputActionMap.name`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_name)), which must also be unique with respect to the other Action Maps present, if any. Each Action Map also has a unique ID ([`InputActionMap.id`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_id)), which you can use to reference the Action Map. The ID remains the same even if you rename the Action Map.
+
+With a reference to an action map, you can then read all the [`actions`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_actions) which belong to that map.
+

Packages/com.unity.inputsystem/Documentation~/enable-actions.md

@@ -2,9 +2,13 @@
 
 Actions have an **enabled** state, meaning you can enable or disable them to suit different situations.
 
-If you have an Action Asset assigned as [project-wide](./about-project-wide-actions.md), the actions it contains are enabled by default and ready to use.
+## Project-wide actions
 
-For actions defined elsewhere, such as in an Action Asset not assigned as project-wide, or defined your own code, they begin in a disabled state, and you must enable them before they will respond to input.
+If you are using the recommended [project-wide actions](./about-project-wide-actions.md) workflow, those actions are enabled automatically as your project starts. You do not need to enable them.
+
+## Other actions
+
+For actions defined elsewhere, such as in an action asset not assigned as project-wide, or defined your own code, those actions begin in a disabled state, and you must enable them before you can use them to respond to input.
 
 You can enable actions individually, or as a group by enabling the Action Map which contains them.
 
@@ -16,11 +20,13 @@ lookAction.Enable();
 gameplayActions.Enable();
 ```
 
-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](ActionBindings.md#binding-resolution).
+## Behaviour when enabled
+
+When an action is enabled, 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](binding-resolution.md).
 
-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 as an action's 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).
 
-While enabled, an Action actively monitors the [Control(s)](controls.md) it's bound to. If a bound Control changes state, the Action processes the change. If the Control's change represents an [Interaction](Interactions.md) change, the Action creates a response. All of this happens during the Input System update logic. Depending on the [update mode](Settings.md#update-mode) selected in the input settings, this happens once every frame, once every fixed update, or manually if updates are set to manual.
+While enabled, the action actively monitors the [control(s)](controls.md) it is bound to. If a bound control changes state, the action processes the change. If the control's change represents an [interaction](interactions.md) change, the action creates a response. All of this happens during the Input System update logic. Depending on the [update mode](Settings.md#update-mode) selected in the input settings, this happens once every frame, once every fixed update, or manually if the update mode setting is set to manual.