From b548344f5cfcc926ae0508af6ef90b798faf8da9 Mon Sep 17 00:00:00 2001 From: Ben Pitt Date: Fri, 7 Feb 2025 16:08:35 +0000 Subject: [PATCH 1/2] Start of responding to input reorg --- .../about-responding-to-input.md | 35 +++++++++ .../Documentation~/api-overview.md | 12 ++- .../Documentation~/control-types.md | 24 +++--- .../Documentation~/enable-actions.md | 16 ++-- .../Documentation~/polling-actions.md | 78 +++++++++++++++---- .../Documentation~/read-devices-directly.md | 2 + .../respond-to-input-at-runtime.md | 25 ------ .../Documentation~/respond-to-input.md | 3 +- 8 files changed, 133 insertions(+), 62 deletions(-) create mode 100644 Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/respond-to-input-at-runtime.md diff --git a/Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md b/Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md new file mode 100644 index 0000000000..223c80e346 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md @@ -0,0 +1,35 @@ +# About responding to input + +The Input System offers various ways to respond to input at runtime, from the recommended workflow using [actions](Actions.md) and [bindings](bindings.md), to more direct techniques such as reading device controls directly. + +## Recommended workflow + +Working with the Input System's [recommended workflow](Workflows.md) in your project involves two phases which you must approach in this order: + +1. Configure your project's input +2. Implement responses to input + +### Configure your project's input + +You must first [configure input for your project](setting-up-input.md) as [actions](Actions.md), before you can respond to those actions. + +In some situations you may find the [default project-wide actions](default-actions.md) cover all your needs, and you can go straight to implementing responses to input. In other cases you might need to [add or modify actions](configure-actions.md), or [start from scratch with your own set of actions](create-empty-action-asset.md). + +### Implement responses to input + +Once you have the actions set up, you're ready to implement responses to those actions. + +There are two main techniques you can use to respond to actions in your project. These are to either use **polling** or an **event-driven** approach. + +- The **polling** approach refers to the technique of repeatedly checking the current state of your actions. Typically you do this in the `Update()` method of a `MonoBehaviour` script. See [polling actions](polling-actions.md) for further information. + +- The **event-driven** approach involves creating your own methods in code that are automatically called when an action is performed. See [Set callbacks on actions](set-callbacks-on-actions.md) for further information. + +For most common scenarios, especially action games where the user's input has a continuous effect on an in-game character, **polling** is usually simpler and easier to implement. For other situations where input is less continuous and directed to different GameObjects in your scene, an event-driven approach might be more appropriate. + +## Other workflows + +The Input System also allows you to read device states directly, which bypasses many of the features such as actions and bindings. This is suitable for fast prototyping, or single fixed platform scenarios, but is a less flexible workflow because it bypasses some of the main Input System features. + +See [Read devices directly](read-devices-directly.md) for further information about this workflow. + diff --git a/Packages/com.unity.inputsystem/Documentation~/api-overview.md b/Packages/com.unity.inputsystem/Documentation~/api-overview.md index b1521e1721..4021a08812 100644 --- a/Packages/com.unity.inputsystem/Documentation~/api-overview.md +++ b/Packages/com.unity.inputsystem/Documentation~/api-overview.md @@ -6,10 +6,14 @@ 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](./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).| +|[`InputAction`](../api/UnityEngine.InputSystem.InputAction.html)|The class which represents an action. You can use a reference to an action to read the current value of the controls that it is bound to, or to trigger callbacks in response to input. This class corresponds to an entry in the **Actions**"** column of the [Input Actions editor](actions-editor.md).| +|[`InputActionMap`](../api/UnityEngine.InputSystem.InputActionMap.html)|The class which represents an [action map](create-edit-delete-action-maps.md). The API equivalent to an entry in the "Action Maps" column of the [Input Actions editor](actions-editor.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 [bindings](bindings.md).| -Each Action has a name ([`InputAction.name`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_name)), which must be unique within the Action Map that the Action belongs to, if any (see [`InputAction.actionMap`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_actionMap)). Each Action also has a unique ID ([`InputAction.id`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id)), which you can use to reference the Action. The ID remains the same even if you rename the Action. +## Actions + +Each action has a name ([`InputAction.name`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_name)), which must be unique within the Action Map that the Action belongs to, if any (see [`InputAction.actionMap`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_actionMap)). Each Action also has a unique ID ([`InputAction.id`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id)), which you can use to reference the Action. The ID remains the same even if you rename the Action. + +## Action maps Each Action Map has a name ([`InputActionMap.name`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_name)), which must also be unique with respect to the other Action Maps present, if any. Each Action Map also has a unique ID ([`InputActionMap.id`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_id)), which you can use to reference the Action Map. The ID remains the same even if you rename the Action Map. diff --git a/Packages/com.unity.inputsystem/Documentation~/control-types.md b/Packages/com.unity.inputsystem/Documentation~/control-types.md index 63f4dbc1ed..93ca6ddf23 100644 --- a/Packages/com.unity.inputsystem/Documentation~/control-types.md +++ b/Packages/com.unity.inputsystem/Documentation~/control-types.md @@ -2,18 +2,18 @@ The Input System provides the following types of controls: -|Control Type|Description|Example| -|------------|-----------|-------| -|[`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html)|A 1D floating-point axis.|[`Gamepad.leftStick.x`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html#UnityEngine_InputSystem_Controls_Vector2Control_x)| -|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|A button expressed as a floating-point value. Whether the button can have a value other than 0 or 1 depends on the underlying representation. For example, gamepad trigger buttons can have values other than 0 and 1, but gamepad face buttons generally can't.|[`Mouse.leftButton`](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_leftButton)| -|[`KeyControl`](../api/UnityEngine.InputSystem.Controls.KeyControl.html)|A specialized button that represents a key on a [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html). Keys have an associated [`keyCode`](../api/UnityEngine.InputSystem.Controls.KeyControl.html#UnityEngine_InputSystem_Controls_KeyControl_keyCode) and, unlike other types of Controls, change their display name in accordance to the currently active system-wide keyboard layout. See the [Keyboard](Keyboard.md) documentation for details.|[`Keyboard.aKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_aKey)| -|[`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html)|A 2D floating-point vector.|[`Pointer.position`](../api/UnityEngine.InputSystem.Pointer.html#UnityEngine_InputSystem_Pointer_position)| -|[`Vector3Control`](../api/UnityEngine.InputSystem.Controls.Vector3Control.html)|A 3D floating-point vector.|[`Accelerometer.acceleration`](../api/UnityEngine.InputSystem.Accelerometer.html#UnityEngine_InputSystem_Accelerometer_acceleration)| -|[`QuaternionControl`](../api/UnityEngine.InputSystem.Controls.QuaternionControl.html)|A 3D rotation.|[`AttitudeSensor.attitude`](../api/UnityEngine.InputSystem.AttitudeSensor.html#UnityEngine_InputSystem_AttitudeSensor_attitude)| -|[`IntegerControl`](../api/UnityEngine.InputSystem.Controls.IntegerControl.html)|An integer value.|[`Touchscreen.primaryTouch.touchId`](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId)| -|[`StickControl`](../api/UnityEngine.InputSystem.Controls.StickControl.html)|A 2D stick control like the thumbsticks on gamepads or the stick control of a joystick.|[`Gamepad.rightStick`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightStick)| -|[`DpadControl`](../api/UnityEngine.InputSystem.Controls.DpadControl.html)|A 4-way button control like the D-pad on gamepads or hatswitches on joysticks.|[`Gamepad.dpad`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_dpad)| -|[`TouchControl`](../api/UnityEngine.InputSystem.Controls.TouchControl.html)|A control that represents all the properties of a touch on a [touch screen](Touch.md).|[`Touchscreen.primaryTouch`](../api/UnityEngine.InputSystem.Touchscreen.html#UnityEngine_InputSystem_Touchscreen_primaryTouch)| +|Control Type|Value Type|Description|Example| +|-|-|-|-| +|[`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html)|`float`|A 1D floating-point axis.|[`Gamepad.leftStick.x`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html#UnityEngine_InputSystem_Controls_Vector2Control_x)| +|[`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html)|`float`|A button expressed as a floating-point value. Whether the button can have a value other than 0 or 1 depends on the underlying representation. For example, gamepad trigger buttons can have values other than 0 and 1, but gamepad face buttons generally can't.|[`Mouse.leftButton`](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_leftButton)| +|[`KeyControl`](../api/UnityEngine.InputSystem.Controls.KeyControl.html)|N/A|A specialized button that represents a key on a [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html). Keys have an associated [`keyCode`](../api/UnityEngine.InputSystem.Controls.KeyControl.html#UnityEngine_InputSystem_Controls_KeyControl_keyCode) and, unlike other types of Controls, change their display name in accordance to the currently active system-wide keyboard layout. See the [Keyboard](Keyboard.md) documentation for details.|[`Keyboard.aKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_aKey)| +|[`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html)|`Vector2`|A 2D floating-point vector.|[`Pointer.position`](../api/UnityEngine.InputSystem.Pointer.html#UnityEngine_InputSystem_Pointer_position)| +|[`Vector3Control`](../api/UnityEngine.InputSystem.Controls.Vector3Control.html)|`Vector3`|A 3D floating-point vector.|[`Accelerometer.acceleration`](../api/UnityEngine.InputSystem.Accelerometer.html#UnityEngine_InputSystem_Accelerometer_acceleration)| +|[`QuaternionControl`](../api/UnityEngine.InputSystem.Controls.QuaternionControl.html)|`Quaternion`|A 3D rotation.|[`AttitudeSensor.attitude`](../api/UnityEngine.InputSystem.AttitudeSensor.html#UnityEngine_InputSystem_AttitudeSensor_attitude)| +|[`IntegerControl`](../api/UnityEngine.InputSystem.Controls.IntegerControl.html)|`int`|An integer value.|[`Touchscreen.primaryTouch.touchId`](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId)| +|[`StickControl`](../api/UnityEngine.InputSystem.Controls.StickControl.html)|`Vector2`|A 2D stick control like the thumbsticks on gamepads or the stick control of a joystick.|[`Gamepad.rightStick`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_rightStick)| +|[`DpadControl`](../api/UnityEngine.InputSystem.Controls.DpadControl.html)|`Vector2`|A 4-way button control like the D-pad on gamepads or hatswitches on joysticks.|[`Gamepad.dpad`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_dpad)| +|[`TouchControl`](../api/UnityEngine.InputSystem.Controls.TouchControl.html)|`TouchState`|A control that represents all the properties of a touch on a [touch screen](Touch.md).|[`Touchscreen.primaryTouch`](../api/UnityEngine.InputSystem.Touchscreen.html#UnityEngine_InputSystem_Touchscreen_primaryTouch)| You can browse the set of all registered control layouts in the [input debugger](Debugging.md#debugging-layouts). diff --git a/Packages/com.unity.inputsystem/Documentation~/enable-actions.md b/Packages/com.unity.inputsystem/Documentation~/enable-actions.md index e3865b88b6..29b0154b5f 100644 --- a/Packages/com.unity.inputsystem/Documentation~/enable-actions.md +++ b/Packages/com.unity.inputsystem/Documentation~/enable-actions.md @@ -2,9 +2,13 @@ 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](./about-project-wide-actions.md), the actions it contains are enabled by default and ready to use. +## Project-wide actions -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. +If you are using the recommended [project-wide actions](./about-project-wide-actions.md) workflow, those actions are enabled automatically as your project starts. You do not need to enable them. + +## Other actions + +For actions defined elsewhere, such as in an action asset not assigned as project-wide, or defined your own code, those actions begin in a disabled state, and you must enable them before you can use them to respond to input. You can enable actions individually, or as a group by enabling the Action Map which contains them. @@ -16,11 +20,13 @@ lookAction.Enable(); gameplayActions.Enable(); ``` -When you enable an Action, the Input System resolves its bindings, unless it has done so already, or if the set of devices that the Action can use has not changed. For more details about this process, see the documentation on [binding resolution](ActionBindings.md#binding-resolution). +## Behaviour when enabled + +When an action is enabled, the Input System resolves its bindings, unless it has done so already, or if the set of devices that the action can use has not changed. For more details about this process, see the documentation on [binding resolution](binding-resolution.md). -You can't change certain aspects of the configuration, such Action Bindings, while an Action is enabled. To stop Actions or Action Maps from responding to input, call [`Disable`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_Disable). +You can't change certain aspects of the configuration, such as an action's bindings, while an action is enabled. To stop actions or action maps from responding to input, call [`Disable`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_Disable). -While enabled, an Action actively monitors the [Control(s)](Controls.md) it's bound to. If a bound Control changes state, the Action processes the change. If the Control's change represents an [Interaction](Interactions.md) change, the Action creates a response. All of this happens during the Input System update logic. Depending on the [update mode](Settings.md#update-mode) selected in the input settings, this happens once every frame, once every fixed update, or manually if updates are set to manual. +While enabled, the action actively monitors the [control(s)](controls.md) it is bound to. If a bound control changes state, the action processes the change. If the control's change represents an [interaction](interactions.md) change, the action creates a response. All of this happens during the Input System update logic. Depending on the [update mode](Settings.md#update-mode) selected in the input settings, this happens once every frame, once every fixed update, or manually if the update mode setting is set to manual. diff --git a/Packages/com.unity.inputsystem/Documentation~/polling-actions.md b/Packages/com.unity.inputsystem/Documentation~/polling-actions.md index 96f2c3a895..8b068a1757 100644 --- a/Packages/com.unity.inputsystem/Documentation~/polling-actions.md +++ b/Packages/com.unity.inputsystem/Documentation~/polling-actions.md @@ -1,6 +1,41 @@ -# Polling Actions +# Polling actions -You can poll the current value of an Action using [`InputAction.ReadValue<>()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_ReadValue__1): +Polling actions is one of the two main [ways to respond to actions](about-responding-to-input.md) using the recommended workflow. + +Polling refers to the act of repeatedly checking the status or value of an action. This is in contrast to using callbacks which are only triggered when an action is performed. + +The code required to poll an action depends on the [action type](action-type-reference.md) + +## Poll value-type actions + +To poll an action whose type is **Value** or **Pass-through**, use: + +- [`ReadValue<>()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_ReadValue__1) with the corresponding type that matches the action's [control type's](control-types.md) value. + +## Poll button-type actions + +To poll an action whose type is **Button**, use: + +- [`IsPressed()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame) +- [`WasPressedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame) +- [`WasReleasedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame) + + + +## Poll using interaction phases + +Actions have interaction phases which can be either `Waiting`, `Started`, `Performed` or `Canceled`. When the interaction phase changes depends on the action's [interaction type](built-in-interactions.md), if one is assigned, or the [default interaction](default-interactions.md) otherwise. You can poll an action's interaction phase using the following methods: + +- [`phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase) +- [`WasPerformedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame) +- [`WasCompletedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasCompletedThisFrame) + +## Examples + +### Polling value and button actions example +This example shows polling two actions in `Update`. + +The `Move` action is a value-type, and the `Jump` action is a button-type. ```CSharp using UnityEngine; @@ -8,34 +43,37 @@ using UnityEngine.InputSystem; public class Example : MonoBehaviour { + // These variables are to hold the Action references InputAction moveAction; + InputAction jumpAction; private void Start() { + // Find the references to the "Move" and "Jump" actions moveAction = InputSystem.actions.FindAction("Move"); + jumpAction = InputSystem.actions.FindAction("Jump"); } void Update() { + // Read the "Move" action value, which is a 2D vector + // and the "Jump" action state, which is a button + Vector2 moveValue = moveAction.ReadValue(); - // your code would then use moveValue to apply movement - // to your GameObject + // your movement code here + + if (jumpAction.IsPressed()) + { + // your jump code here + } } } ``` -Note that the value type has to correspond to the value type of the control that the value is being read from. - -There are two methods you can use to poll for `performed` [action callbacks](#action-callbacks) to determine whether an action was performed or stopped performing in the current frame. - -These methods differ from [`InputAction.WasPressedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame) and [`InputAction.WasReleasedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame) in that these depend directly on the [Interactions](Interactions.md) driving the action (including the [default Interaction](Interactions.md#default-interaction) if no specific interaction has been added to the action or binding). +### Polling interaction phase example -|Method|Description| -|------|-----------| -|[`InputAction.WasPerformedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame)|True if the [`InputAction.phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase) of the action has, at any point during the current frame, changed to [`Performed`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Performed).| -|[`InputAction.WasCompletedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasCompletedThisFrame)|True if the [`InputAction.phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase) of the action has, at any point during the current frame, changed away from [`Performed`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Performed) to any other phase. This can be useful for [Button](#button) actions or [Value](#value) actions with interactions like [Press](Interactions.md#press) or [Hold](Interactions.md#hold) when you want to know the frame the interaction stops being performed. For actions with the [default Interaction](Interactions.md#default-interaction), this method will always return false for [Value](#value) and [Pass-Through](#pass-through) actions (since the phase stays in [`Started`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Started) for Value actions and stays in [`Performed`](../api/UnityEngine.InputSystem.InputActionPhase.html#UnityEngine_InputSystem_InputActionPhase_Performed) for Pass-Through).| -This example uses the Interact action from the [default actions](./about-project-wide-actions.md#the-default-actions), which has a [Hold](Interactions.md#hold) interaction to make it perform only after the bound control is held for a period of time (for example, 0.4 seconds): +This example uses the Interact action from the [default actions](default-actions.md), which has a [Hold](Interactions.md#hold) interaction to make it perform only after the bound control is held for a period of time (for example, 0.4s): ```CSharp using UnityEngine; @@ -65,6 +103,18 @@ public class Example : MonoBehaviour } ``` + + + + + +Note that the value type has to correspond to the value type of the control that the value is being read from. + +There are two methods you can use to poll for `performed` [action callbacks](#action-callbacks) to determine whether an action was performed or stopped performing in the current frame. + + + + Finally, there are three methods you can use to poll for button presses and releases: |Method|Description| diff --git a/Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md b/Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md new file mode 100644 index 0000000000..e1198c2449 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md @@ -0,0 +1,2 @@ +# Read devices directly + diff --git a/Packages/com.unity.inputsystem/Documentation~/respond-to-input-at-runtime.md b/Packages/com.unity.inputsystem/Documentation~/respond-to-input-at-runtime.md deleted file mode 100644 index b4f6da2c5f..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/respond-to-input-at-runtime.md +++ /dev/null @@ -1,25 +0,0 @@ -# Respond to input at runtime - -There are two main techniques you can use to respond to Actions in your project. These are to either use **polling** or an **event-driven** approach. - -- The **Polling** approach refers to the technique of repeatedly checking the current state of the Actions you are interested in. Typically you would do this in the `Update()` method of a `MonoBehaviour` script. -- The **Event-driven** approach involves creating your own methods in code that are automatically called when an action is performed. - -For most common scenarios, especially action games where the user's input should have a continuous effect on an in-game character, **Polling** is usually simpler and easier to implement. - -For other situations where input is less frequent and directed to various different GameObjects in your scene, an event-driven approach might be more suitable. - - ----- (TODO the below info was part of "responding to actions" but is most likely duplicate info found on other pages. need to check before removing.) - - - -### Debugging Actions - -To see currently enabled Actions and their bound Controls, use the [Input Debugger](Debugging.md#debugging-actions). - -You can also use the [`InputActionVisualizer`](Debugging.md#inputactionvisualizer) component from the Visualizers sample to get an on-screen visualization of an Action's value and Interaction state in real-time. - -### Using Actions with multiple players - -You can use the same Action definitions for multiple local players (for example, in a local co-op game). For more information, see documentation on the [Player Input Manager](PlayerInputManager.md) component. diff --git a/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md b/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md index cfeb7428ba..f4164f5532 100644 --- a/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md @@ -4,12 +4,11 @@ Learn how to implement responses to the input that you have configured in your p | **Topic** | **Description** | | :------------------------------ | :------------------------------- | -| **[Respond To Input At Runtime](respond-to-input-at-runtime.md)** | Summary | +| **[Respond To Input At Runtime](about-responding-to-input.md)** | Summary | | **[API Overview](api-overview.md)** | Summary | | **[Enabling actions](enable-actions.md)** | Summary | | **[Polling actions](polling-actions.md)** | Summary | | **[Set callbacks on actions](set-callbacks-on-actions.md)** | Summary | -| **[Trace actions](trace-actions.md)** | Summary | | **[Player Input Component](player-input-component.md)** | Summary | | **[Player Input Manager Component](player-input-manager-component.md)** | Summary | From ac0431daca2b00622607800126e375af74f66a86 Mon Sep 17 00:00:00 2001 From: Ben Pitt Date: Thu, 13 Feb 2025 12:46:48 +0000 Subject: [PATCH 2/2] Continued work on all pages in this section --- .../Documentation~/TableOfContents.md | 8 ++- .../about-responding-to-input.md | 16 ++--- .../Documentation~/api-overview.md | 20 +++++- .../Documentation~/polling-actions.md | 35 +++------ .../Documentation~/read-devices-directly.md | 72 +++++++++++++++++++ .../Documentation~/respond-to-input.md | 5 +- .../set-callbacks-on-actions.md | 49 ++++++------- .../Documentation~/using-actions-workflow.md | 4 +- 8 files changed, 145 insertions(+), 64 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index 07b6ef53be..8c804dd2ab 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -62,11 +62,17 @@ * [The actions editor window](actions-editor.md) * [Devices](devices.md) * [Get information about devices](get-information-about-devices.md) +* [Responding to input](respond-to-input.md) + * [About responding to input](about-responding-to-input.md) + * [Enable actions](enable-actions.md) + * [Polling actions](polling-actions.md) + * [Set callbacks on actions](set-callbacks-on-actions.md) + * [Read devices directly](read-devices-directly.md) + * [API Overview](api-overview.md) * [Using the Input System]() * [Project-Wide Actions](about-project-wide-actions.md) * [Configuring Input](ActionsEditor.md) * [Actions](actions.md) - * [Enabling Actions](enable-actions.md) * [Responding to Actions](RespondingToActions.md) * [Input Action Assets](ActionAssets.md) * [Input Bindings](ActionBindings.md) diff --git a/Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md b/Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md index 223c80e346..8c368465b1 100644 --- a/Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/about-responding-to-input.md @@ -6,18 +6,18 @@ The Input System offers various ways to respond to input at runtime, from the re Working with the Input System's [recommended workflow](Workflows.md) in your project involves two phases which you must approach in this order: -1. Configure your project's input -2. Implement responses to input +1. Configure your project's actions. +2. Implement responses to actions. -### Configure your project's input +### Configure your project's actions You must first [configure input for your project](setting-up-input.md) as [actions](Actions.md), before you can respond to those actions. -In some situations you may find the [default project-wide actions](default-actions.md) cover all your needs, and you can go straight to implementing responses to input. In other cases you might need to [add or modify actions](configure-actions.md), or [start from scratch with your own set of actions](create-empty-action-asset.md). +In some situations you might find the configuration in the [default project-wide actions](default-actions.md) covers all your needs, and you can go straight to implementing responses to input. In other cases you might want to start with the default configuration and [add or modify actions](configure-actions.md), or you can [start with an empty configuration and define your own](create-empty-action-asset.md). -### Implement responses to input +### Implement responses to actions -Once you have the actions set up, you're ready to implement responses to those actions. +Once you have your actions set up, you can implement responses to those actions. There are two main techniques you can use to respond to actions in your project. These are to either use **polling** or an **event-driven** approach. @@ -25,11 +25,11 @@ There are two main techniques you can use to respond to actions in your project. - The **event-driven** approach involves creating your own methods in code that are automatically called when an action is performed. See [Set callbacks on actions](set-callbacks-on-actions.md) for further information. -For most common scenarios, especially action games where the user's input has a continuous effect on an in-game character, **polling** is usually simpler and easier to implement. For other situations where input is less continuous and directed to different GameObjects in your scene, an event-driven approach might be more appropriate. +For most common scenarios, especially action games where the user's input has a continuous centralized effect on an in-game character, **polling** is usually simpler and easier to implement. For other situations where input is less continuous, or directed to many different areas in your scene, an event-driven approach might be more appropriate. ## Other workflows -The Input System also allows you to read device states directly, which bypasses many of the features such as actions and bindings. This is suitable for fast prototyping, or single fixed platform scenarios, but is a less flexible workflow because it bypasses some of the main Input System features. +The Input System also allows you to read device states directly, which bypasses many of the features such as actions and bindings. This workflow is suitable for fast prototyping, or single fixed platform scenarios, but is a less flexible workflow because it bypasses some useful Input System features. See [Read devices directly](read-devices-directly.md) for further information about this workflow. diff --git a/Packages/com.unity.inputsystem/Documentation~/api-overview.md b/Packages/com.unity.inputsystem/Documentation~/api-overview.md index 4021a08812..9b51ed39bc 100644 --- a/Packages/com.unity.inputsystem/Documentation~/api-overview.md +++ b/Packages/com.unity.inputsystem/Documentation~/api-overview.md @@ -1,7 +1,16 @@ +# API Overview -## API Overview +When scripting with Actions in the Input System, there are number of important API you can use, listed here: -When scripting with Actions in the Input System, there are number of important API you can use, which are described here: +## Namespace + +The Input System's API is contained in the `UnityEngine.InputSystem` namespace. To use it, include the namespace as follows: + +``` +using UnityEngine.InputSystem; +``` + +## Important API |API name|Description| |-----|-----------| @@ -12,8 +21,15 @@ When scripting with Actions in the Input System, there are number of important A ## Actions +The [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) class represents an action in the Input System. These are the same actions that you [create in the actions editor](Actions.md). + +With a reference to an action, you can then read values and state changes using eeither the [polling](polling-actions.md) or [callbacks](set-callbacks-on-actions.md) workflow. + Each action has a name ([`InputAction.name`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_name)), which must be unique within the Action Map that the Action belongs to, if any (see [`InputAction.actionMap`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_actionMap)). Each Action also has a unique ID ([`InputAction.id`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_id)), which you can use to reference the Action. The ID remains the same even if you rename the Action. ## Action maps Each Action Map has a name ([`InputActionMap.name`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_name)), which must also be unique with respect to the other Action Maps present, if any. Each Action Map also has a unique ID ([`InputActionMap.id`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_id)), which you can use to reference the Action Map. The ID remains the same even if you rename the Action Map. + +With a reference to an action map, you can then read all the [`actions`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_actions) which belong to that map. + diff --git a/Packages/com.unity.inputsystem/Documentation~/polling-actions.md b/Packages/com.unity.inputsystem/Documentation~/polling-actions.md index 2c8b85fd5f..10b233f974 100644 --- a/Packages/com.unity.inputsystem/Documentation~/polling-actions.md +++ b/Packages/com.unity.inputsystem/Documentation~/polling-actions.md @@ -4,13 +4,15 @@ Polling actions is one of the two main [ways to respond to actions](about-respon Polling refers to the act of repeatedly checking the status or value of an action. This is in contrast to using callbacks which are only triggered when an action is performed. -The code required to poll an action depends on the [action type](action-type-reference.md) +The code required to poll an action depends on the [action type](action-type-reference.md), and whether you want to read the action's values or use the [interaction state](Interactions.md) instead. ## Poll value-type actions To poll an action whose type is **Value** or **Pass-through**, use: -- [`ReadValue<>()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_ReadValue__1) with the corresponding type that matches the action's [control type's](control-types.md) value. +- [`ReadValue<>()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_ReadValue__1) + +You must use the corresponding type that matches the action's [control type's](control-types.md) value. For example, `ReadValue()` for a 2D axis. ## Poll button-type actions @@ -18,13 +20,13 @@ To poll an action whose type is **Button**, use: - [`IsPressed()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame) - [`WasPressedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame) -- [`WasReleasedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame) - +- [`WasReleasedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame) +Buttons have no applicable value other than whether they are pressed or released. ## Poll using interaction phases -Actions have interaction phases which can be either `Waiting`, `Started`, `Performed` or `Canceled`. When the interaction phase changes depends on the action's [interaction type](built-in-interactions.md), if one is assigned, or the [default interaction](default-interactions.md) otherwise. You can poll an action's interaction phase using the following methods: +Actions have [interaction phases](introduction-interactions.md) which can be either `Waiting`, `Started`, `Performed` or `Canceled`. The interaction phase changes depending on the action's [interaction type](built-in-interactions.md), if one is assigned, or the [default interaction](default-interactions.md) otherwise. You can poll an action's interaction phase using the following methods: - [`phase`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_phase) - [`WasPerformedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPerformedThisFrame) @@ -32,7 +34,7 @@ Actions have interaction phases which can be either `Waiting`, `Started`, `Perfo ## Examples -### Polling value and button actions example +### Polling actions example with a 2D axis and a button action This example shows polling two actions in `Update`. The `Move` action is a value-type, and the `Jump` action is a button-type. @@ -70,7 +72,7 @@ public class Example : MonoBehaviour } ``` -### Polling interaction phase example +### Polling actions example using interaction phase This example uses the Interact action from the [default actions](default-actions.md), which has a [Hold](Interactions.md#hold) interaction to make it perform only after the bound control is held for a period of time (for example, 0.4s): @@ -104,24 +106,7 @@ public class Example : MonoBehaviour ``` - - - - -Note that the value type has to correspond to the value type of the control that the value is being read from. - -There are two methods you can use to poll for `performed` [action callbacks](#action-callbacks) to determine whether an action was performed or stopped performing in the current frame. - - - - -Finally, there are three methods you can use to poll for button presses and releases: - -|Method|Description| -|------|-----------| -|[`InputAction.IsPressed()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_IsPressed)|True if the level of [actuation](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude) on the action has crossed the [press point](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint) and did not yet fall to or below the [release threshold](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_buttonReleaseThreshold).| -|[`InputAction.WasPressedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame)|True if the level of [actuation](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude) on the action has, at any point during the current frame, reached or gone above the [press point](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint).| -|[`InputAction.WasReleasedThisFrame()`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame)|True if the level of [actuation](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_EvaluateMagnitude) on the action has, at any point during the current frame, gone from being at or above the [press point](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_defaultButtonPressPoint) to at or below the [release threshold](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_buttonReleaseThreshold).| +### Polling button actions example This example uses three actions called Shield, Teleport, and Submit (which are not included in the [default actions](./about-project-wide-actions.md#the-default-actions)): diff --git a/Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md b/Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md index e1198c2449..243e399fa4 100644 --- a/Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md +++ b/Packages/com.unity.inputsystem/Documentation~/read-devices-directly.md @@ -1,2 +1,74 @@ # Read devices directly +The input system allows you to directly read the state of a device's controls, which can be useful in some situations. This isn't generally the recommended workflow because it bypasses many of the Input Systems useful features, such as [actions](Actions.md) and [bindings](bindings.md). + +To read a device's controls directly you must: + +1. Get a reference to a device +2. Identify the control on the device you want to read +3. Read the value from the control + +## Get a reference to a device + +To get a reference to a device, you can either: + +- Get the currently connected device of a given type, or +- Check through all currently connected devices. + +### Get the current device of a specific type + +You can get references to any supported device currently connected by using one of the [InputDevice classes](../api/UnityEngine.InputSystem.InputDevice.html) and using the `.current` property to get the currently active device of that type. For example, [`Gamepad.current`](../api/UnityEngine.InputSystem.Gamepad.html#UnityEngine_InputSystem_Gamepad_current) returns the most recently active connected gamepad. + +You can browse the available device types from the [InputDevice classes API documentation](../api/UnityEngine.InputSystem.InputDevice.html). +- Some types listed are usable directly, such as `Gamepad` or `Joystick`. +- Some are abstract parent classes that have usable child classes. For example, `Pointer` is not directly usable, but has usable child classes of `Mouse`, `Pen`, and `Touch`. +- Some usable types also have more specialized child classes. For example `Gamepad` also has child classes such as `AndroidGamepad` as well as other Gampad types. + +### Check through all connected devices + +The `InputSystem.devices` property provides an array of all currently connected devices. You can [iterate through this array to get the reference to each connected device](query-gamepads.md#discover-all-connected-devices). + + +## Identify the control property on the device + +Each type of device has its own configuration of [controls](controls.md), defined by its [layout](Layouts.md). Each control has an API property that allows you to access the value of that control. + +For example, all Gamepads have a `leftStick` and `rightStick` property, as well as a number of other properties which correspond to each of its controls. + +You can browse the API documentation for any given device type to discover the control properties to use. For example, the [Gamepad class properties API documentation](../api/UnityEngine.InputSystem.Gamepad.html#properties). + +## Read the value from the control + +Once you have the reference to the device, and you know the control property to read, you can read the value from your code using the API which matches the [control's type](control-types-reference.md). + +- For value type controls, use `ReadValue`, which returns a value of the control's type. +- For button type controls, use `isPressed`, `wasPressedThisFrame` or `wasReleasedThisFrame`. + +For example: + +```CSharp +using UnityEngine; +using UnityEngine.InputSystem; + +public class MyPlayerScript : MonoBehaviour +{ + void Update() + { + var gamepad = Gamepad.current; + + // check there is a Gamepad connected + if (gamepad != null) + { + if (gamepad.rightTrigger.wasPressedThisFrame) + { + // 'Use' code here + } + + Vector2 move = gamepad.leftStick.ReadValue(); + { + // 'Move' code here + } + } + } +} +``` \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md b/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md index f4164f5532..97cd0aeb84 100644 --- a/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/respond-to-input.md @@ -4,11 +4,12 @@ Learn how to implement responses to the input that you have configured in your p | **Topic** | **Description** | | :------------------------------ | :------------------------------- | -| **[Respond To Input At Runtime](about-responding-to-input.md)** | Summary | -| **[API Overview](api-overview.md)** | Summary | +| **[About responding to input](about-responding-to-input.md)** | An introduction to the ways you can implement responses to input in your project. | | **[Enabling actions](enable-actions.md)** | Summary | | **[Polling actions](polling-actions.md)** | Summary | | **[Set callbacks on actions](set-callbacks-on-actions.md)** | Summary | +| **[Read devices directly](read-devices-directly.md))** | Summary | +| **[API Overview](api-overview.md)** | Summary | | **[Player Input Component](player-input-component.md)** | Summary | | **[Player Input Manager Component](player-input-manager-component.md)** | Summary | diff --git a/Packages/com.unity.inputsystem/Documentation~/set-callbacks-on-actions.md b/Packages/com.unity.inputsystem/Documentation~/set-callbacks-on-actions.md index a15b811c4b..e47f8d8ab7 100644 --- a/Packages/com.unity.inputsystem/Documentation~/set-callbacks-on-actions.md +++ b/Packages/com.unity.inputsystem/Documentation~/set-callbacks-on-actions.md @@ -1,24 +1,26 @@ -## Responding to Actions using callbacks +# Set callbacks on actions + +Setting callbacks on actions is one of the two main [ways to respond to actions](about-responding-to-input.md) using the recommended workflow. When you set up callbacks for your Action, the Action informs your code that a certain type of input has occurred, and your code can then respond accordingly. -There are several ways to do this: +The Input System offers the following ways to set up input callbacks: + +- The [PlayerInput component](using-playerinput-workflow.md). +- [Action callbacks](#action-callbacks). +- [Action map callbacks](#action-map-callbacks) +- The global [On Action Change callback](#global-input-callback). -1. You can use the [PlayerInput component](using-playerinput-workflow.md) to set up callbacks in the inspector. -1. Each Action has a [`started`, `performed`, and `canceled` callback](#action-callbacks). -1. Each Action Map has an [`actionTriggered` callback](#inputactionmapactiontriggered-callback). -1. The Input System has a global [`InputSystem.onActionChange` callback](#inputsystemonactionchange-callback). -2. [`InputActionTrace`](#inputactiontrace) can record changes happening on Actions. -#### The PlayerInput component +You can also use [`InputActionTrace`](trace-actions.md) to record all changes happening on actions, which is useful for [debugging](Debugging.md). -The PlayerInput component is the simplest way to set up Action callbacks. It provides an interface in the inspector that allows you set up callbacks directly to your methods without requiring intermediate code. [Read more about the PlayerInput component](using-playerinput-workflow.md). +## The Player Input component -Alternatively, you can implement callbacks entirely from your own code using the following workflow: +With the Player Input component, you can set up callbacks using an interface in the inspector without requiring intermediate code. Refer to [the PlayerInput component](using-playerinput-workflow.md) for further information. -#### Action callbacks +## Action callbacks Every Action has a set of distinct phases it can go through in response to receiving input. @@ -35,29 +37,28 @@ You can read the current phase of an action using [`InputAction.phase`](../api/U The `Started`, `Performed`, and `Canceled` phases each have a callback associated with them: ```CSharp - var action = new InputAction(); +jumpAction = InputSystem.actions.FindAction("Jump"); - action.started += context => /* Action was started */; - action.performed += context => /* Action was performed */; - action.canceled += context => /* Action was canceled */; +jumpAction.started += context => /* Action was started */; +jumpAction.performed += context => /* Action was performed */; +jumpAction.canceled += context => /* Action was canceled */; ``` Each callback receives an [`InputAction.CallbackContext`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html) 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`](../api/UnityEngine.InputSystem.InputAction.CallbackContext.html#UnityEngine_InputSystem_InputAction_CallbackContext_ReadValue__1)). ->__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. +The contents of the callback context structure are only valid during the callback. In particular, it's not 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](Interactions.md) present on the respective Bindings. If the Bindings have no Interactions that apply to them, the [default Interaction](Interactions.md#default-interaction) applies. +When and how the callbacks are triggered depends on the [interactions](Interactions.md) present on the respective bindings. If the bindings have no interactions that apply to them, the [default interaction](default-interactions.md) applies. -##### `InputActionMap.actionTriggered` callback +## Action map callbacks -Instead of listening to individual actions, you can listen on an entire Action Map for state changes on any of the Actions in the Action Map. +Instead of listening to individual actions, you can listen to an entire action map for state changes on any action it contains. ```CSharp -var actionMap = new InputActionMap(); -actionMap.AddAction("action1", "/buttonSouth"); -actionMap.AddAction("action2", "/buttonNorth"); +playerActionMap = InputSystem.actions.FindActionMap("Player"); + -actionMap.actionTriggered += +playerActionMap.actionTriggered += context => { ... }; ``` @@ -65,7 +66,7 @@ The argument received is the same `InputAction.CallbackContext` structure that y >__Note__: The Input System calls `InputActionMap.actionTriggered` for all three of the individual callbacks on Actions. That is, you get `started`, `performed`, and `canceled` all on a single callback. -##### `InputSystem.onActionChange` callback +## Global input callback Similar to `InputSystem.onDeviceChange`, your app can listen for any action-related change globally. diff --git a/Packages/com.unity.inputsystem/Documentation~/using-actions-workflow.md b/Packages/com.unity.inputsystem/Documentation~/using-actions-workflow.md index 51b4d08cd6..1922481adf 100644 --- a/Packages/com.unity.inputsystem/Documentation~/using-actions-workflow.md +++ b/Packages/com.unity.inputsystem/Documentation~/using-actions-workflow.md @@ -34,7 +34,7 @@ This means, in many cases, you can start scripting with the Input System without There are various ways to access your actions from code. One of the simplest ways is to use the `FindAction` method. -`FindAction` allows you to search for an action by name from within the set of configured acations, and returns a reference which you can then either read the value directly (also called "polling"), or you can attach callback methods that are called 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). +`FindAction` allows you to search for an action by name from within the set of configured acations, and returns a reference which you can then either read the value directly (known as [polling](polling-actions.md)), or you can attach callback methods that are called the action is performed. The workflow described on this page focuses only on reading the action values. Refer to [polling actions](polling-actions.md) and [setting callbacks on actions](set-callbacks-on-actions.md) for further information. > __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 may be a familiar process. @@ -97,7 +97,7 @@ 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 refeferences in the example above are found during the Start() functionm, 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](about-project-wide-actions.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 wish to access. +> **Note:** The [InputSystem.actions](../api/UnityEngine.InputSystem.InputSystem.html) API refers specifically to the Action Asset assigned as the [project-wide actions](about-project-wide-actions.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 wish to access. ## Pros and Cons