Essential Summary of Unity's New Input System
Published: 2024-01-17 05:31:00

## The Input Action System

### The basic idea
- The User presses a button on a device 
  (User > Device > Interaction)
- There is a Binding between Device, Interaction, and Actions
- The Action calls a method in our code
- The code reacts to the interaction

![Unity Input System Response Steps in a picture](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o8wo2b5fpyiz4smmb6yz.png)
[Photo's reference](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.7/manual/Concepts.html)

### Input Action Maps
- An Action Map provides controls for different circumstances and levels.
- Each Action Map has a name and an ID too, which are unique within the Action Asset that the Action Map belongs to (if any).
- For an Action to do something, you must first enable it, individually or in bulk through Action maps. When you enable an Action, the Input System resolves its bindings.
- To stop Actions or Action Maps from responding to input, call Disable.

This is what happens on Enabling an action:

```
Update()/FixedUpdate()/ manual updates 
{
  > The Action actively monitors the Control(s) it's bound to
  > If (a bound Control state changes)
    {
       The action processes the change 
       {
          > If (the Control's change represents an 
                 Interaction change)
            {
               > The action creates a response.
            }
        }
     }
 }

```

- Each Action Map has an InputActionMap.[actionTriggered ](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Actions.html#inputactionmapactiontriggered-callback:~:text=InputActionMap.actionTriggered%20callback)callback.

### Input Actions
- Input Actions are designed to separate the logical meaning of an input from the physical means of input.
- Actions use InputBinding to refer to the inputs they collect.
- Each Action has a name (InputAction.name), which must be unique within the Action Map that the Action belongs to, and a unique ID (InputAction.id), which you can use to reference the Action.
- The Actions can be: created in its dedicated ActionAssets’ Editor, embedded in the MoboBehaviour components, manually loaded from a JSON file, or created directly in code.
**Note: **You must manually enable and disable Actions and Action Maps that are embedded in MonoBehaviour components.
- An Action doesn't represent an actual response to input by itself. It informs your code that a certain type of input has occurred. Your code then responds to this.
- Each Action has a started, performed, and canceled [callback](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Actions.html#started-performed-and-canceled-callbacks).
- You can poll the current state of an Action (the current value of an action) whenever you need it; to do this, use **InputAction.ReadValue<>()**.
- **InputActionTrace** can record changes happening on Actions.
- You can also use [PlayerInput](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Components.html#notification-behaviors) to pick up input from Actions.
- Action phases in receiving an input: Disabled, Waiting, Started, Performed, Canceled. 
- You can read the current phase of an action using **InputAction.phase**. The last 3 phases have a callback associated with them.

**Note:** Each callback receives an **InputAction.CallbackContext** structure, which holds context information that you can use to query the current state of the Action and to read out values from Controls that triggered the Action (InputAction.CallbackContext.ReadValue).
**Note:** The contents of the structure are only valid for the duration of the callback. In particular, it isn't safe to store the received context and later access its properties from outside the callback.
- When and how the callbacks are triggered depends on the Interactions present on the respective Bindings. If the Bindings have no Interactions that apply to them, the default Interaction applies.
- At runtime >> a Controller sends an Input >> an Interaction completes >> the Action triggered >> the code responses
- There are 3 different [Action Types](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/api/UnityEngine.InputSystem.InputActionType.html) that you can select in the Input Action editor window, or by specifying it as a parameter when you call the InputAction() constructor. The default Action Type is Value.
Learn More about them [here](https://www.youtube.com/watch?v=DMUZfVSYJfs).
In Summary:
- Use the **Value type** for any inputs that should track continuous changes to the state of a Control. When the Action is initially enabled, it performs an initial state check of all bound Controls. If any of them is actuated, the Action then triggers a callback with the current value.
- The **Button type** is very similar to the Value type, but its Actions can only be bound to ButtonControl controls, and it doesn’t perform the initial state check as the Value one does. Use this for inputs that trigger an Action once every time they are pressed.
- With the **Pass-Through type**, any change to any bound Control triggers a callback with that Control's value. It won’t try to determine where this value is coming from. This is useful if you just have one set of controls, and want to process all input from a set of Controls.
- To see currently enabled Actions and their bound Controls, use the [Input Debugger](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Debugging.html#debugging-actions). Here is a [tutorial](https://www.google.com/search?q=unity+inputaction+visualizer&source=lmns&tbm=vid&bih=685&biw=1309&rlz=1C5CHFA_enCA968CA968&hl=en&sa=X&ved=2ahUKEwiho_epgcWDAxX7ETQIHUa2A50Q0pQJKAF6BAgBEAQ#fpstate=ive&vld=cid:1bf2d7e1,vid:ICh1ZEaVUjc,st:0).
- You can also use the [InputActionVisualizer](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Debugging.html#inputactionvisualizer) component from the Visualizers sample to get an on-screen visualization of an Action's value and Interaction state in real-time.

### Input Action Asset
- An [Input Action Asset](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/ActionAssets.html) is an Asset that contains Input Actions and their associated Bindings and Control Schemes. These Assets have the _.inputactions_ file extension and are stored in a plain JSON format.
- In the Control picker window, you can explore a tree of Input Devices and Controls that the Input System recognizes and binds to these Controls. 
- The Device and Control tree is organized hierarchically from generic to specific. [Ref](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/ActionAssets.html#:~:text=The%20Device%20and%20Control%20tree%20is%20organized%20hierarchically%20from%20generic%20to%20specific.)
- Instead of browsing the tree to find the Control you want, it's easier to let the Input System listen for input. [Ref](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/ActionAssets.html#:~:text=Instead%20of%20browsing%20the%20tree%20to%20find%20the%20Control%20you%20want%2C%20it%27s%20easier%20to%20let%20the%20Input%20System%20listen%20for%20input.)
- Finally, you can choose to manually edit the Binding path, instead of using the Control picker. [Ref](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/ActionAssets.html#:~:text=Finally%2C%20you%20can%20choose%20to%20manually%20edit%20the%20Binding%20path%2C%20instead%20of%20using%20the%20Control%20picker.)

#### Using Input Action Assets
**Auto-generating script code for Actions - ** [Video](https://youtu.be/m5WsmlEOFiA?t=609)
- One of the most convenient ways to work with .inputactions Assets in scripts is to automatically generate a C# wrapper class for them. 
*Using Action Assets with PlayerInput Component* - [Video](https://youtu.be/m5WsmlEOFiA?t=709)
- set up all your Actions in an Input Action Asset
>> Then assign it to the [PlayerInput component](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Components.html#playerinput-component)
>> which can automatically handle activating Action Maps and selecting Control Schemes for you

### Input Bindings
- During the **disambiguation** process, the Input System looks at the value of each Control bound to an Action. If the magnitude of the input from any Control is higher than the [magnitude](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Controls.html#control-actuation:~:text=It%20can%20be%20useful%20to%20determine%20not%20just%20whether%20a%20Control%20is%20actuated%20at%20all%2C%20but%20also%20the%20amount%20by%20which%20it%20is%20actuated%20(that%20is%2C%20its%20magnitude).%20For%20example%2C%20for%20a%20Vector2Control%20this%20would%20be%20the%20length%20of%20the%20vector%2C%20whereas%20for%20a%20button%20it%20is%20the%20raw%2C%20absolute%20floating%2Dpoint%20value.) of the Control currently driving the Action, then the Control with the higher magnitude becomes the new Control driving the Action.
- If you don't want your Action to perform disambiguation, you can set your Action type to Pass-Through.
- Runtime rebinding allows users of your application to set their own Bindings.

### Input Interactions
- An [Interaction](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Interactions.html) represents a specific input pattern. For example, a hold is an Interaction that requires a Control to be held for at least a minimum amount of time.
- Interaction’s phases: Waiting, Starting, Performed, Canceled
- Not every Interaction triggers every phase.
- Using Interactions: You can install Interactions on Bindings or Actions.
- Interactions on Actions work very similar to Interactions on Bindings, but they affect all Controls bound to an Action, not just the ones coming from a specific Binding. If there are Interactions on both the Binding and the Action, the Input System processes the ones from the binding first.

Here are the [Predefined Interactions](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Interactions.html#:~:text=duration%3D0.8\)%22\)%3B-,Predefined%20Interactions,-The%20Input%20System):
> Default Interaction
> Press
> Hold
> Tap
> SlowTap
> MultiTap

**Note:** You can write your own [custom Interaction](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/manual/Interactions.html#:~:text=were%20too%20long\).-,Writing%20custom%20Interactions,-You%20can%20also) and use  it in the UI and code the same way you use built-in Interactions. To do so, add a class implementing the [IInputInteraction](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.0/api/UnityEngine.InputSystem.IInputInteraction.html) interface.

### Processor
- It will process your Input after it’s received. For example, it can Normalize the value of the input you receive if you only care about the direction of the input to move your character, and not the Value of it.
- Learn about the Deadzone processor type [here](https://youtu.be/17VqOh3_zxU?t=188).
- You can choose multiple Processors, and it depends on the type of your Action.