Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ uid: input-system-workflow-project-wide-actions

<img src="Images/Workflow-Actions.png" height="200px">

<br/>
While the Input System has a variety of workflows to choose from, this is the primary recommended workflow, which suits most common scenarios for game and app input.

In this workflow, you configure Actions in the [**Input Actions** editor](ActionsEditor.html), then set up references to those actions and read their values in your code.
Expand Down Expand Up @@ -36,7 +37,8 @@ There are various ways to access your actions from code. One of the simplest way

Use `FindAction` to search for an action by name from within the set of configured actions, and return a reference which you can then either read the value directly (also called "polling"), or you can attach callback methods that are called when the action is performed. The workflow described on this page focuses only on reading the action values. [You can read more about using callbacks here](RespondingToActions.html#action-callbacks).

> __Tip__: Finding and storing a reference to an Action is similar to finding and storing a reference to a Component, so if you have done that elsewhere in Unity, this might be a familiar process.
> [!TIP]
> Finding and storing a reference to an Action is similar to finding and storing a reference to a Component, so if you have done that elsewhere in Unity, this might be a familiar process.

To use `FindAction` to get references to your Actions and read user input in your script, use the following steps:

Expand Down Expand Up @@ -95,9 +97,11 @@ public class Example : MonoBehaviour
}
```

> **Note:** You should avoid using `FindAction` in your `Update()` loop, because it performs a string-based lookup which could impact performance. This is why the Action references in the example above are found during the Start() function, and stored in variables after finding them.
> [!TIP]
> You should avoid using `FindAction` in your `Update()` loop, because it performs a string-based lookup which could impact performance. This is why the Action references in the example above are found during the Start() function, and stored in variables after finding them.

> **Note:** The [InputSystem.actions](../api/UnityEngine.InputSystem.InputSystem.html) API refers specifically to the Action Asset assigned as the [project-wide actions](ProjectWideActions.md). Most projects only require one Action Asset, but if you are using more than one Action Asset, you must create a reference using the type InputActionAsset to the asset you want to access.
> [!NOTE]
> The [InputSystem.actions](../api/UnityEngine.InputSystem.InputSystem.html) API refers specifically to the Action Asset assigned as the [project-wide actions](ProjectWideActions.md). Most projects only require one Action Asset, but if you are using more than one Action Asset, you must create a reference using the type InputActionAsset to the asset you want to access.

## Pros and Cons

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ uid: input-system-workflow-direct

<img src="Images/Workflow-Direct.png" height="200px">

<br/>
This is the simplest and most direct input workflow, but the least flexible. It bypasses the [Input Actions editor](ActionsEditor.md), so you do not benefit from all the features come with [Actions](Actions.md).

It can be useful if you want a quick implementation with one specific type of device. It's generally not the best choice if you want to provide your users with multiple types of input or if you want to target multiple platforms.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ uid: input-system-workflow-player-input

<img src="Images/Workflow-PlayerInput.png">

<br/>
The highest level of abstraction provided by the Input System is when you use [Actions](Actions.html) and the **Player Input component** together.

The Player Input provides a way to make connections between your configured Actions and the C# methods in your own MonoBehaviour scripts, so that your desired C# methods are called when the user performs an input action.
Expand Down Expand Up @@ -51,7 +52,8 @@ public class ExampleScript : MonoBehaviour
}
```

> __Note__: As a general rule, if you are using the PlayerInput workflow, you should read input through callbacks as described above, however if you need to access the input actions asset directly while using the PlayerInput component, you should access the [PlayerInput component's copy of the actions](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions), not `InputSystem.actions`.
> [!NOTE]
> As a general rule, if you are using the PlayerInput workflow, you should read input through callbacks as described above, however if you need to access the input actions asset directly while using the PlayerInput component, you should access the [PlayerInput component's copy of the actions](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_actions), not `InputSystem.actions`.
>
> This is because the PlayerInput component performs device filtering to automatically assign devices to multiple players, so each instance has its own copy of the actions filtered for each player. If you bypass this by reading `InputSystem.actions` directly, the automatic device assignment won't work.

Expand Down
11 changes: 6 additions & 5 deletions Packages/com.unity.inputsystem/Documentation~/Workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,13 @@ You can choose to configure Actions and Bindings in the Editor UI, or you can se

The descriptions below describe these main workflows and link to more detailed description of them.

|Workflows |Description |
| **Workflow** | **Interactions** |
|---|---|
|[**Using Actions**](Workflow-Actions.md)|This is the **recommended** workflow for most situations. In this workflow, you use the [Actions Editor window](./ActionsEditor.md) to configure sets of actions and bindings, then set up references and read the values for those actions in your code.|
|[**Using Actions and the PlayerInput Component**](Workflow-PlayerInput.md)|This workflow provides extra features that allow you to connect up **callbacks** directly from Actions to your own callback handler methods, removing the need to deal with Action references in your code. It also provides features that are useful in **local multiplayer** scenarios such as device assignment and split-screen functionality.|
|[**Directly read device states**](Workflow-Direct.md)|This workflow is a simplified, script-only approach which bypasses the Actions and Bindings features entirely. Instead your script explicitly references specific device controls (such as "left gamepad stick") and reads the values directly. This is suitable for **fast prototyping**, or single fixed platform scenarios. It is a **less flexible** workflow because it bypasses some of the main input system features|
|[**Using Actions**](Workflow-Actions.md)<br/><br/>This is the **recommended** workflow for most situations. In this workflow, you use the [Actions Editor window](./ActionsEditor.md) to configure sets of actions and bindings, then set up references and read the values for those actions in your code.|![The Input Device and Actions icons under the Binding header lead directly into the icon representing your action code.](Images/Workflow-Actions.png)|
|[**Using Actions and the PlayerInput Component**](Workflow-PlayerInput.md)<br/><br/>This workflow provides extra features that allow you to connect up **callbacks** directly from Actions to your own callback handler methods, removing the need to deal with Action references in your code. It also provides features that are useful in **local multiplayer** scenarios such as device assignment and split-screen functionality.|![The Input Device and Actions icons under the Binding header lead into the PlayerInput Component and from there into the icon representing your action code.](Images/Workflow-PlayerInput.png)|
|[**Directly read device states**](Workflow-Direct.md)<br/><br/>This workflow is a simplified, script-only approach which bypasses the Actions and Bindings features entirely. Instead your script explicitly references specific device controls (such as "left gamepad stick") and reads the values directly. This is suitable for **fast prototyping**, or single fixed platform scenarios. It is a **less flexible** workflow because it bypasses some of the main input system features|![The Input Device icon leads directly into the icon representing your action code.](Images/Workflow-Direct.png)|



> **Note**: Because the Input System has multiple workflows, the code samples used throughout this documentation also vary, often demonstrating techniques using various workflows. For example, some code samples may use Action references, and some may use the workflow of reading input directly from devices.
> [!NOTE]
> Because the Input System has multiple workflows, the code samples used throughout this documentation also vary, often demonstrating techniques using various workflows. For example, some code samples may use Action references, and some may use the workflow of reading input directly from devices.