DOCS: ISX-1883 Updated manual documentation to provide guidance for how to work with project-wide actions as an asset. (#1867)

* DOCS: Doc and UI updates reflecting change to storing project wide actions as asset.

* DOCS: Amendments to PlayerInput manual page.

* DOCS: ISX-1856 Improved documentation on PlayerInput component in workflows page.

* DOCS: Added documentation of the project settings action editor "more" menu and how to use it.

---------

Co-authored-by: Håkan Sidenvall <[email protected]>
Co-authored-by: Lyndon Homewood <[email protected]>

Author: 3 people

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

@@ -3,23 +3,17 @@ uid: input-system-action-assets
 ---
 # Input Action Assets
 
-* [Creating Action Assets](#creating-input-action-assets)
-* [Editing Action Assets](#editing-input-action-assets)
-* [Using Action Assets](#using-input-action-assets)
+- [Creating Input Action Assets](#creating-input-action-assets)
+- [Editing Input Action Assets](#editing-input-action-assets)
+- [Using Input Action Assets](#using-input-action-assets)
+- [Type-safe C# API Generation](#type-safe-c-api-generation)
 
 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.
 
-### Why use an Input Action Asset instead of configuring actions in the Project Settings window?
+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.
 
-Input Action Assets contain the same type of data that you see in the input settings in the Project Settings window, but instead of stored as part of your project settings, they are contained in an asset.
+For most common scenarios, you do not need to use more than one Input Action Asset. It is usually simpler to configure your project-wide action definition in the Project Settings window.
 
-For most common scenarios, you do not need to use an Input Action Asset. It is usually simpler to configure your project-wide action definition in the Project Settings window.
-
-Input Action Assets exist because, in earlier versions of the Input System package, they were the _only_ way to configure actions. Now that you can configure actions in the Project Settings window, creating Action Assets is a largely redundant workflow, but it still exists for backwards-compatibility.
-
-#### Type-safe C# API Generation
-
-Input Action Assets have a feature that is not present for project-wide actions, which is that you can **generate a C# class** from your action definitions, which allow you to refer to your actions in a type-safe manner from code. This means you can avoid looking up your actions by string. This is one reason you might choose to use an Action Asset instead of the project-wide actions defined in the Project Settings window. See below for more information on this.
 
 ## Creating Input Action Assets
 
@@ -34,6 +28,11 @@ The Actions Editor which opens is identical to the [Actions Editor in the Projec
 
 ## Using Input Action Assets
 
+
+## Type-safe C# API Generation
+
+Input Action Assets allow you to **generate a C# class** from your action definitions, which allow you to refer to your actions in a type-safe manner from code. This means you can avoid looking up your actions by string.
+
 ### Auto-generating script code for Actions
 
 One of the most convenient ways to work with `.inputactions` Assets in scripts is to automatically generate a C# wrapper class for them. This removes the need to manually look up Actions and Action Maps using their names, and also provides an easier way to set up callbacks.
@@ -118,4 +117,4 @@ void Start()
 }
 ```
 
-> __Note:__ This default actions asset is entirely separate from the default actions that appear in the project-wide actions in the Project Settings window, and should also be considered outdated and redundant.
+> __Note:__ This default actions asset is older than, and entirely separate from the [default project-wide actions](ProjectWideActions.md). It is a legacy asset that remains included in the package for backward compatibility.

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

@@ -29,11 +29,11 @@ Actions also make it simpler to create a system that lets your players [customiz
 
 ## Overview
 
-When scripting with Actions in the Input System, there are number of important classes you can use, which are described here:
+When scripting with Actions in the Input System, there are number of important API you can use, which are described here:
 
-|Class|Description|
+|API name|Description|
 |-----|-----------|
-|`InputSystem.actions`|A reference to the set of actions configured in the [Input Actions editor](ActionsEditor.md). |
+|[`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html)|A reference to the set of actions assigned as the [project-wide Actions](./ProjectWideActions.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).|
@@ -46,11 +46,7 @@ Each Action Map has a name ([`InputActionMap.name`](../api/UnityEngine.InputSyst
 
 The simplest way to create actions is to use the [Input Actions editor](ActionsEditor.md) in the Project Settings window. This is the primary recommended workflow and suitable for most scenarios.
 
-However, because the input system API is very open, there are many other ways to create actions which may suit less common scenarios. For example:
-
-- You can create [Input Actions assets](ActionAssets.md) which define a set of action data similar to that defined in Project Settings, but is instead stored in a self-contained asset (this is an outdated workflow but is still supported).
-- You can manually load Actions from JSON data.
-- You can create Actions entirely in code, including setting up the bindings.
+However, because the input system API is very open, there are many other ways to create actions which may suit less common scenarios. For example, by loading actions from JSON data, or creating actions entirely in code.
 
 ### Creating Actions using the Action editor
 
@@ -62,18 +58,11 @@ For information on how to create and edit Input Actions in the editor, see the [
 
 # Other ways to create Actions
 
-The simplest way to create actions is to use the [Input Actions editor](ActionsEditor.md) as described above. However, because the Input System package API is open and flexible, you can create actions using alternative techniques. These alternatives might be more suitable if you developing something unusual or want to customize your project beyond the standard workflow.
-
-### Creating Actions in Input Action Assets
-
-You can create actions that are stored in an Asset instead of in your Project Settings, by creating an [Action Asset](ActionAssets.md). This workflow used to be the main workflow in previous versions of the Input System package, but has been superseded by the [Input Actions editor](ActionsEditor.md) in the Project Settings window, which provides a simpler workflow.
-
-However it is still possible to create [Action Assets](ActionAssets.md) which contain a complete set of Action Maps, Actions and Bindings, and use those instead of the project-wide Actions that are defined in the Project Settings window.
-
+The simplest way to create actions is to use the [Input Actions editor](ActionsEditor.md) to configure a set of actions in an asset, as described above. However, because the Input System package API is open and flexible, you can create actions using alternative techniques. These alternatives might be more suitable if you want to customize your project beyond the standard workflow.
 
 ### Creating Actions by declaring them in MonoBehaviours
 
-As an alternative workflow, you can declare individual [Input Action](../api/UnityEngine.InputSystem.InputAction.html) and [Input Action Maps](../api/UnityEngine.InputSystem.InputActionMap.html) as fields directly inside `MonoBehaviour` components, like this:
+As an alternative workflow, you can declare individual [Input Action](../api/UnityEngine.InputSystem.InputAction.html) and [Input Action Maps](../api/UnityEngine.InputSystem.InputActionMap.html) as fields directly inside `MonoBehaviour` components.
 
 ```CSharp
 using UnityEngine;
@@ -88,49 +77,18 @@ public class ExampleScript : MonoBehaviour
 
 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 in a MonoBehaviour and assign that MonoBehaviour to a GameObject, the GameObject's Inspector window displays an interface similar to the Actions Asset window, 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](./ActionsEditor.md), which allows you to set up the bindings for those actions. For example:
 
 ![MyBehavior Inspector](Images/Workflow-EmbeddedActionsInspector.png)
 
-The visual editors work similarly to the [Input Actions editor](ActionsEditor.md).
-
 * To add or remove Actions or Bindings, click the Add (+) or Remove (-) icon in the header.
 * To edit Bindings, double-click them.<br>
 * To edit Actions, double-click them in an Action Map, or click the gear icon on individual Action properties.<br>
 * You can also right-click entries to bring up a context menu, and you can drag them. Hold the Alt key and drag an entry to duplicate it.
 
 Unlike the project-wide actions in the Project Settings window, you must manually enable and disable Actions and Action Maps that are embedded in MonoBehaviour components.
 
-```CSharp
-public class MyBehavior : MonoBehaviour
-{
-    // ...
-
-    void Awake()
-    {
-        fireAction.performed += OnFire;
-        lookAction.performed += OnLook;
-
-        gameplayActions["fire"].performed += OnFire;
-    }
-
-    void OnEnable()
-    {
-        fireAction.Enable();
-        lookAction.Enable();
-
-        gameplayActions.Enable();
-    }
-
-    void OnDisable()
-    {
-        fireAction.Disable();
-        lookAction.Disable();
-
-        gameplayActions.Disable();
-    }
-}
-```
+When you use this workflow, the serialised action configurations are stored with the parent GameObject as part of the scene, opposite to being serialised with an Action Asset. This can be useful if you want to bundle the control bindings and behaviour together in a single monobehaviour or prefab, so it can be distributed together. However, this can also make it harder to organize your full set of control bindings if they are distributed across multiple prefabs or scenes.
 
 ### Loading Actions from JSON
 
@@ -177,7 +135,13 @@ Any action that you create in this way during Play mode do not persist in the In
 
 ## Enabling actions
 
-Actions defined in the [Input Actions editor](ActionsEditor.md) are enabled by default and ready to use. For actions defined elsewhere, such as in your own code or in Action Assets, they begin in a disabled state, and you must enable them before they will respond to input. You can enable them individually, or as a group by enabling the Action Map which contains them.
+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](./ProjectWideActions.md), the actions it contains are enabled by default and ready to use.
+
+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.
+
+You can enable actions individually, or as a group by enabling the Action Map which contains them.
 
 ```CSharp
 // Enable a single action.

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

@@ -1,29 +1,31 @@
 ---
 uid: input-system-configuring-input
 ---
-# Configuring Input
+# Configuring Input with the Actions Editor
 
-The **Input Actions Editor** allows you to configure [Input Actions](Actions.md) and their associated [Bindings](ActionBindings.md) and [Control Schemes](ActionBindings.md#control-schemes).
+The **Input Actions Editor** allows you to edit [Action Assets](ActionAssets.md), which contain a saved configuration of [Input Actions](Actions.md) and their associated [Bindings](ActionBindings.md).
 
-Open the Input Actions settings by going to **Edit** > **Project Settings** > **Input System Package** > **Input Actions**
+It allows you to group collections of Actions into [Action Maps](ActionsEditor.html#configure-action-maps), which represent different input scenarios in your project (such as UI navigation, gameplay, etc.)
 
-![image alt text](./Images/ProjectSettingsInputActions.png)
-*The Input Actions editor in the Project Settings window*
+It also alows you to define [Control Schemes](ActionBindings.md#control-schemes) which are a way to enable or disable a set of devices, or respond to which type of device is being used. This is often useful if you want to customise your UI based on whether your users are using mouse, keyboard, or gamepad as their chosen input.
 
-The Input Action editor is divided into three panels (marked A, B & C above).
+### Action Assets and Project-Wide Actions
 
-### The default Actions
+The typical workflow for most projects is to have a single Action Asset, which is assigned as the **project-wide actions**. If you have not yet created and assigned an Actions Asset as the project-wide actions, the recommended workflow is to do this first. Read more about [project-wide actions](ProjectWideActions.md).
 
-The Input System comes pre-configured with some default Actions such as "Move", "Jump", and more, which suit many common app and game scenarios. They are configured to read input most types of input controller such as Keyboard, Mouse, Gamepad, Touchscreen and XR.
+### Opening the Actions Editor
 
-When you first open the Input Actions Editor, you can see the default action maps and actions displayed.
+The **Input Actions Editor** is an editor window displayed when you open an Action Asset by double-clicking it.
 
-These default actions mean that in many cases, you can start scripting with the Input System without any configuration by referring to the names of the default actions that are already configured for you. You can also rename and reconfigure the default actions, or delete these default configurations to suit your needs.
+It is also displayed in the Project Settings window under **Edit** > **Project Settings** > **Input System Package** if you have an Action Asset assigned as project-wide.
 
-If you’d like to delete all the default actions so that you can start from an empty configuration, you don’t need to delete the individual actions one-by-one. You can delete the default Action Maps, which deletes all the Actions contained in those maps in one go.
+![image alt text](./Images/ActionsEditorCallout.png)
+*The Input Actions editor, displaying the default actions*
 
 ### The Actions Editor panels
 
+The Input Actions editor is divided into three panels (marked A, B & C above).
+
 |Name|Description|
 |-|-|
 |**(A) Action Maps**|Displays the list of currently defined Action Maps. Each Action Map is a collection of Actions that you can enable or disable together as a group.|
@@ -43,7 +45,8 @@ If you’d like to delete all the default actions so that you can start from an
 * To rename an existing Action, either long-click the name, or right-click the Action Map and select __Rename__ from the context menu.
 * To delete an existing Action, either right-click it and select __Delete__ from the context menu.
 * To duplicate an existing Action, either right-click it and select __Duplicate__ from the context menu.
-* To re-order actions in the list, drag an action and drop it to its new position in the list. **Note:** The order of actions in this window is for visual convenience only, and does not affect the order in which the actions are triggered in your code. If multiple actions are performed in the same frame, the order in which they are reported by the input system is undefined. To avoid problems, you should not write code that assumes they will be reported in a particular order.
+*
+
 
 ## Action type and Control type
 

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

@@ -16,3 +16,4 @@ This page introduces the basic concepts that relate to working with the Input Sy
 |[**Action Map**](ActionsEditor.html#configure-action-maps) | Action Maps allow you to organise Actions into groups which represent specific situations where a set of actions make sense together. You can simultaneously enable or disable all Actions in an action map, so it is useful to group Actions in Action Maps by the context in which they are relevant. For example, you might have one action map for controlling a player, and another for interacting with your game's UI.|
 |[**Binding**](ActionBindings.html)| A connection defined between an **Action** and specific device controls. For example, your "Move" action might have bindings to the arrow keys and WSAD keys on the keyboard, and the left stick on a joypad, and the primary 2D axis on a VR controller. Multiple bindings like this means your game can accept cross-platform input. |
 |[**Your Action Code**](RespondingToActions.md)| The part of your script which is executed based on the actions you have configured. In your code, you can use references to actions to either read the current value or state of the action (also known as "polling"), or set up a callback to call your own method when actions are performed.|
+|[**Action Asset**](ActionAssets.md) | An asset type which contains a saved configuration of Action Maps, Actions and Bindings. You can specify one Action Asset in your project as the [project-wide actions](ProjectWideActions.md), which allows you to easily reference those actions in code by using [`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html). |