|
| 1 | +# Using The Unity Axis Action |
| 2 | + |
| 3 | +> * Level: Beginner |
| 4 | +> |
| 5 | +> * Reading Time: 10 minutes |
| 6 | +> |
| 7 | +> * Checked with: Unity 2018.3.14f1 |
| 8 | +
|
| 9 | +## Introduction |
| 10 | + |
| 11 | +Unity Input Manager Axis Actions tie into the [Unity Input Manager] and emit events when a defined input axis changes value. There are two kinds of Unity Axis Action: |
| 12 | + |
| 13 | +* UnityInputManager.1DAxisAction: listens for changes on a single axis and emits a `float` value for the axis changes. |
| 14 | +* UnityInputManager.2DAxisAction: listens for changes on a two axes and emits a `Vector2` value combining both axis changes. |
| 15 | + |
| 16 | +A Unity Axis Action is derived from a [Zinnia] Action and therefore can be injected into any component that accepts a Zinnia Action. |
| 17 | + |
| 18 | +The `Tilia.Input.UnityInputManager` package comes with a prefab Action that wraps the required components to make using a `UnityInputManager.1DAxisAction` much easier. |
| 19 | + |
| 20 | +## Prerequisites |
| 21 | + |
| 22 | +* [Install the Tilia.Input.UnityInputManager] package dependency in to your [Unity] project. |
| 23 | +* Create the [Tilia Input Axis Definitions] in your Unity project. |
| 24 | + |
| 25 | +### Step 1 |
| 26 | + |
| 27 | +Create a new `Sphere` Unity 3D Object by selecting `Main Menu -> GameObject -> 3D Object -> Sphere`. |
| 28 | + |
| 29 | +We will utilize a 1D axis action to control the position of this sphere in the scene. |
| 30 | + |
| 31 | +### Step 2 |
| 32 | + |
| 33 | +Expand the `Tilia Input UnityInputManager` Package directory in the Unity Project window and select then `Packages -> Tilia Input UnityInputManager -> Runtime -> Prefabs -> Actions` directory then drag and drop the `Input.UnityInputManager.1DAxisAction` prefab into the Hierarchy window. |
| 34 | + |
| 35 | +> Be sure to use the `Input.UnityInputManager.1DAxisAction` prefab and not just add the `Unity Input Manager Axis 1D Action` component to a GameObject as the component needs linking to a `MomentProcessor` to function. |
| 36 | +
|
| 37 | + |
| 38 | + |
| 39 | +### Step 3 |
| 40 | + |
| 41 | +We need to define the axis to listen to on the `Unity Input Manager Axis 1D Action` component found within the `Input.UnityInputManager.1DAxisAction` prefab. |
| 42 | + |
| 43 | +There are many different supported axes depending on the input peripheral being used and this package creates an additional 18 axis definitions named `Tilia.Input.UnityInputManager_AxisX` (where X is the number of the axis ranging from 3 to 20 e.g. `Tilia.Input.UnityInputManager_Axis3`). |
| 44 | + |
| 45 | +The Unity software also has 2 default axis values called `Horizontal` and `Vertical` which map to the arrows on the keyboard and the standard joystick movement of an input peripheral. |
| 46 | + |
| 47 | +Select the `Input.UnityInputManager.1DAxisAction` GameObject in the Hierarchy window and update the `Axis Name` parameter on the `Unity Input Manager Axis 1D Action` component to listen changes on the specified axis, in this case type `Horizontal` to listen for changes on the default horizontal axis definition within the Unity Input Manager definitions. |
| 48 | + |
| 49 | + |
| 50 | + |
| 51 | +### Step 4 |
| 52 | + |
| 53 | +We'll need to create a small script that allows us to change the position of our `Sphere` GameObject to test our newly created `1D Axis Action`. |
| 54 | + |
| 55 | +Create a new `Script` by selecting `Main Menu -> Assets -> Create -> C# Script` in the Unity software and name it `PositionUpdater`. |
| 56 | + |
| 57 | +Copy and paste the below code into the newly created `PositionUpdater` script: |
| 58 | + |
| 59 | +``` |
| 60 | +using UnityEngine; |
| 61 | +
|
| 62 | +public class PositionUpdater : MonoBehaviour |
| 63 | +{ |
| 64 | + public void SetHorizontalPosition(float newPosition) |
| 65 | + { |
| 66 | + transform.position = Vector3.right * newPosition; |
| 67 | + } |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +This simply script has a single method called `SetHorizontalPosition` which will take a `float` value that sets the position of the `Transform` that the component is on in relation to the left/right axis of the GameObject. |
| 72 | + |
| 73 | +> The `Vector3.right * newPosition` calculation is basically creating a new Vector3 position value based on the world right direction multiplied by the new position value provided. So if `newPosition` was `0` then `Vector3.right` which is a literal of `(0, 0, 1)` would be `(0, 0, 1) * 0 = (0, 0, 0)` and this would set the GameObject position to a world space of `(0, 0, 0)`. If we passed in a `newPosition` of `1` then the GameObject position will be calculated as `(0, 0, 1)`. |
| 74 | +
|
| 75 | +Add the `PositionUpdater` scrip to the `Sphere` GameObject. |
| 76 | + |
| 77 | +### Step 5 |
| 78 | + |
| 79 | +Now to set up the `Unity Input Manager Axis 1D Action` component to update the position of the `Sphere` GameObject when the horizontal axis changes (e.g. when we press the left/right arrow keys on the keyboard or move the left thumbstick on an Xbox controller). |
| 80 | + |
| 81 | +Click the `+` symbol in the bottom right corner of the `Value Changed` event parameter in the `Unity Input Manager Axis 1D Action` component and then drag and drop the `Sphere` GameObject into the box that appears and displays `None (Object)`. |
| 82 | + |
| 83 | +Select a `Function` to perform when the `Value Changed` event is emitted. For this example, select `PositionUpdater -> SetHorizontalPosition` (be sure to select `Dynamic float - SetHorizontalPosition` for this example). |
| 84 | + |
| 85 | + |
| 86 | + |
| 87 | +### Done |
| 88 | + |
| 89 | +Play the Unity scene and press the left/right arrow keys on the keyboard and the `Sphere` GameObject will snap to a new position according to the key being pressed. Alternatively, use an Xbox Controller and move the left thumbstick left and right to see the `Sphere` match the position of where the left thumbstick is being pushed to. |
| 90 | + |
| 91 | +This is because when the axis is not being touched at all, the axis value will be `0`. When the axis is fully pushed to the right, the axis value will be `1`. When the axis is fully pushed to the left, the axis value will be `-1`. The value of the axis can be anything between `-1` and `1` depending on the amount of pressure applied to the input peripheral. This axis value is then being passed to control the `X` position of the GameObject in world space. |
| 92 | + |
| 93 | +[Unity Input Manager]: https://docs.unity3d.com/Manual/class-InputManager.html |
| 94 | +[Zinnia]: https://github.com/ExtendRealityLtd/Zinnia.Unity |
| 95 | +[Install the Tilia.Input.UnityInputManager]: ../Installation/README.md |
| 96 | +[Unity]: https://unity3d.com/ |
| 97 | +[Tilia Input Axis Definitions]: ../Installation/README.md#step-4-creating-the-required-unity-input-manager-axis-definitions |
0 commit comments