more WIP for Setting up input, actions section, DOCF-5905

duckets · duckets · commit 3eff357cd7c4 · 2024-11-29T12:26:24.000Z
diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md
@@ -10,11 +10,11 @@
 * [Setting up input](setting-up-input.md)
   * [Actions](actions.md)
   * [Action Assets](action-assets.md)
-    * [Create an Action Asset](create-action-asset.md)
+    * [Create an Action Asset](create-empty-action-asset.md)
     * [Assign a project-wide Action Asset](assign-project-wide-actions.md)
     * [Default actions](default-actions.md)
-    * [Create action maps](create-action-maps.md)
-    * [Create actions](create-actions.md)
+    * [Create action maps](create-edit-delete-action-maps.md)
+    * [Create actions](create-edit-delete-actions.md)
       * [Stand-alone actions](stand-alone-actions.md)
       * [Load actions from JSON](load-actions-from-json.md)
       * [Create actions in code](create-actions-in-code.md)
@@ -29,7 +29,7 @@
   * [Devices](devices.md)
     * [Get information about devices](get-information-about-devices.md)
 * [Using the Input System]()
-  * [Project-Wide Actions](ProjectWideActions.md)
+  * [Project-Wide Actions](about-project-wide-actions.md)
   * [Configuring Input](ActionsEditor.md)
   * [Actions](Actions.md)
   * [Enabling Actions](enable-actions.md)
diff --git a/Packages/com.unity.inputsystem/Documentation~/UISupport.md b/Packages/com.unity.inputsystem/Documentation~/UISupport.md
@@ -30,7 +30,7 @@ The three main UI solutions are **UI Toolkit**, **Unity UI**, and **IMGUI**. The
 
 **For [**UI Toolkit**](https://docs.unity3d.com/Manual/UIElements.html), also known as "UI Elements" (an XML/CSS style UI solution):**
 
-- From Unity 2023.2 and onwards, the UI actions defined in the default [project-wide actions](./ProjectWideActions.md) directly map to UI Toolkit input. You do not need to use the UI Input Module component.</br></br>
+- From Unity 2023.2 and onwards, the UI actions defined in the default [project-wide actions](./about-project-wide-actions.md) directly map to UI Toolkit input. You do not need to use the UI Input Module component.</br></br>
 - In versions of Unity prior to 2023.2, you must use the UI Input Module component to define which actions are passed through from the Input System to the UI.
 
 **For [**Unity UI**](https://docs.unity3d.com/Packages/com.unity.ugui@latest), also known as "uGUI" (a GameObject and Component style UI solution):**
@@ -53,7 +53,7 @@ IMGUI|No|n/a
 
 ## Setting up UI input
 
-The default [project-wide actions](./ProjectWideActions.md) comes with a "**UI**" Action Map, that contains all the actions required for UI interaction (shown in the image below). You can configure the bindings for these actions in the [Actions Editor](./ActionsEditor.md). Go to **Project Settings > Input System Package**, then select "**UI**" in the Action Maps column.
+The default [project-wide actions](./about-project-wide-actions.md) comes with a "**UI**" Action Map, that contains all the actions required for UI interaction (shown in the image below). You can configure the bindings for these actions in the [Actions Editor](./ActionsEditor.md). Go to **Project Settings > Input System Package**, then select "**UI**" in the Action Maps column.
 
 ![ProjectSettingsInputActionsUIActionMap](Images/ProjectSettingsInputActionsUIActionMap.png)
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/about-action-assets.md b/Packages/com.unity.inputsystem/Documentation~/about-action-assets.md
@@ -3,18 +3,10 @@
 
 The Input System stores your configuration of [Input Actions](Actions.md) and their associated [Bindings](ActionBindings.md), [Action Maps](ActionsEditor.html#configure-action-maps) and [Control Schemes](ActionBindings.md#control-schemes) in an [Action Asset](ActionAssets.md) file. 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](about-project-wide-actions.md), but you can also create new Action Assets directly in the Project window.
 
 For most common scenarios, you do not need to use more than one Input Action Asset. This is because an Action Asset can contain multiple [Action Maps](ActionsEditor.html#configure-action-maps), which each containing a set of actions relevant to the various parts of your project (such as UI navigation, gameplay, etc).
 
-## Project-Wide Actions
-
-You can assign an individual Action Asset to be available "project-wide", which means the actions within that asset are available more conveniently through the Input System API without needing to set up references to the asset.
-
-When you [assign an Action Asset as project-wide](assign-project-wide-actions.md), it also becomes automatically [preloaded](https://docs.unity3d.com/ScriptReference/PlayerSettings.GetPreloadedAssets.html) when your app starts up, and is kept available until it terminates.
-
-Unless you have specific project requirements that require more than one Action Asset, the recommended workflow is to use a single Action Asset assigned as the project-wide actions.
-
 ## Modifying Input Action Assets at runtime
 There are several ways to modify an Input Action Asset at runtime. Any modifications that you make during Play mode to an Input Action Asset do not persist in the Input Action Asset after you exit Play mode. This means you can test your application in a realistic manner in the Editor without having to worry about inadvertently modifying the asset. For examples on how to modify an Input Action Asset, see the documentation on [Creating Actions in code](Actions.md#creating-actions-in-code) and [Changing Bindings](ActionBindings.md#changing-bindings).
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/about-project-wide-actions.md b/Packages/com.unity.inputsystem/Documentation~/about-project-wide-actions.md
@@ -1,7 +1,13 @@
 ---
 uid: project-wide-actions
 ---
+# Project-Wide Actions
 
+You can assign an individual Action Asset to be available "project-wide", which means the actions within that asset are available more conveniently through the Input System API without needing to set up references to the asset.
+
+When you [assign an Action Asset as project-wide](assign-project-wide-actions.md), it also becomes automatically [preloaded](https://docs.unity3d.com/ScriptReference/PlayerSettings.GetPreloadedAssets.html) when your app starts up, and is kept available until it terminates.
+
+Unless you have specific project requirements that require more than one Action Asset, the recommended workflow is to use a single Action Asset assigned as the project-wide actions.
 
 
 ## Edit project-wide actions
diff --git a/Packages/com.unity.inputsystem/Documentation~/action-properties.md b/Packages/com.unity.inputsystem/Documentation~/action-properties.md
@@ -2,3 +2,9 @@
 
 Action properties are the details about an action which describe the type of control it relates to, as well as some optional properties such as Interactions and Processors assigned to the action.
 
+
+## Action type and Control type
+
+If you select an Action, you can edit its properties in the right-hand pane of the window:
+
+![Action Properties](Images/ActionProperties.png)
diff --git a/Packages/com.unity.inputsystem/Documentation~/actions-editor.md b/Packages/com.unity.inputsystem/Documentation~/actions-editor.md
@@ -11,7 +11,7 @@ It also allows you to define [Control Schemes](ActionBindings.md#control-schemes
 
 ### Action Assets and Project-Wide 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 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](about-project-wide-actions.md).
 
 ### Opening the Actions Editor
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/api-overview.md b/Packages/com.unity.inputsystem/Documentation~/api-overview.md
@@ -5,7 +5,7 @@ When scripting with Actions in the Input System, there are number of important A
 
 |API name|Description|
 |-----|-----------|
-|[`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html)|A reference to the set of actions assigned as the [project-wide Actions](./ProjectWideActions.md).|
+|[`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).|
diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-actions.md b/Packages/com.unity.inputsystem/Documentation~/configure-actions.md
@@ -0,0 +1,18 @@
+# Configure actions
+
+Configuring an action covers all the ways an action can be set up, the controls it is bound to, and the ways it responds to signals from those controls.
+
+An action's configuration includes its properties, bindings, controls, control schemes, and interactions, described in this section.
+
+
+| **Topic**                       | **Description**                  |
+| :------------------------------ | :------------------------------- |
+| **[Action Properties](action-properties.md)** | Summary |
+| **[Bindings](bindings.md)** | Summary |
+| **[Controls](controls.md)** | Summary |
+| **[Control Schemes](control-schemes.md)** | Summary |
+| **[Interactions](interactions.md)** | Summary |
+
+## Additional resources
+
+-  [Actions Editor window reference](actions-editor.md)
diff --git a/Packages/com.unity.inputsystem/Documentation~/create-edit-delete-action-maps.md b/Packages/com.unity.inputsystem/Documentation~/create-edit-delete-action-maps.md
@@ -1,4 +1,4 @@
-# Create Action Maps
+# Create, Edit and Delete Action Maps
 
 Action maps provide a way to group collections of Actions that represent different input scenarios in your project (such as UI navigation, gameplay, etc.)
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/create-edit-delete-actions.md b/Packages/com.unity.inputsystem/Documentation~/create-edit-delete-actions.md
@@ -1,26 +1,34 @@
 
-# Create Actions
+# Create, Edit and Delete Actions
 
-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.
+The simplest way to create, edit or delete 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 there are many other ways to create actions which might suit less common scenarios. For example, by loading actions from JSON data, or creating actions entirely in code.
+However there are many other ways to work with actions which might suit less common scenarios. For example, by [loading actions from JSON data](load-actions-from-json.md), or [creating actions entirely in code](configure-input-directly-from-code.md).
 
-### Create Actions using the Action editor
+## Create 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.
 
 ![Action Editor Window](Images/ProjectSettingsInputActionsSimpleShot.png)
 *The Input Actions Editor in the Project Settings window*
 
 
-### Adding, renaming, duplicating and deleting Actions
+### Add, rename, duplicate or delete actions
 
 * To add a new Action, select the Add (+) icon in the header of the Action column.
 * To rename an existing Action, either long-click the name, or right-click the Action 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.
 
 
+If you’d like to delete all the 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 each Action Map, which deletes all the Actions contained in the maps in one go.
+
+You can also delete all action maps, or reset all the actions back to the default values from the **more** (⋮) menu at the top right of the Input Actions section of the settings window, below the Project Settings window search field.
+
+![The Input Actions **more** menu as displayed in the Project Settings window](images/InputActionsSettingsMoreMenu.png)
+
+> **Note:** this **more** (⋮) menu is only available in the Project Settings actions editor, and is not available when the Actions Editor is open in a separate window.
+
 
 
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/create-empty-action-asset.md b/Packages/com.unity.inputsystem/Documentation~/create-empty-action-asset.md
@@ -11,5 +11,5 @@ To do this:
 1. Click the project window's **Add (+)** button.
 2. Select **Input Actions** from the menu.
 
-When you create an action asset this way, the new action asset is empty, containing no actions, action maps, or control schemes. You must [add](./create-actions.md) and [configure](./configure-actions.md) new actions to use it. The new action asset is also not assigned as [project-wide](./assign-project-wide-actions.md).
+When you create an action asset this way, the new action asset is empty, containing no actions, action maps, or control schemes. You must [add](./create-edit-delete-actions.md) and [configure](./configure-actions.md) new actions to use it. The new action asset is also not assigned as [project-wide](./assign-project-wide-actions.md).
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/default-actions.md b/Packages/com.unity.inputsystem/Documentation~/default-actions.md
@@ -7,13 +7,7 @@ When you [create and assign default project-wide actions](./create-project-wide-
 
 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.
 
-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 each Action Map, which deletes all the Actions contained in the maps in one go.
 
-You can also delete all action maps, or reset all the actions back to the default values from the **more** (⋮) menu at the top right of the Input Actions section of the settings window, below the Project Settings window search field.
-
-![The Input Actions **more** menu as displayed in the Project Settings window](images/InputActionsSettingsMoreMenu.png)
-
-> **Note:** this **more** (⋮) menu is not available when the Actions Editor is open in a separate window, it is only present in the Project Settings window.
 
 ### The legacy default Actions Asset
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/enable-actions.md b/Packages/com.unity.inputsystem/Documentation~/enable-actions.md
@@ -2,7 +2,7 @@
 
 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.
+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.
 
 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.
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/generate-cs-api-from-actions.md b/Packages/com.unity.inputsystem/Documentation~/generate-cs-api-from-actions.md
@@ -1,27 +1,30 @@
 # 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.
+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. 
 
-### Auto-generating script code for Actions
+This removes the need to manually look up Actions and Action Maps using their names, and also provides an easy way to set up callbacks.
 
-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.
+> **Note**: This is an alternative workflow to [project-wide actions](./about-project-wide-actions.md), and provides a different way to access the actions defined in your action asset.
 
-To enable this option, tick the __Generate C# Class__ checkbox in the importer properties in the Inspector of the `.inputactions` Asset, then select __Apply__.
+
+To enable type-safe C# API generation:
+
+1. Select the action asset in the Project window.
+2. In the Inpsector window, enable the __Generate C# Class__ option.
+3. Select __Apply__.
 
 ![MyPlayerControls Importer Settings](Images/FireActionInputAssetInspector.png)
 
 You can optionally choose a path name, class name, and namespace for the generated script, or keep the default values.
 
-This generates a C# script that simplifies working with the Asset.
+Once applied, the Input System creates a C# script containing API that matches the actions defined in the asset which you can access directly in code. The following example demonstrates this, assuming there is an action map named "gameplay" containing two actions, "use" and "move" defined in the action asset:
 
 ```CSharp
 using UnityEngine;
 using UnityEngine.InputSystem;
 
-// IGameplayActions is an interface generated from the "gameplay" action map
-// we added (note that if you called the action map differently, the name of
-// the interface will be different). This was triggered by the "Generate Interfaces"
-// checkbox.
+// IGameplayActions is an interface generated from the "gameplay" action map.
+// Your interface name will match the name you chose for your action map.
 public class MyPlayerScript : MonoBehaviour, IGameplayActions
 {
     // MyPlayerControls is the C# class that Unity generated.
diff --git a/Packages/com.unity.inputsystem/Documentation~/polling-actions.md b/Packages/com.unity.inputsystem/Documentation~/polling-actions.md
diff --git a/Packages/com.unity.inputsystem/Documentation~/setting-up-input.md b/Packages/com.unity.inputsystem/Documentation~/setting-up-input.md
diff --git a/Packages/com.unity.inputsystem/Documentation~/understanding-input.md b/Packages/com.unity.inputsystem/Documentation~/understanding-input.md
diff --git a/Packages/com.unity.inputsystem/Documentation~/using-actions-workflow.md b/Packages/com.unity.inputsystem/Documentation~/using-actions-workflow.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Create Action Maps`
	`1`	`+# Create, Edit and Delete Action Maps`
`2`	`2`
`3`	`3`	`Action maps provide a way to group collections of Actions that represent different input scenarios in your project (such as UI navigation, gameplay, etc.)`
`4`	`4`