diff --git a/Packages/com.unity.inputsystem/Documentation~/ActionAssets.md b/Packages/com.unity.inputsystem/Documentation~/ActionAssets.md deleted file mode 100644 index def2c2e5e5..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/ActionAssets.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -uid: input-system-action-assets ---- -# Input Action Assets - -- [Creating Input Action Assets](#creating-input-action-assets) -- [Editing Input Action Assets](#editing-input-action-assets) -- [Using Input Action Assets](#using-input-action-assets) -- [Type-safe C# API Generation](#type-safe-c-api-generation) - -An Input Action Asset is an Asset which contains a set of [Input Actions](Actions.md) definitions and their associated [Bindings](ActionBindings.md) and [Control Schemes](ActionBindings.md#control-schemes). 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. It is usually simpler to configure your project-wide action definition in the Project Settings window. - - -## Creating Input Action Assets - -To create an Asset that contains [Input Actions](Actions.md) in Unity, right-click in the __Project__ window or go to __Assets > Create > Input Actions__ from Unity's main menu. - -## Editing Input Action Assets - -To bring up the Action editor, double-click an `.inputactions` Asset in the Project Browser, or select the __Edit Asset__ button in the Inspector for that Asset. You can have more than one editor window open at the same time, but not for the same Asset. - -The Actions Editor which opens is identical to the [Actions Editor in the Project Settings window](ActionsEditor.md). - - -## Using Input Action Assets - - -## Type-safe C# API Generation - -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. - -### Auto-generating script code for Actions - -One of the most convenient ways to work with `.inputactions` Assets in scripts is to automatically generate a C# wrapper class for them. This removes the need to manually look up Actions and Action Maps using their names, and also provides an easier way to set up callbacks. - -To enable this option, tick the __Generate C# Class__ checkbox in the importer properties in the Inspector of the `.inputactions` Asset, then select __Apply__. - -![MyPlayerControls Importer Settings](Images/FireActionInputAssetInspector.png) - -You can optionally choose a path name, class name, and namespace for the generated script, or keep the default values. - -This generates a C# script that simplifies working with the Asset. - -```CSharp -using UnityEngine; -using UnityEngine.InputSystem; - -// IGameplayActions is an interface generated from the "gameplay" action map -// we added (note that if you called the action map differently, the name of -// the interface will be different). This was triggered by the "Generate Interfaces" -// checkbox. -public class MyPlayerScript : MonoBehaviour, IGameplayActions -{ - // MyPlayerControls is the C# class that Unity generated. - // It encapsulates the data from the .inputactions asset we created - // and automatically looks up all the maps and actions for us. - MyPlayerControls controls; - - public void OnEnable() - { - if (controls == null) - { - controls = new MyPlayerControls(); - // Tell the "gameplay" action map that we want to get told about - // when actions get triggered. - controls.gameplay.SetCallbacks(this); - } - controls.gameplay.Enable(); - } - - public void OnDisable() - { - controls.gameplay.Disable(); - } - - public void OnUse(InputAction.CallbackContext context) - { - // 'Use' code here. - } - - public void OnMove(InputAction.CallbackContext context) - { - // 'Move' code here. - } - -} -``` - ->__Note__: To regenerate the .cs file, right-click the .inputactions asset in the Project Browser and choose "Reimport". - -### Using Action Assets with `PlayerInput` - -The [Player Input](PlayerInput.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 Default Actions Asset - -An asset called `DefaultInputActions.inputactions` containing a default setup of Actions comes with the Input System Package. You can reference this asset directly in your projects like any other Unity asset. However, the asset is also available in code form through the [`DefaultInputActions`](../api/UnityEngine.InputSystem.DefaultInputActions.html) class. - -```CSharp -void Start() -{ - // Create an instance of the default actions. - var actions = new DefaultInputActions(); - actions.Player.Look.performed += OnLook; - actions.Player.Move.performed += OnMove; - actions.Enable(); -} -``` - -> __Note:__ This default actions asset is older than, and entirely separate from the [default project-wide actions](ProjectWideActions.md). It is a legacy asset that remains included in the package for backward compatibility. diff --git a/Packages/com.unity.inputsystem/Documentation~/Actions.md b/Packages/com.unity.inputsystem/Documentation~/Actions.md index 780d0e2ddc..f69239fde7 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Actions.md +++ b/Packages/com.unity.inputsystem/Documentation~/Actions.md @@ -3,156 +3,23 @@ uid: input-system-actions --- # Actions -**Actions** are an important concept in the Input System. They allow you to separate the purpose of an input from the device controls which perform that input. Actions allow you to associate the purpose and device controls together in a flexible way. +**Actions** allow you to separate the purpose of an input from the device controls which perform that input, and associate the purpose and device controls together in a flexible way. -For example, the purpose of an input in a game might be to make the player's character move around. The device control associated with that action might be the motion of the left gamepad stick. +For example, the purpose of an input in a game might be to make the player's character move. The device control associated with that action might be the left gamepad stick. -The association between an Action and the device controls which perform that input is a **binding**, and you can set up bindings in the [Input Actions editor](ActionsEditor.md). When you use Actions in your code, you do not need to refer to specific devices because the binding defines which device's controls are used to perform the action. +The association between an Action and the device controls which perform that input is a **binding**, and you can set up bindings in the [Input Actions editor](actions-editor.md). When you use Actions in your code, you do not need to refer to specific devices because the binding defines which device's controls are used to perform the action. -To use actions in your code, you must use the [Input Actions editor](ActionsEditor.md) to establish the mapping between the Action and one or more device controls. For example in this screenshot, the "Move" action is displayed, showing its bindings the left gamepad stick, and the keyboard's arrow keys. +To use actions in your code, you must use the [Input Actions editor](actions-editor.md) to configure the mapping between the Action and one or more device controls. For example in this screenshot, the "Move" action is displayed, showing its bindings the left gamepad stick, and the keyboard's arrow keys. ![Actions Bindings](Images/ActionsBinding.png)
*The Actions panel of the Input Actions Editor in Project Settings* -You can then get a reference to this action in your code, and check its value, or attach a callback method to be notified when it is performed. See the [Actions Workflow page](Workflow-Actions.md) for a simple example script demonstrating this. +You can then get a reference to this action in your code, and check its value, or attach a callback method to be notified when it is performed. See the [Actions Workflow page](using-actions-workflow.md) for a simple example script demonstrating this. -Actions also make it simpler to create a system that lets your players [customize their bindings at runtime](ActionBindings.md#interactive-rebinding), which is a common requirement for games. +Actions also make it simpler to create a system that lets your players [customize their bindings at runtime](rebind-action-runtime.md), which is a common requirement for games. >**Notes:** > - Actions are a runtime only feature. You can't use them in [Editor window code](https://docs.unity3d.com/ScriptReference/EditorWindow.html). > -> - You can read input without using Actions and Bindings by directly reading specific device controls. This is less flexible, but can be quicker to implement for certain situations. Read more about [directly reading devices from script](Workflow-Direct.md). +> - You can read input without using Actions and Bindings by directly reading specific device controls. This is less flexible, but can be quicker to implement for certain situations. Read more about [directly reading devices from script](using-direct-workflow.md). > -> - Although you can reorder actions in this window, the ordering is for visual convenience only, and does not affect the order in which the actions are triggered in your code. If multiple actions are performed in the same frame, the order in which they are reported by the input system is undefined. To avoid problems, you should not write code that assumes they will be reported in a particular order. ->
  - - -## Overview - -When scripting with Actions in the Input System, there are number of important API you can use, which are described here: - -|API name|Description| -|-----|-----------| -|[`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html)|A reference to the set of actions assigned as the [project-wide Actions](./ProjectWideActions.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).| - -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. - -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. - -## Creating Actions - -The simplest way to create actions is to use the [Input Actions editor](ActionsEditor.md) in the Project Settings window. This is the primary recommended workflow and suitable for most scenarios. - -However, because the input system API is very open, there are many other ways to create actions which may suit less common scenarios. For example, by loading actions from JSON data, or creating actions entirely in code. - -### Creating Actions using the Action editor - -For information on how to create and edit Input Actions in the editor, see the [Input Actions editor](ActionsEditor.md). This is the recommended workflow if you want to organise all your input actions and bindings in one place, which applies across the whole of your project. This often the case for most types of game or app. - -![Action Editor Window](Images/ProjectSettingsInputActionsSimpleShot.png) -*The Input Actions Editor in the Project Settings window* - - -# Other ways to create Actions - -The simplest way to create actions is to use the [Input Actions editor](ActionsEditor.md) to configure a set of actions in an asset, as described above. However, because the Input System package API is open and flexible, you can create actions using alternative techniques. These alternatives might be more suitable if you want to customize your project beyond the standard workflow. - -### Creating Actions by declaring them in MonoBehaviours - -As an alternative workflow, you can declare individual [Input Action](../api/UnityEngine.InputSystem.InputAction.html) and [Input Action Maps](../api/UnityEngine.InputSystem.InputActionMap.html) as fields directly inside `MonoBehaviour` components. - -```CSharp -using UnityEngine; -using UnityEngine.InputSystem; - -public class ExampleScript : MonoBehaviour -{ - public InputAction move; - public InputAction jump; -} -``` - -The result is similar to using an Actions defined in the Input Actions editor, except the Actions are defined in the GameObject's properties and saved as Scene or Prefab data, instead of in a dedicated Asset. - -When you embed actions like this, by defining serialized InputAction fields in a MonoBehaviour, the GameObject's Inspector window displays an interface similar to the Actions column of the [Actions Editor](./ActionsEditor.md), which allows you to set up the bindings for those actions. For example: - -![MyBehavior Inspector](Images/Workflow-EmbeddedActionsInspector.png) - -* To add or remove Actions or Bindings, click the Add (+) or Remove (-) icon in the header. -* To edit Bindings, double-click them.
-* To edit Actions, double-click them in an Action Map, or click the gear icon on individual Action properties.
-* You can also right-click entries to bring up a context menu, and you can drag them. Hold the Alt key and drag an entry to duplicate it. - -Unlike the project-wide actions in the Project Settings window, you must manually enable and disable Actions and Action Maps that are embedded in MonoBehaviour components. - -When you use this workflow, the serialised action configurations are stored with the parent GameObject as part of the scene, opposite to being serialised with an Action Asset. This can be useful if you want to bundle the control bindings and behaviour together in a single monobehaviour or prefab, so it can be distributed together. However, this can also make it harder to organize your full set of control bindings if they are distributed across multiple prefabs or scenes. - -### Loading Actions from JSON - -You can load Actions as JSON in the form of a set of Action Maps or as a full [`InputActionAsset`](../api/UnityEngine.InputSystem.InputActionAsset.html). This also works at runtime in the Player. - -```CSharp -// Load a set of action maps from JSON. -var maps = InputActionMap.FromJson(json); - -// Load an entire InputActionAsset from JSON. -var asset = InputActionAsset.FromJson(json); -``` - -### Creating Actions in code - -You can manually create and configure Actions entirely in code, including assigning the bindings. This also works at runtime in the Player. For example: - -```CSharp -// Create free-standing Actions. -var lookAction = new InputAction("look", binding: "/leftStick"); -var moveAction = new InputAction("move", binding: "/rightStick"); - -lookAction.AddBinding("/delta"); -moveAction.AddCompositeBinding("Dpad") - .With("Up", "/w") - .With("Down", "/s") - .With("Left", "/a") - .With("Right", "/d"); - -// Create an Action Map with Actions. -var map = new InputActionMap("Gameplay"); -var lookAction = map.AddAction("look"); -lookAction.AddBinding("/leftStick"); - -// Create an Action Asset. -var asset = ScriptableObject.CreateInstance(); -var gameplayMap = new InputActionMap("gameplay"); -asset.AddActionMap(gameplayMap); -var lookAction = gameplayMap.AddAction("look", "/leftStick"); -``` - -Any action that you create in this way during Play mode 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. - - -## Enabling actions - -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](./ProjectWideActions.md), the actions it contains are enabled by default and ready to use. - -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. - -You can enable actions individually, or as a group by enabling the Action Map which contains them. - -```CSharp -// Enable a single action. -lookAction.Enable(); - -// Enable an en entire action map. -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). - -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). - -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. diff --git a/Packages/com.unity.inputsystem/Documentation~/ActionsEditor.md b/Packages/com.unity.inputsystem/Documentation~/ActionsEditor.md deleted file mode 100644 index 39ac1fe4b6..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/ActionsEditor.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -uid: input-system-configuring-input ---- -# Configuring Input with the Actions Editor - -The **Input Actions Editor** allows you to edit [Action Assets](ActionAssets.md), which contain a saved configuration of [Input Actions](Actions.md) and their associated [Bindings](ActionBindings.md). - -It allows you to group collections of Actions into [Action Maps](ActionsEditor.html#configure-action-maps), which represent different input scenarios in your project (such as UI navigation, gameplay, etc.) - -It also alows you to define [Control Schemes](ActionBindings.md#control-schemes) which are a way to enable or disable a set of devices, or respond to which type of device is being used. This is often useful if you want to customise your UI based on whether your users are using mouse, keyboard, or gamepad as their chosen input. - -### Action Assets and Project-Wide Actions - -The typical workflow for most projects is to have a single Action Asset, which is assigned as the **project-wide actions**. If you have not yet created and assigned an Actions Asset as the project-wide actions, the recommended workflow is to do this first. Read more about [project-wide actions](ProjectWideActions.md). - -### Opening the Actions Editor - -The **Input Actions Editor** is an editor window displayed when you open an Action Asset by double-clicking it. - -It is also displayed in the Project Settings window under **Edit** > **Project Settings** > **Input System Package** if you have an Action Asset assigned as project-wide. - -![image alt text](./Images/ActionsEditorCallout.png) -*The Input Actions editor, displaying the default actions* - -### The Actions Editor panels - -The Input Actions editor is divided into three panels (marked A, B & C above). - -|Name|Description| -|-|-| -|**(A) Action Maps**|Displays the list of currently defined Action Maps. Each Action Map is a collection of Actions that you can enable or disable together as a group.| -|**(B) Actions**|Displays all the actions defined in the currently selected Action Map, and the bindings associated with each Action.| -|**(C) Properties**|Displays the properties of the currently selected Action or Binding from the Actions panel. The title of this panel changes depending on whether you have an Action or a Binding selected in the Actions panel.| - -### Configure Action Maps - -* To add a new Action Map, select the Add (+) icon in the header of the Action Map panel. -* To rename an existing Action Map, either long-click the name, or right-click the Action Map and select __Rename__ from the context menu. Note that Action Map names can't contain slashes (`/`). -* To delete an existing Action Map, right-click it and select __Delete__ from the context menu. -* To duplicate an existing Action Map, right-click it and select __Duplicate__ from the context menu. - -### Configure Actions - -* To add a new Action, select the Add (+) icon in the header of the Action column. -* To rename an existing Action, either long-click the name, or right-click the Action Map and select __Rename__ from the context menu. -* To delete an existing Action, either right-click it and select __Delete__ from the context menu. -* To duplicate an existing Action, either right-click it and select __Duplicate__ from the context menu. -* - - -## Action type and Control type - -If you select an Action, you can edit its properties in the right-hand pane of the window: - -![Action Properties](Images/ActionProperties.png) - -#### Action Type - -The Action Type setting allows to to select between **Button**, **Value** or **PassThrough**. - -These options relate to whether this action should represent a discrete on/off button-style interaction or a value that can change over time while the control is being used. - -For device controls such as keyboard keys, mouse clicks, or gamepad buttons, select **Button**. For device controls such as mouse movement, a joystick or gamepad stick, or device orientation that provide continuously changing input over a period of time, select **Value**. - -The Button and Value types of action also provides data about the action such as whether it has started and stopped, and conflict resolution in situations where multiple bindings are mapped to the same action. - -The third option, **PassThrough**, is also a value type, and as such is suitable for the same types of device controls as value. The difference is that actions set to PassThrough only provide basic information about the values incoming from the device controls bound to it, and does not provide the extra data relating to the phase of the action, nor does it perform conflict resolution in the case of multiple controls mapped to the same action. - -For more detail about how these types work, see [action types](RespondingToActions.html#action-types) and [default interactions](Interactions.html#default-interaction). - -#### Control Type - -The Control Type setting allows you to select the type of control expected by the action. This limits the controls shown when setting up bindings in the UI and also limits which contols can be bound interactively to the action. - -For example, if you select **2D axis**, only those controls that can supply a 2D vector as value are available as options for the binding control path. - -There are more specific control types available which futher filter the available bindings, such as "Stick", "Dpad" or "Touch". If you select one of these control types, the list of available controls is further limited to only those controls of those specific types when you select a binding for your action (see directly below). - -### Bindings - -* To add a new Binding, select the Add (+) icon on the action you want to add it to, and select the binding type from the menu that appears. -* To delete an existing Binding, either right-click it and select __Delete__ from the context menu. -* To duplicate an existing Binding, either right-click it and select __Duplicate__ from the context menu. - -You can add multiple bindings to an action, which is generally useful for supporting multiple types of input device. For example, in the default set of actions, the "Move" action has a binding to the left gamepad stick and the WSAD keys, which means input through any of these bindings will perform the action. - -![The default "move" action with its multiple bindings highlighted](./Images/ActionWithMultipleBindings.png)
-_The default "Move" action in the Actions Editor window, displaying the multiple bindings associated with it._ - -If you select a Binding, you can edit its properties in the right-hand pane of the window: - -![Binding Properties](Images/BindingProperties.png) - -#### Picking Controls - -The most important property of any Binding is the [control path](Controls.md#control-paths) it's bound to. To edit it, open the __Path__ drop-down list. This displays a Control picker window. - -![Control Picker](Images/InputControlPicker.png) - -In the Control picker window, you can explore a tree of Input Devices and Controls that the Input System recognizes, and bind to these Controls. Unity filters this list by the Action's [`Control Type`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_expectedControlType) property. For example, if the Control type is `Vector2`, you can only select a Control that generates two-dimensional values, like a stick. - -The Device and Control tree is organized hierarchically from generic to specific. For example, the __Gamepad__ Control path `/buttonSouth` matches the lower action button on any gamepad. Alternatively, if you navigate to __Gamepad__ > __More Specific Gamepads__ and select __PS4 Controller__, and then choose the Control path `/buttonSouth`, this only matches the "Cross" button on PlayStation gamepads, and doesn't match any other gamepads. - -Instead of browsing the tree to find the Control you want, it's easier to let the Input System listen for input. To do that, select the __Listen__ button. At first, the list of Controls is empty. Once you start pressing buttons or actuating Controls on the Devices you want to bind to, the Control picker window starts listing any Bindings that match the controls you pressed. Select any of these Bindings to view them. - -Finally, you can choose to manually edit the Binding path, instead of using the Control picker. To do that, select the __T__ button next to the Control path popup. This changes the popup to a text field, where you can enter any Binding string. This also allows you to use wildcard (`*`) characters in your Bindings. For example, you can use a Binding path such as `/touch*/press` to bind to any finger being pressed on the touchscreen, instead of manually binding to `/touch0/press`, `/touch1/press` and so on. - -#### Editing Composite Bindings - -Composite Bindings are Bindings consisting of multiple parts, which form a Control together. For instance, a [2D Vector Composite](ActionBindings.md#2d-vector) uses four buttons (left, right, up, down) to simulate a 2D stick input. See the [Composite Bindings](ActionBindings.md#composite-bindings) documentation to learn more. - -![2D Vector Composite](./Images/2DVectorComposite.png) - -To create a Composite Binding, in the Input Action Asset editor window, select the Add (+) icon on the Action you want to add it to, and select the Composite Binding type from the popup menu. - -![Add 2D Vector Composite](./Images/Add2DVectorComposite.png) - -This creates multiple Binding entries for the Action: one for the Composite as a whole, and then, one level below that, one for each Composite part. The Composite itself doesn't have a Binding path property, but its individual parts do, and you can edit these parts like any other Binding. Once you bind all the Composite's parts, the Composite can work together as if you bound a single control to the Action. - -**Note**: The set of Composites displayed in the menu is depends on the value type of the Action. This means that, for example, if the Action is set to type "Button", then only Composites able to return values of type `float` will be shown. - -To change the type of a Composite retroactively, select the Composite, then select the new type from the **Composite Type** drop-down in the **Properties** pane. - -![Composite Type](./Images/CompositeType.png) - -To change the part of the Composite to which a particular Binding is assigned, use the **Composite Part** drop-down in the Binding's properties. - -![Composite Part](./Images/CompositePart.png) - -You can assign multiple Bindings to the same part. You can also duplicate individual part Bindings: right-click the Binding, then select **Duplicate** to create new part Bindings for the Composite. This can be used, for example, to create a single Composite for both "WASD" style controls and arrow keys. - -![Duplicated Part Bindings](./Images/DuplicatedPartBindings.png) - -### Editing Control Schemes - -Input Action Assets can have multiple [Control Schemes](ActionBindings.md#control-schemes), which let you enable or disable different sets of Bindings for your Actions for different types of Devices. - -![Control Scheme Properties](Images/ControlSchemeProperties.png) - -To see the Control Schemes in the Input Action Asset editor window, open the Control Scheme drop-down list in the top left of the window. This menu lets you add or remove Control Schemes to your Actions Asset. If the Actions Asset contains any Control Schemes, you can select a Control Scheme, and then the window only shows bindings that are associated with that Scheme. If you select a binding, you can now pick the Control Schemes for which this binding should be active in the __Properties__ view to the left of the window. - -When you add a new Control Scheme, or select an existing Control Scheme, and then select __Edit Control Scheme__, you can edit the name of the Control Scheme and which devices the Scheme should be active for. When you add a new Control Scheme, the "Device Type" list is empty by default (as shown above). You must add at least one type of device to this list for the Control Scheme to be functional. diff --git a/Packages/com.unity.inputsystem/Documentation~/Architecture.md b/Packages/com.unity.inputsystem/Documentation~/Architecture.md index 427ab04ac5..8533d46aa3 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Architecture.md +++ b/Packages/com.unity.inputsystem/Documentation~/Architecture.md @@ -9,9 +9,9 @@ The Input System has a layered architecture that consists of a low-level layer a The foundation of the Input System is the native backend code. This is platform-specific code which collects information about available Devices and input data from Devices. This code is not part of the Input System package, but is included with Unity itself. It has implementations for each runtime platform supported by Unity. This is why some platform-specific input bugs can only be fixed by an update to Unity, rather than a new version of the Input System package. -The Input System interfaces with the native backend using [events](Events.md) that the native backend sends. These events notify the system of the creation and removal of [Input Devices](Devices.md), as well as any updates to the Device states. For efficiency and to avoid creating any garbage, the native backend reports these events as a simple buffer of raw, unmanaged memory containing a stream of events. +The Input System interfaces with the native backend using [events](input-events.md) that the native backend sends. These events notify the system of the creation and removal of [Input Devices](devices.md), as well as any updates to the Device states. For efficiency and to avoid creating any garbage, the native backend reports these events as a simple buffer of raw, unmanaged memory containing a stream of events. -The Input System can also send data back to the native backend in the form of [commands](Devices.md#device-commands) sent to Devices, which are also buffers of memory that the native backend interprets. These commands can have different meanings for different Device types and platforms. +The Input System can also send data back to the native backend in the form of [commands](device-commands.md) sent to Devices, which are also buffers of memory that the native backend interprets. These commands can have different meanings for different Device types and platforms. # Input System (low-level) @@ -19,7 +19,7 @@ The Input System can also send data back to the native backend in the form of [c The low-level Input System code processes and interprets the memory from the event stream that the native backend provides, and dispatches individual events. -The Input System creates Device representations for any newly discovered Device in the event stream. The low-level code sees a Device as a block of raw, unmanaged memory. If it receives a state event for a Device, it writes the data from the state event into the Device's [state representation](Controls.md#control-state) in memory, so that the state always contains an up-to-date representation of the Device and all its Controls. +The Input System creates Device representations for any newly discovered Device in the event stream. The low-level code sees a Device as a block of raw, unmanaged memory. If it receives a state event for a Device, it writes the data from the state event into the Device's [state representation](controls.md#control-state) in memory, so that the state always contains an up-to-date representation of the Device and all its Controls. The low-level system code also contains structs which describe the data layout of commonly known Devices. @@ -27,8 +27,8 @@ The low-level system code also contains structs which describe the data layout o ![High-Level Architecture](Images/InputArchitectureHighLevel.png) -The high-level Input System code interprets the data in a Device's state buffers by using [layouts](Layouts.md), which describe the data layout of a Device and its Controls in memory. The Input System creates layouts from either the pre-defined structs of commonly known Devices supplied by the low level system, or dynamically at runtime, as in the case of [generic HIDs](HID.md#auto-generated-layouts). +The high-level Input System code interprets the data in a Device's state buffers by using [layouts](layouts.md), which describe the data layout of a Device and its Controls in memory. The Input System creates layouts from either the pre-defined structs of commonly known Devices supplied by the low level system, or dynamically at runtime, as in the case of [generic HIDs](hid-specification.md). -Based on the information in the layouts, the Input System then creates [Control](Controls.md) representations for each of the Device's controls, which let you read the state of each individual Control in a Device. +Based on the information in the layouts, the Input System then creates [Control](controls.md) representations for each of the Device's controls, which let you read the state of each individual Control in a Device. -As part of the high-level system, you can also build another abstraction layer to map Input Controls to your application mechanics. Use [Actions](Actions.md) to [bind](ActionBindings.md) one or more Controls to an input in your application. The Input System then monitors these Controls for state changes, and notifies your game logic using [callbacks](RespondingToActions.md#responding-to-actions-using-callbacks). You can also specify more complex behaviors for your Actions using [Processors](Processors.md) (which perform processing on the input data before sending it to you) and [Interactions](Interactions.md) (which let you specify patterns of input on a Control to listen to, such as multi-taps). +As part of the high-level system, you can also build another abstraction layer to map Input Controls to your application mechanics. Use [Actions](actions.md) to [bind](bindings.md) one or more Controls to an input in your application. The Input System then monitors these Controls for state changes, and notifies your game logic using [callbacks](respond-to-input.md#responding-to-actions-using-callbacks). You can also specify more complex behaviors for your Actions using [Processors](processors.md) (which perform processing on the input data before sending it to you) and [Interactions](Interactions.md) (which let you specify patterns of input on a Control to listen to, such as multi-taps). diff --git a/Packages/com.unity.inputsystem/Documentation~/Concepts.md b/Packages/com.unity.inputsystem/Documentation~/Concepts.md deleted file mode 100644 index b36cd4fcb0..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/Concepts.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -uid: basic-concepts ---- -# Basic Concepts - -This page introduces the basic concepts that relate to working with the Input System. They relate to the steps in the sequence of events that occur when a user sends input to your game or app. The Input System provides features which implement these steps, or you can choose to implement some of them yourself. - -![](Images/ConceptsOverview.png) - -|Concept|Description| -|-------|-----------| -|[**User**](UserManagement.html)| The person playing your game or using your app, by holding or touching the input device and providing input.| -|[**Input Device**](SupportedDevices.html)| Often referred to just as a "**device**" within the context of input. A physical piece of hardware, such as a keyboard, gamepad, mouse, or touchscreen which allows the user to send input into Unity.| -|[**Control**](Controls.html)|The separate individual parts of an input device which each send input values into Unity. For example, a gamepad’s **controls** comprise multiple buttons, sticks and triggers, and a mouse’s controls include the two X and Y sensors on the underside, and the various buttons and scroll wheels on the top side.| -|[**Action**](Actions.html)| Actions are a high-level concept that describe individual things that a user might want to do in your game or app, such as "Jump" within a game, or "Select" in an on-screen UI. They are things a user can do in your game or app as a result of input, regardless of what device or control they use to perform it. Actions generally have conceptual names that you choose to suit your project, and should usually be verbs. For example "Run", "Jump" "Crouch", "Use", "Start", "Quit".| -|[**Action Map**](ActionsEditor.html#configure-action-maps) | Action Maps allow you to organise Actions into groups which represent specific situations where a set of actions make sense together. You can simultaneously enable or disable all Actions in an action map, so it is useful to group Actions in Action Maps by the context in which they are relevant. For example, you might have one action map for controlling a player, and another for interacting with your game's UI.| -|[**Binding**](ActionBindings.html)| A connection defined between an **Action** and specific device controls. For example, your "Move" action might have bindings to the arrow keys and WSAD keys on the keyboard, and the left stick on a joypad, and the primary 2D axis on a VR controller. Multiple bindings like this means your game can accept cross-platform input. | -|[**Your Action Code**](RespondingToActions.md)| The part of your script which is executed based on the actions you have configured. In your code, you can use references to actions to either read the current value or state of the action (also known as "polling"), or set up a callback to call your own method when actions are performed.| -|[**Action Asset**](ActionAssets.md) | An asset type which contains a saved configuration of Action Maps, Actions and Bindings. You can specify one Action Asset in your project as the [project-wide actions](ProjectWideActions.md), which allows you to easily reference those actions in code by using [`InputSystem.actions`](../api/UnityEngine.InputSystem.InputSystem.html). | diff --git a/Packages/com.unity.inputsystem/Documentation~/Contributing.md b/Packages/com.unity.inputsystem/Documentation~/Contributing.md index ad1e654e45..4d1cb726df 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Contributing.md +++ b/Packages/com.unity.inputsystem/Documentation~/Contributing.md @@ -1,7 +1,7 @@ --- uid: input-system-contributing --- -# Contributing +# Contribute to the Input System source code The [full source code](https://github.com/Unity-Technologies/InputSystem) for the Input System is available on GitHub. This is also where most of the Input System's development happens. diff --git a/Packages/com.unity.inputsystem/Documentation~/Controls.md b/Packages/com.unity.inputsystem/Documentation~/Controls.md deleted file mode 100644 index 19292386ea..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/Controls.md +++ /dev/null @@ -1,285 +0,0 @@ ---- -uid: input-system-controls ---- -# Controls - -* [Hierarchies](#control-hierarchies) -* [Types](#control-types) -* [Usages](#control-usages) -* [Paths](#control-paths) -* [State](#control-state) -* [Actuation](#control-actuation) -* [Noisy Controls](#noisy-controls) -* [Synthetic Controls](#synthetic-controls) -* [Performance Optimization](#performance-optimization) - -An Input Control represents a source of values. These values can be of any structured or primitive type. The only requirement is that the type is [blittable](https://docs.microsoft.com/en-us/dotnet/framework/interop/blittable-and-non-blittable-types). - ->__Note__: Controls are for input only. Output and configuration items on Input Devices are not represented as Controls. - -Each Control is identified by a name ([`InputControl.name`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_name)) and can optionally have a display name ([`InputControl.displayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_displayName)) that differs from the Control name. For example, the right-hand face button closest to the touchpad on a PlayStation DualShock 4 controller has the control name "buttonWest" and the display name "Square". - -Additionally, a Control might have one or more aliases which provide alternative names for the Control. You can access the aliases for a specific Control through its [`InputControl.aliases`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_aliases) property. - -Finally, a Control might also have a short display name which can be accessed through the [`InputControl.shortDisplayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_shortDisplayName) property. For example, the short display name for the left mouse button is "LMB". - -## Control hierarchies - -Controls can form hierarchies. The root of a Control hierarchy is always a [Device](Devices.md). - -The setup of hierarchies is exclusively controlled through [layouts](Layouts.md). - -You can access the parent of a Control using [`InputControl.parent`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_parent), and its children using [`InputControl.children`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_children). To access the flattened hierarchy of all Controls on a Device, use [`InputDevice.allControls`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_allControls). - -## Control types - -All controls are based on the [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html) base class. Most concrete implementations are based on [`InputControl`](../api/UnityEngine.InputSystem.InputControl-1.html). - -The Input System provides the following types of controls out of the box: - -|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)| - -You can browse the set of all registered control layouts in the [input debugger](Debugging.md#debugging-layouts). - -## Control usages - -A Control can have one or more associated usages. A usage is a string that denotes the Control's intended use. An example of a Control usage is `Submit`, which labels a Control that is commonly used to confirm a selection in the UI. On a gamepad, this usage is commonly found on the `buttonSouth` Control. - -You can access a Control's usages using the [`InputControl.usages`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_usages) property. - -Usages can be arbitrary strings. However, a certain set of usages is very commonly used and comes predefined in the API in the form of the [`CommonUsages`](../api/UnityEngine.InputSystem.CommonUsages.html) static class. Check out the [`CommonUsages` scripting API page](../api/UnityEngine.InputSystem.CommonUsages.html) for an overview. - -## Control paths - ->Example: `/leftStick/x` means "X Control on left stick of gamepad". - -The Input System can look up Controls using textual paths. [Bindings](ActionBindings.md) on Input Actions rely on this feature to identify the Control(s) they read input from. However, you can also use them for lookup directly on Controls and Devices, or to let the Input System search for Controls among all devices using [`InputSystem.FindControls`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_FindControls_System_String_). - -```CSharp -var gamepad = Gamepad.all[0]; -var leftStickX = gamepad["leftStick/x"]; -var submitButton = gamepad["{Submit}"]; -var allSubmitButtons = InputSystem.FindControls("*/{Submit}"); -``` - -Control paths resemble file system paths. Each path consists of one or more components separated by a forward slash: - - component/component... - -Each component uses a similar syntax made up of multiple fields. Each field is optional, but at least one field must be present. All fields are case-insensitive. - - {usageName}controlName#(displayName) - -The following table explains the use of each field: - -|Field|Description|Example| -|-----|-----------|-------| -|``|Requires the Control at the current level to be based on the given layout. The actual layout of the Control may be the same or a layout *based* on the given layout.|`/buttonSouth`| -|`{usageName}`|Works differently for Controls and Devices.

When used on a Device (the first component of a path), it requires the device to have the given usage. See [Device usages](Devices.md#device-usages) for more details.

For looking up a Control, the usage field is currently restricted to the path component immediately following the Device (the second component in the path). It finds the Control on the Device that has the given usage. The Control can be anywhere in the Control hierarchy of the Device.|Device:

`{LeftHand}/trigger`

Control:

`/{Submit}`| -|`controlName`|Requires the Control at the current level to have the given name. Takes both "proper" names ([`InputControl.name`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_name)) and aliases ([`InputControl.aliases`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_aliases)) into account.

This field can also be a wildcard (`*`) to match any name.|`MyGamepad/buttonSouth`

`*/{PrimaryAction}` (match `PrimaryAction` usage on Devices with any name)| -|`#(displayName)`|Requires the Control at the current level to have the given display name (i.e. [`InputControl.displayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_displayName)). The display name may contain whitespace and symbols.|`/#(a)` (matches the key that generates the "a" character, if any, according to the current keyboard layout).

`/#(Cross)`| - -You can access the literal path of a given control via its [`InputControl.path`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_path) property. - -If needed, you can manually parse a control path into its components using the [`InputControlPath.Parse(path)`](../api/UnityEngine.InputSystem.InputControlPath.html#UnityEngine_InputSystem_InputControlPath_Parse_System_String_) API. - -```CSharp -var parsed = InputControlPath.Parse("{LeftHand}/trigger").ToArray(); - -Debug.Log(parsed.Length); // Prints 2. -Debug.Log(parsed[0].layout); // Prints "XRController". -Debug.Log(parsed[0].name); // Prints an empty string. -Debug.Log(parsed[0].usages.First()); // Prints "LeftHand". -Debug.Log(parsed[1].layout); // Prints null. -Debug.Log(parsed[1].name); // Prints "trigger". -``` - -## Control state - -Each Control is connected to a block of memory that is considered the Control's "state". You can query the size, format, and location of this block of memory from a Control through the [`InputControl.stateBlock`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_stateBlock) property. - -The state of Controls is stored in unmanaged memory that the Input System handles internally. All Devices added to the system share one block of unmanaged memory that contains the state of all the Controls on the Devices. - -A Control's state might not be stored in the natural format for that Control. For example, the system often represents buttons as bitfields, and axis controls as 8-bit or 16-bit integer values. This format is determined by the combination of platform, hardware, and drivers. Each Control knows the format of its storage and how to translate the values as needed. The Input System uses [layouts](Layouts.md) to understand this representation. - -You can access the current state of a Control through its [`ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) method. - -```CSharp -Gamepad.current.leftStick.x.ReadValue(); -``` - -Each type of Control has a specific type of values that it returns, regardless of how many different types of formats it supports for its state. You can access this value type through the [`InputControl.valueType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_valueType) property. - -Reading a value from a Control might apply one or more value Processors. See documentation on [Processors](Processors.md) for more information. - -[//]: # (#### Default State - TODO) - -[//]: # (#### Reading State vs Reading Values - TODO) - -#### Recording state history - -You might want to access the history of value changes on a Control (for example, in order to compute exit velocity on a touch release). - -To record state changes over time, you can use [`InputStateHistory`](../api/UnityEngine.InputSystem.LowLevel.InputStateHistory.html) or [`InputStateHistory`](../api/UnityEngine.InputSystem.LowLevel.InputStateHistory-1.html). The latter restricts Controls to those of a specific value type, which in turn simplifies some of the API. - -```CSharp -// Create history that records Vector2 control value changes. -// NOTE: You can also pass controls directly or use paths that match multiple -// controls (e.g. "/