Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Contrôleurs, manettes de jeu et joysticks
Godot supports hundreds of controller models out of the box. Controllers are supported on Windows, macOS, Linux, Android, iOS, and Web.
Note
Since Godot 4.5, the engine relies on SDL 3 for controller support on Windows, macOS, and Linux. This means the list of supported controllers and their behavior should closely match what is available in other games and engines using SDL 3. Note that SDL is only used for input, not for windowing or sound.
Prior to Godot 4.5, the engine used its own controller support code. This can cause certain controllers to behave incorrectly. This custom code is still used to support controllers on Android and Web, so it may result in issues appearing only on those platforms.
Notez que les dispositifs plus spécialisés tels que les volants, les pédales de direction et les HOTAS sont moins testés et peuvent ne pas toujours fonctionner comme prévu. Si vous avez accès à l'un de ces dispositifs, n'hésitez pas à reporter les bogues sur GitHub.
Dans ce guide, vous apprendrez :
Comment écrire votre logique d'entrée pour supporter à la fois les entrées du clavier et de contrôleur.
Comment les contrôleurs peuvent se comporter différemment des entrées clavier/souris.
Dépannage des problèmes avec les contrôleurs dans Godot.
Prise en charge de l'entrée universelle
Grâce au système d'actions d'entrée de Godot, Godot permet de prendre en charge à la fois les entrées clavier et manette sans avoir à écrire des chemins de code séparés. Au lieu de coder en dur les touches ou les boutons de la manette dans vos scripts, vous devez créer des actions d'entrée dans les paramètres du projet qui feront ensuite référence aux entrées spécifiées des touches et de la manette.
Les actions de saisie sont expliquées en détail sur la page Utilisation d'InputEvent.
Note
Contrairement à la saisie au clavier, la prise en charge de la saisie à la souris et à la manette pour une action (comme regarder autour de soi dans un jeu à la première personne) nécessitera des chemins de code différents puisqu'ils doivent être traités séparément.
Quelle méthode singleton d’entrée dois-je utiliser ?
Il y a 3 façons d'obtenir une entrée de manière analogique :
Lorsque vous avez deux axes (comme un joystick ou un mouvement WASD) et que vous voulez que les deux axes se comportent comme une seule entrée, utilisez
Input.get_vector():
# `velocity` will be a Vector2 between `Vector2(-1.0, -1.0)` and `Vector2(1.0, 1.0)`.
# This handles deadzone in a correct way for most use cases.
# The resulting deadzone will have a circular shape as it generally should.
var velocity = Input.get_vector("move_left", "move_right", "move_forward", "move_back")
# The line below is similar to `get_vector()`, except that it handles
# the deadzone in a less optimal way. The resulting deadzone will have
# a square-ish shape when it should ideally have a circular shape.
var velocity = Vector2(
Input.get_action_strength("move_right") - Input.get_action_strength("move_left"),
Input.get_action_strength("move_back") - Input.get_action_strength("move_forward")
).limit_length(1.0)
// `velocity` will be a Vector2 between `Vector2(-1.0, -1.0)` and `Vector2(1.0, 1.0)`.
// This handles deadzone in a correct way for most use cases.
// The resulting deadzone will have a circular shape as it generally should.
Vector2 velocity = Input.GetVector("move_left", "move_right", "move_forward", "move_back");
// The line below is similar to `get_vector()`, except that it handles
// the deadzone in a less optimal way. The resulting deadzone will have
// a square-ish shape when it should ideally have a circular shape.
Vector2 velocity = new Vector2(
Input.GetActionStrength("move_right") - Input.GetActionStrength("move_left"),
Input.GetActionStrength("move_back") - Input.GetActionStrength("move_forward")
).LimitLength(1.0);
Lorsque vous avez un axe qui peut aller dans les deux sens (comme la manette des gaz sur un manche de vol), ou lorsque vous voulez gérer des axes séparés individuellement, utilisez
Input.get_axis():
# `walk` will be a floating-point number between `-1.0` and `1.0`.
var walk = Input.get_axis("move_left", "move_right")
# The line above is a shorter form of:
var walk = Input.get_action_strength("move_right") - Input.get_action_strength("move_left")
// `walk` will be a floating-point number between `-1.0` and `1.0`.
float walk = Input.GetAxis("move_left", "move_right");
// The line above is a shorter form of:
float walk = Input.GetActionStrength("move_right") - Input.GetActionStrength("move_left");
Pour d'autres types d'entrées analogiques, comme le traitement d'un déclencheur ou le traitement d'une direction à la fois, utilisez
Input.get_action_strength():
# `strength` will be a floating-point number between `0.0` and `1.0`.
var strength = Input.get_action_strength("accelerate")
// `strength` will be a floating-point number between `0.0` and `1.0`.
float strength = Input.GetActionStrength("accelerate");
Pour les entrées numériques/booléennes non analogiques (uniquement les valeurs "pressed" our "not pressed"), comme les boutons de la manette, les boutons de la souris ou les touches du clavier, utilisez Input.is_action_pressed() :
# `jumping` will be a boolean with a value of `true` or `false`.
var jumping = Input.is_action_pressed("jump")
// `jumping` will be a boolean with a value of `true` or `false`.
bool jumping = Input.IsActionPressed("jump");
Note
If you need to know whether an input was just pressed in the previous
frame, use Input.is_action_just_pressed() instead of
Input.is_action_pressed(). Unlike Input.is_action_pressed() which
returns true as long as the input is
held, Input.is_action_just_pressed() will only return true for one
frame after the button has been pressed.
Vibration
Vibration (also called haptic feedback) can be used to enhance the feel of a game. For instance, in a racing game, you can convey the surface the car is currently driving on through vibration, or create a sudden vibration on a crash.
Use the Input singleton's start_joy_vibration method to start vibrating a gamepad. Use stop_joy_vibration to stop vibration early (useful if no duration was specified when starting).
On mobile devices, you can also use
vibrate_handheld to vibrate the
device itself (independently from the gamepad). On Android, this requires the
VIBRATE permission to be enabled in the Android export preset before
exporting the project.
Note
Vibration can be uncomfortable for certain players. Make sure to provide an in-game slider to disable vibration or reduce its intensity.
Différences entre les entrées clavier/souris et contrôleur
Si vous avez l’habitude de gérer les entrées au clavier et à la souris, vous pouvez être surpris par la façon dont les contrôleurs gèrent des situations spécifiques.
Zone morte
Contrairement aux claviers et aux souris, les contrôleurs offrent des axes avec des entrées analogiques. L'avantage des entrées analogiques est qu'elles offrent une flexibilité supplémentaire pour les actions. Contrairement aux entrées numériques qui ne peuvent fournir que des forces de 0.0 et 1.0, une entrée analogique peut fournir n'importe quelle force entre 0.0 et 1.0. L'inconvénient est que sans un système de zone morte, l'intensité d'un axe analogique ne sera jamais égale à 0.0 en raison de la façon dont le contrôleur est physiquement construit. Au lieu de cela, il s'attardera à une valeur faible telle que 0.062. Ce phénomène est connu sous le nom de drifting et peut être plus visible sur les contrôleurs anciens ou défectueux.
Prenons un jeu de course comme exemple concret. Grâce aux entrées analogiques, nous pouvons diriger lentement la voiture dans une direction ou une autre. Cependant, sans un système de zone morte, la voiture se dirigerait lentement d'elle-même, même si le joueur ne touche pas le joystick. C'est parce que la force de l'axe directionnel ne sera pas égale à 0.0 quand nous l'attendons. Puisque nous ne voulons pas que notre voiture se dirige toute seule dans ce cas, nous définissons une valeur de "zone morte" de 0.2 qui ignorera toute entrée dont la force est inférieure à 0.2. La valeur idéale de la zone morte est suffisamment élevée pour ignorer l'entrée causée par la dérive du joystick, mais suffisamment basse pour ne pas ignorer l'entrée réelle du joueur.
Godot features a built-in deadzone system to tackle this problem. The default
value is 0.5, but you can adjust it on a per-action basis in the Project
Settings' Input Map tab. For Input.get_vector(), the deadzone can be
specified as an optional 5th parameter. If not specified, it will calculate the
average deadzone value from all of the actions in the vector.
Événements "Echo"
Contrairement à la saisie au clavier, le fait de maintenir enfoncé un bouton de contrôleur, comme la direction du D-pad, ne génère not d'événements de saisie répétés à intervalles fixes (également appelés événements "écho"). En effet, le système d'exploitation n'envoie jamais d'événements "écho" pour les entrées de la manette.
Si vous voulez que les boutons du contrôleur envoient des événements d'écho, vous devrez générer des objets InputEvent par code et les analyser à l'aide de Input.parse_input_event() à intervalles réguliers. Ceci peut être accompli à l'aide d'un nœud Timer.
Window focus
Unlike keyboard input, controller inputs can by default be seen by all windows on the operating system, including unfocused windows.
While this is useful for third-party split screen functionality, it can also have adverse effects. Players may accidentally send controller inputs to the running project while interacting with another window.
If you wish to ignore controller input events when the project isn't focused,
set ProjectSettings.input_devices/joypads/ignore_joypad_on_unfocused_application to true.
Alternatively, you can also set Input.ignore_joypad_on_unfocused_application to true.
Prévention de l'économie d'énergie
Unlike keyboard and mouse input, controller inputs do not inhibit sleep and power saving measures (such as turning off the screen after a certain amount of time has passed).
To combat this, Godot enables power saving prevention by default when a project is running. If you notice the system is turning off its display when playing with a gamepad, check the value of Display > Window > Energy Saving > Keep Screen On in the Project Settings.
Dépannage
Voir aussi
Vous pouvez consulter la liste des problèmes connus avec le support des contrôleurs sur GitHub.
Mon contrôleur n'est pas reconnu par Godot.
First, check that your controller is recognized by other applications. You can use the Gamepad Tester website to confirm that your controller is recognized.
On Windows Godot only supports up to 4 controllers at a time. This is because Godot uses the XInput API, which is limited to supporting 4 controllers at once. Additional controllers above this limit are ignored by Godot.
Mon contrôleur fonctionne sur une plate-forme donnée, mais pas sur une autre plate-forme.
Linux
If you're using a self-compiled engine binary, make sure it was compiled with
udev support. This is enabled by default, but it is possible to disable udev
support by specifying udev=no on the SCons command line. If you're using an
engine binary supplied by a Linux distribution, double-check whether it was
compiled with udev support.
Controllers can still work without udev support, but it is less reliable as regular polling must be used to check for controllers being connected or disconnected during gameplay (hotplugging).
Android
As described at the top of the page, controller support on mobile platforms relies on a custom implementation instead of using SDL for input. This means controller support may be less reliable than on desktop platforms.
Support for SDL-based controller input on mobile platforms is planned in a future release.
Web
Web controller support is often less reliable compared to "native" platforms. The quality of controller support tends to vary wildly across browsers. As a result, you may have to instruct your players to use a different browser if they can't get their controller to work.
Like for mobile platforms, support for SDL-based controller input on the web platform is planned in a future release.