Gamepad ******* Setup ===== - Windows > Package manager. Select Unity Registry. .. image:: reg.png - Look for **Input System** and install it - Restart Unity as requested Control ======= A **control** is a specific input element on a device (such as a key, button) that can produce an input signal, for example: - /space - /leftButton - /leftStick The Unity Input System provides a unified naming scheme for controls, allowing the same bindings to work across different consoles, mouses and gamepads: Gamepad ======= The Unity Input System uses standardized names for gamepad controls: .. list-table:: :header-rows: 1 * - Unity Input System - Xbox - PlayStation - Nintendo Switch * - **/buttonSouth** - A - Cross (✕) - B * - **/buttonNorth** - Y - Triangle (△) - X * - **/buttonWest** - X - Square (□) - Y * - **/buttonEast** - B - Circle (○) - A * - **/leftShoulder** - LB - L1 - L * - **/rightShoulder** - RB - R1 - R * - **/leftTrigger** - LT - L2 - ZL * - **/rightTrigger** - RT - R2 - ZR * - **/start** - Menu - Options - \+ * - **/select** - View - Share - \- * - **/leftStickPress** - LS - L3 - Stick press * - **/rightStickPress** - RS - R3 - Stick press To clarify the naming, the following diagram shows the standard control names for an Xbox gamepad: .. image:: joy.png :scale: 70% Warning: In Unity, **leftStick** refers to the stick located on the left side of the gamepad, not to the stick being pushed to the left. Leftstick and rightstick are analog controller that return a 2D vector describing the direction of the stick. The directional pad is a discrete directional control that can return only nine possible directions. .. figure:: dir.png :scale: 80% :align: center Analog stick values represented as a Vector2. The directional pad can be used either as a 2D directional control using */dpad* or as four individual buttons: */dpad/up*, */dpad/down*, *`/dpad/left*, and */dpad/right* but not simultaneously. Mouse ===== .. list-table:: :header-rows: 1 * - Unity Input System - Description - Typical Use * - **/leftButton** - Left mouse button - Primary action / Fire / Select * - **/rightButton** - Right mouse button - Secondary action / Aim / Context menu * - **/middleButton** - Middle mouse button (wheel click) - Camera control / Special action * - **/scroll** - Scroll wheel axis - Zoom / Weapon switch * - **/position** - Cursor position on screen - UI interaction / Cursor tracking * - **/delta** - Mouse movement delta - Camera look / Free look * - **/press** - Any mouse button press - Generic mouse input detection Keyboard ======== As you know, a game is distributed internationally, which means it must work with any keyboard layout. To handle this issue, two approaches can be used for choosing a control: .. image:: key.png - By the physical **Location of the key** on the keyboard .. image:: keyboard.png :scale: 80% - By the **character**: \'A\', \'b\'... The first approach is commonly used in games. This way, whether you are using a French or an English keyboard, the keys used for movement (ZQSD or WASD) are located in the same physical positions. The second approach is better suited for text input, such as a chat or a text field, where the character produced by the key is what matters most. .. warning:: To locate a key on the keyboard, the system does not use an ID or coordinates. Instead, it uses the character (\'A\', \'M\'...) associated with the key in the US keyboard layout. This may create confusion between the *key location* system and the *character-based* system. Actions, Bindings and Action Maps ================================= An **action** represents a gameplay operation (for example move, jump, or fire) that can be triggered by different input *controls*. A **binding** associates one *control* (key, button, or axis) with an *action*. For example, the ``Fire`` action can be triggered by: - /leftButton - /space - /buttonSouth All actions and their bindings are organized in an **Action Map**. The structure can be summarized as follows: .. code-block:: text Action Map ├── Action 1 │ ├── Binding 1 │ └── Binding 2 ├── Action 2 │ ├── Binding 3 │ ├── Binding 4 │ └── Binding 5 └── Action 3 └── Binding 6 In practice, a production-ready game defines different **Action Maps** for different gameplay contexts such as walking, swimming, or driving. Each map contains the actions and bindings relevant to that context. .. note:: In the program, the code you write only interacts with actions. Keyboard, mouse, or gamepad inputs are no longer handled directly. This abstraction makes the action logic independent from the underlying hardware. Binding Types ============= An *input control* can be linked to an action in 3 differents ways, depending on the number of controls that must be pressed: 1 2 or 3 Another type of binding is used to handle directional input. It allows keys such as WASD (or ZQSD-fr) or a gamepad stick to generate a **Vector2**. .. list-table:: :header-rows: 1 * - **Name** - Information - Keyboard - Gamepad * - **Add Binding** - 1 control triggers the action - *Space* - *buttonSouth* * - **Add Binding With One Modifier** - 2 constrols required - *Shift + W* - *leftShoulder + buttonSouth* * - **Add Binding With Two Modifiers** - 3 controls required - *Ctrl + Shift + S* - *leftShoulder + rightShoulder + buttonSouth* * - **Name: Up/Down/Left/Right Composite** - return a 2D movement vector - W A S D or Z Q S D - leftStick Build your own action map ========================= - In the asset folder of your project, right click and select: Create → Input Actions - Name it *PlayerControls* .. image:: playercontrol.png - Double click to open the *PlayerControls* in the Input Actions Editor .. image:: actioneditor.png - Click on the + button to add a new *Action map*, name it *MyGameplay* - Add these actions: - Move : Action Type = Value, Control Type = Vector2 - Jump : Action Type = Button - Click on the + icon to *Add Binding* .. image:: actioneditor2.png - Configure your bindings to obtain the following map: .. image:: result.png :align: center :scale: 150% Last words ========== In the *Assets* folder, open the file associated with your PlayerControls asset in a text editor. You will notice that it is a JSON file containing all the required information. .. image:: json.png :align: center :scale: 80% During the game, we can provide a UI to change bindings. In that case, a script can apply binding overrides at runtime: .. code-block:: csharp var fire = actions.FindAction("Fire"); fire.ApplyBindingOverride(0, "/leftButton"); Finally, we save the current binding overrides to a JSON string (or a file) to persist the player's custom bindings, and reload them the next time the game starts.