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

duckets · duckets · commit 87c7ca1c98f9 · 2024-11-28T17:17:00.000Z
diff --git a/Packages/com.unity.inputsystem/Documentation~/about-action-assets.md b/Packages/com.unity.inputsystem/Documentation~/about-action-assets.md
@@ -0,0 +1,21 @@
+
+# About action assets
+
+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.
+
+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~/action-assets.md b/Packages/com.unity.inputsystem/Documentation~/action-assets.md
@@ -3,63 +3,17 @@ uid: input-system-action-assets
 ---
 # Input Action Assets
 
-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.
-
-While it's possible to have more than one Action Asset in a project, most projects only ever need a single Action Asset. 
-
-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.
-
-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).
-
-## Descriptive heading
-
-Use descriptive headings to break up the content and make the page easy to
-scan. Organize content logically and introduce ideas gradually.
-
-### Detailed heading
-
-Don't use headings below H3 level.
-
-## Additional resources
-
-- [Link](related-content-on-Unity-owned-platforms)
-- [Link](related-content-on-Unity-owned-platforms)
-
---------------------------------------------
-
-[link](##bind)
-
-- [Descriptive heading](#descriptive-heading)
-  - [Detailed heading](#detailed-heading)
-- [Additional resources](#additional-resources)
-- [Project-Wide Actions](#project-wide-actions)
-- [Using Input Action Assets](#using-input-action-assets)
-  - [Using Action Assets with `PlayerInput`](#using-action-assets-with-playerinput)
-  - [Modifying Input Action Assets at runtime](#modifying-input-action-assets-at-runtime)
-
-## Project-Wide Actions
-
-The Input System's **project-wide actions** feature allows you to choose 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 a specific asset.
-
-When you assign an Action Asset as project-wide, 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.
-
-
-
-
-## Using Input Action Assets
-
-
-### Using Action Assets with `PlayerInput`
-
-The [Player Input](player-input-component.md) component provides a convenient way to handle input for one or multiple players. You can assign your Action Asset to the Player Input component so that it can then automatically handle activating Action Maps and selecting Control Schemes for you.
-
-![PlayerInput](Images/PlayerInput.png)
-
-### 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).
+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**. 
+
+Learn how to create, assign and use them in this section.
+
+| **Topic**                       | **Description**                  |
+| :------------------------------ | :------------------------------- |
+| **[About action assets](./about-action-assets.md)** | More information to help you understand what action assets are for. |
+| **[Create and assign a project-wide action asset](create-project-wide-actions.md)** | Create an actions asset that contains the built-in default actions, and assign them as project-wide. |
+| **[Create an empty action asset](create-empty-action-asset.md)** | Create a new empty action asset. |
+| **[Assign a project-wide action asset](assign-project-wide-asset.md)** | Change which action asset is assigned as project-wide. |
+| **[Default actions](default-actions.md)** | When you create and assign default project-wide actions, the Action Asset comes pre-configured with some default Actions which suit many common app and game scenarios. Learn about them here. |
+| **[Generate C# API from actions](./link)** | 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. |
 
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/assign-project-wide-actions.md b/Packages/com.unity.inputsystem/Documentation~/assign-project-wide-actions.md
@@ -2,13 +2,16 @@
 
 To assign an existing Actions Asset as project-wide, do one of the following:
 
-- Go to **Edit** > **Project Settings** > **Input System Package**, then drag the asset from your Project window into the **Project-wide Actions** field.
+1. Go to **Edit** > **Project Settings** > **Input System Package**
+2. Drag the asset from your Project window into the **Project-wide Actions** field.
+
 ![image alt text](./Images/InputSettingsNoProjectWideAsset.png)</br>
 *The Input System Package Project Settings with no project-wide actions assigned*
 
 or:
 
-- Select the Asset in your Project window, then in the Inspector window, select **Assign as the Project-wide Input Actions**.
+1. Select the Asset in your Project window
+2. In the Inspector window, select **Assign as the Project-wide Input Actions**.
 
 
 Only one Actions Asset can be assigned as project-wide. If a different asset was previously assigned as project-wide, it becomes unassigned.
diff --git a/Packages/com.unity.inputsystem/Documentation~/create-empty-action-asset.md b/Packages/com.unity.inputsystem/Documentation~/create-empty-action-asset.md
@@ -0,0 +1,15 @@
+# Create an empty action asset
+
+Usually you only need one Action Asset, assigned as the project-wide actions. The input package provides a convenient way to [create a set of useful default actions and assign them as project-wide](assign-project-wide-actions.md). In other cases, you might want to start with an empty actions asset, or create more than one actions asset.
+
+To do this:
+
+1. Go to __Assets > Create > Input Actions__ from Unity's main menu/
+   
+(or)
+
+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).
+
diff --git a/Packages/com.unity.inputsystem/Documentation~/create-project-wide-actions.md b/Packages/com.unity.inputsystem/Documentation~/create-project-wide-actions.md
@@ -1,8 +1,4 @@
-# Create an action asset
-
-In most cases, you only need one Action Asset, assigned as the project-wide actions. The input package provides a convenient way to create a set of useful default actions and assign them as project-wide. In other cases, you might want to start with an empty actions asset, or create more than one actions asset.
-
-## Create and assign a default project-wide actions asset
+# Create and assign a default project-wide actions asset
 
 Follow these steps to create an actions asset that contains the built-in [default actions](./TheDefaultActions.md), and assign them as project-wide.
 
@@ -29,13 +25,4 @@ When you create an action asset this way, the new asset contains a set of defaul
 ![image alt text](./Images/ProjectSettingsInputActionsSimpleShot.png)
 *The Input System Package Project Settings after creating and assigning the default actions*
 
-Once you have created and assigned project-wide actions, the Input System Package page in Project Settings displays the **Actions Editor** interface. Read more about how to use the [Actions Editor](ActionsEditor.md) to configure your actions.
-
-## Create a new empty input action asset
-
-In some situations you might want to start with an empty action asset, or create additional action assets.
-
-To do this, go to __Assets > Create > Input Actions__ from Unity's main menu, or select **Input Actions** the Project window's **Add (+)** button 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](./CreateActions.md) and [configure](./ConfigureActions.md) new actions to use it. The new action asset is also not assigned as [project-wide](./ProjectWideActions.md).
-
+Once you have created and assigned project-wide actions, the Input System Package page in Project Settings displays the **Actions Editor** interface. Read more about how to use the [Actions Editor](ActionsEditor.md) to configure your actions.
diff --git a/Packages/com.unity.inputsystem/Documentation~/default-actions.md b/Packages/com.unity.inputsystem/Documentation~/default-actions.md
@@ -1,6 +1,6 @@
 # The default project-wide actions
 
-When you [create and assign default project-wide actions](CreateActionAsset.md) the Action Asset 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 from the most common types of input controller such as Keyboard, Mouse, Gamepad, Touchscreen, and extended reality (XR).
+When you [create and assign default project-wide actions](./create-project-wide-actions.md) the Action Asset 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 from the most common types of input controller such as Keyboard, Mouse, Gamepad, Touchscreen, and extended reality (XR).
 
 ![image alt text](./Images/ProjectSettingsInputActionsSimpleShot.png)
 *The Input System Package Project Settings after creating and assigning the default actions*
