controllers_gamepads_joysticks.rst 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320
  1. .. _doc_controllers_gamepads_joysticks:
  2. Controllers, gamepads, and joysticks
  3. ====================================
  4. Godot supports hundreds of controller models thanks to the community-sourced
  5. `SDL game controller database <https://github.com/gabomdq/SDL_GameControllerDB>`__.
  6. Controllers are supported on Windows, macOS, Linux, Android, iOS, and HTML5.
  7. Note that more specialized devices such as steering wheels, rudder pedals and
  8. `HOTAS <https://en.wikipedia.org/wiki/HOTAS>`__ are less tested and may not
  9. always work as expected. Overriding force feedback for those devices is also not
  10. implemented yet. If you have access to one of those devices, don't hesitate to
  11. `report bugs on GitHub
  12. <https://github.com/godotengine/godot/blob/master/CONTRIBUTING.md#reporting-bugs>`__.
  13. In this guide, you will learn:
  14. - **How to write your input logic to support both keyboard and controller inputs.**
  15. - **How controllers can behave differently from keyboard/mouse input.**
  16. - **Troubleshooting issues with controllers in Godot.**
  17. Supporting universal input
  18. --------------------------
  19. Thanks to Godot's input action system, Godot makes it possible to support both
  20. keyboard and controller input without having to write separate code paths.
  21. Instead of hardcoding keys or controller buttons in your scripts, you should
  22. create *input actions* in the Project Settings which will then refer to
  23. specified key and controller inputs.
  24. Input actions are explained in detail on the :ref:`doc_inputevent` page.
  25. .. note::
  26. Unlike keyboard input, supporting both mouse and controller input for an
  27. action (such as looking around in a first-person game) will require
  28. different code paths since these have to be handled separately.
  29. Which Input singleton method should I use?
  30. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  31. There are 3 ways to get input in an analog-aware way:
  32. - When you have two axes (such as joystick or WASD movement) and want both
  33. axes to behave as a single input, use ``Input.get_vector()``:
  34. .. tabs::
  35. .. code-tab:: gdscript GDScript
  36. # `velocity` will be a Vector2 between `Vector2(-1.0, -1.0)` and `Vector2(1.0, 1.0)`.
  37. # This handles deadzone in a correct way for most use cases.
  38. # The resulting deadzone will have a circular shape as it generally should.
  39. var velocity = Input.get_vector("move_left", "move_right", "move_forward", "move_back")
  40. # The line below is similar to `get_vector()`, except that it handles
  41. # the deadzone in a less optimal way. The resulting deadzone will have
  42. # a square-ish shape when it should ideally have a circular shape.
  43. var velocity = Vector2(
  44. Input.get_action_strength("move_right") - Input.get_action_strength("move_left"),
  45. Input.get_action_strength("move_back") - Input.get_action_strength("move_forward")
  46. ).clamped(1.0)
  47. .. code-tab:: csharp
  48. // `velocity` will be a Vector2 between `Vector2(-1.0, -1.0)` and `Vector2(1.0, 1.0)`.
  49. // This handles deadzone in a correct way for most use cases.
  50. // The resulting deadzone will have a circular shape as it generally should.
  51. Vector2 velocity = Input.GetVector("move_left", "move_right", "move_forward", "move_back");
  52. // The line below is similar to `get_vector()`, except that it handles
  53. // the deadzone in a less optimal way. The resulting deadzone will have
  54. // a square-ish shape when it should ideally have a circular shape.
  55. Vector2 velocity = new Vector2(
  56. Input.GetActionStrength("move_right") - Input.GetActionStrength("move_left"),
  57. Input.GetActionStrength("move_back") - Input.GetActionStrength("move_forward")
  58. ).Clamped(1.0);
  59. - When you have one axis that can go both ways (such as a throttle on a
  60. flight stick), or when you want to handle separate axes individually,
  61. use ``Input.get_axis()``:
  62. .. tabs::
  63. .. code-tab:: gdscript GDScript
  64. # `walk` will be a floating-point number between `-1.0` and `1.0`.
  65. var walk = Input.get_axis("move_left", "move_right")
  66. # The line above is a shorter form of:
  67. var walk = Input.get_action_strength("move_right") - Input.get_action_strength("move_left")
  68. .. code-tab:: csharp
  69. // `walk` will be a floating-point number between `-1.0` and `1.0`.
  70. float walk = Input.GetAxis("move_left", "move_right");
  71. // The line above is a shorter form of:
  72. float walk = Input.GetActionStrength("move_right") - Input.GetActionStrength("move_left");
  73. - For other types of analog input, such as handling a trigger or handling
  74. one direction at a time, use ``Input.get_action_strength()``:
  75. .. tabs::
  76. .. code-tab:: gdscript GDScript
  77. # `strength` will be a floating-point number between `0.0` and `1.0`.
  78. var strength = Input.get_action_strength("accelerate")
  79. .. code-tab:: csharp
  80. // `strength` will be a floating-point number between `0.0` and `1.0`.
  81. float strength = Input.GetActionStrength("accelerate");
  82. For non-analog digital/boolean input (only "pressed" or "not pressed" values),
  83. such as controller buttons, mouse buttons or keyboard keys,
  84. use ``Input.is_action_pressed()``:
  85. .. tabs::
  86. .. code-tab:: gdscript GDScript
  87. # `jumping` will be a boolean with a value of `true` or `false`.
  88. var jumping = Input.is_action_pressed("jump")
  89. .. tabs::
  90. .. code-tab:: csharp
  91. // `jumping` will be a boolean with a value of `true` or `false`.
  92. bool jumping = Input.IsActionPressed("jump");
  93. In Godot versions before 3.4, such as 3.3, ``Input.get_vector()`` and
  94. ``Input.get_axis()`` aren't available. Only ``Input.get_action_strength()``
  95. and ``Input.is_action_pressed()`` are available in Godot 3.3.
  96. Differences between keyboard/mouse and controller input
  97. -------------------------------------------------------
  98. If you're used to handling keyboard and mouse input, you may be surprised by how
  99. controllers handle specific situations.
  100. Dead zone
  101. ^^^^^^^^^
  102. Unlike keyboards and mice, controllers offer axes with *analog* inputs. The
  103. upside of analog inputs is that they offer additional flexibility for actions.
  104. Unlike digital inputs which can only provide strengths of ``0.0`` and ``1.0``,
  105. an analog input can provide *any* strength between ``0.0`` and ``1.0``. The
  106. downside is that without a deadzone system, an analog axis' strength will never
  107. be equal to ``0.0`` due to how the controller is physically built. Instead, it
  108. will linger at a low value such as ``0.062``. This phenomenon is known as
  109. *drifting* and can be more noticeable on old or faulty controllers.
  110. Let's take a racing game as a real-world example. Thanks to analog inputs, we
  111. can steer the car slowly in one direction or another. However, without a
  112. deadzone system, the car would slowly steer by itself even if the player isn't
  113. touching the joystick. This is because the directional axis strength won't be
  114. equal to ``0.0`` when we expect it to. Since we don't want our car to steer by
  115. itself in this case, we define a "dead zone" value of ``0.2`` which will ignore
  116. all input whose strength is lower than ``0.2``. An ideal dead zone value is high
  117. enough to ignore the input caused by joystick drifting, but is low enough to not
  118. ignore actual input from the player.
  119. Godot features a built-in dead zone system to tackle this problem. The default
  120. value is ``0.2``, but you can increase it or decrease it on a per-action basis
  121. in the Project Settings' Input Map tab.
  122. For ``Input.get_vector()``, the deadzone can be specified, or otherwise it
  123. will calculate the average deadzone value from all of the actions in the vector.
  124. "Echo" events
  125. ^^^^^^^^^^^^^
  126. Unlike keyboard input, holding down a controller button such as a D-pad
  127. direction will **not** generate repeated input events at fixed intervals (also
  128. known as "echo" events). This is because the operating system never sends "echo"
  129. events for controller input in the first place.
  130. If you want controller buttons to send echo events, you will have to generate
  131. :ref:`class_InputEvent` objects by code and parse them using
  132. :ref:`Input.parse_input_event() <class_Input_method_parse_input_event>`
  133. at regular intervals. This can be accomplished
  134. with the help of a :ref:`class_Timer` node.
  135. Window focus
  136. ^^^^^^^^^^^^
  137. Unlike keyboard input, controller inputs can be seen by **all** windows on the
  138. operating system, including unfocused windows.
  139. While this is useful for
  140. `third-party split screen functionality <https://nucleus-coop.github.io/>`__,
  141. it can also have adverse effects. Players may accidentally send controller inputs
  142. to the running project while interacting with another window.
  143. If you wish to ignore events when the project window isn't focused, you will
  144. need to create an :ref:`autoload <doc_singletons_autoload>` called ``Focus``
  145. with the following script and use it to check all your inputs:
  146. ::
  147. # Focus.gd
  148. extends Node
  149. var focused := true
  150. func _notification(what: int) -> void:
  151. match what:
  152. NOTIFICATION_WM_FOCUS_OUT:
  153. focused = false
  154. NOTIFICATION_WM_FOCUS_IN:
  155. focused = true
  156. func input_is_action_pressed(action: String) -> bool:
  157. if focused:
  158. return Input.is_action_pressed(action)
  159. return false
  160. func event_is_action_pressed(event: InputEvent, action: String) -> bool:
  161. if focused:
  162. return Input.is_action_pressed(action)
  163. return false
  164. Then, instead of using ``Input.is_action_pressed(action)``, use
  165. ``Focus.input_is_action_pressed(action)`` where ``action`` is the name of
  166. the input action. Also, instead of using ``event.is_action_pressed(action)``,
  167. use ``Focus.event_is_action_pressed(event, action)`` where ``event`` is an
  168. InputEvent reference and ``action`` is the name of the input action.
  169. Power saving prevention
  170. ^^^^^^^^^^^^^^^^^^^^^^^
  171. Unlike keyboard and mouse input, controller inputs do **not** inhibit sleep and
  172. power saving measures (such as turning off the screen after a certain amount of
  173. time has passed).
  174. To combat this, Godot enables power saving prevention by default when a project
  175. is running. If you notice the system is turning off its display when playing
  176. with a gamepad, check the value of **Display > Window > Energy Saving > Keep Screen On**
  177. in the Project Settings.
  178. Power saving prevention is **not** supported on Linux in Godot 3.x, but it is
  179. supported in Godot 4.x. As a workaround, increase the screensaver's timeout
  180. period to make it less likely to occur during gameplay.
  181. Troubleshooting
  182. ---------------
  183. .. seealso::
  184. You can view a list of
  185. `known issues with controller support <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Atopic%3Ainput+gamepad>`__
  186. on GitHub.
  187. My controller isn't recognized by Godot.
  188. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  189. First, check that your controller is recognized by other applications. You can
  190. use the `Gamepad Tester <https://gamepad-tester.com/>`__ website to confirm that
  191. your controller is recognized.
  192. My controller has incorrectly mapped buttons or axes.
  193. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  194. If buttons are incorrectly mapped, this may be due to an erroneous mapping from
  195. the `SDL game controller database <https://github.com/gabomdq/SDL_GameControllerDB>`__.
  196. You can contribute an updated mapping to be included in the next Godot version
  197. by opening a pull request on the linked repository.
  198. There are many ways to create mappings. One option is to use the mapping wizard
  199. in the `official Joypads demo <https://godotengine.org/asset-library/asset/140>`__.
  200. Once you have a working mapping for your controller, you can test it by defining
  201. the ``SDL_GAMECONTROLLERCONFIG`` environment variable before running Godot:
  202. .. tabs::
  203. .. code-tab:: bash Linux/macOS
  204. export SDL_GAMECONTROLLERCONFIG="your:mapping:here"
  205. ./path/to/godot.x86_64
  206. .. code-tab:: bat Windows (cmd)
  207. set SDL_GAMECONTROLLERCONFIG=your:mapping:here
  208. path\to\godot.exe
  209. .. code-tab:: powershell Windows (powershell)
  210. $env:SDL_GAMECONTROLLERCONFIG="your:mapping:here"
  211. path\to\godot.exe
  212. To test mappings on non-desktop platforms or to distribute your project with
  213. additional controller mappings, you can add them by calling
  214. :ref:`Input.add_joy_mapping() <class_Input_method_add_joy_mapping>`
  215. as early as possible in a script's ``_ready()`` function.
  216. My controller works on a given platform, but not on another platform.
  217. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  218. Linux
  219. ~~~~~
  220. Prior to Godot 3.3, official Godot binaries were compiled with udev support
  221. but self-compiled binaries were compiled *without* udev support unless
  222. ``udev=yes`` was passed on the SCons command line. This made controller
  223. hotplugging support unavailable in self-compiled binaries.
  224. HTML5
  225. ~~~~~
  226. HTML5 controller support is often less reliable compared to "native" platforms.
  227. The quality of controller support tends to vary wildly across browsers. As a
  228. result, you may have to instruct your players to use a different browser if they
  229. can't get their controller to work.
  230. Also, note that
  231. `controller support was significantly improved <https://github.com/godotengine/godot/pull/45078>`__
  232. in Godot 3.3 and later.