Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Contrôleurs, manettes de jeu et joysticks

Godot prend en charge des centaines de modèles de contrôleurs grâce à la SDL game controller database, alimentée par la communauté.

Les contrôleurs(manettes, etc) sont pris en charge sur Windows, macOS, Linux, Android, iOS et HTML5.

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)
  • 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")
  • 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")

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")

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.

Dans les versions de Godot antérieures à 3.4, comme la 3.3, Input.get_vector() et Input.get_axis() ne sont pas disponibles. Seuls Input.get_action_strength() et Input.is_action_pressed() sont disponibles dans Godot 3.3.

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 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 events when the project window isn't focused, you will need to create an autoload called Focus with the following script and use it to check all your inputs:

# Focus.gd
extends Node

var focused := true

func _notification(what: int) -> void:
    match what:
        NOTIFICATION_APPLICATION_FOCUS_OUT:
            focused = false
        NOTIFICATION_APPLICATION_FOCUS_IN:
            focused = true


func input_is_action_pressed(action: StringName) -> bool:
    if focused:
        return Input.is_action_pressed(action)

    return false


func event_is_action_pressed(event: InputEvent, action: StringName) -> bool:
    if focused:
        return event.is_action_pressed(action)

    return false

Then, instead of using Input.is_action_pressed(action), use Focus.input_is_action_pressed(action) where action is the name of the input action. Also, instead of using event.is_action_pressed(action), use Focus.event_is_action_pressed(event, action) where event is an InputEvent reference and action is the name of the input action.

Power saving prevention

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.

On Linux, power saving prevention requires the engine to be able to use D-Bus. Check whether D-Bus is installed and reachable if running the project within a Flatpak, as sandboxing restrictions may make this impossible by default.

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.

Tout d'abord, vérifiez que votre contrôleur est reconnu par les autres applications. Vous pouvez utiliser le site Gamepad Tester pour confirmer que votre contrôleur est reconnu.

Les boutons ou les axes de ma manette sont mal affectés.

First, if your controller provides some kind of firmware update utility, make sure to run it to get the latest fixes from the manufacturer. For instance, Xbox One and Xbox Series controllers can have their firmware updated using the Xbox Accessories app. (This application only runs on Windows, so you have to use a Windows machine or a Windows virtual machine with USB support to update the controller's firmware.) After updating the controller's firmware, unpair the controller and pair it again with your PC if you are using the controller in wireless mode.

Si les boutons sont incorrectement mappés, cela peut être dû à un mappage erroné de la base de données SDL du contrôleur de jeu. Vous pouvez contribuer à un mappage mis à jour qui sera inclus dans la prochaine version de Godot en ouvrant une demande de pull sur le dépôt lié.

Il y a plusieurs façons de créer des mappings. Une option consiste à utiliser l'assistant de mappage dans la official Joypads demo. Une fois que vous avez un mappage fonctionnel pour votre contrôleur, vous pouvez le tester en définissant la variable d'environnement SDL_GAMECONTROLLERCONFIG avant de lancer Godot :

export SDL_GAMECONTROLLERCONFIG="your:mapping:here"
./path/to/godot.x86_64

Pour tester les mappings sur des plateformes autres que l'ordinateur de bureau ou pour distribuer votre projet avec des mappings de contrôleurs supplémentaires, vous pouvez les ajouter en appelant Input.add_joy_mapping() le plus tôt possible dans la fonction _ready() d'un script.

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).

HTML5

La prise en charge des contrôleurs HTML5 est souvent moins fiable que celle des plateformes "natives". La qualité de la prise en charge des contrôleurs a tendance à varier énormément d'un navigateur à l'autre. Par conséquent, vous devrez peut-être demander à vos joueurs d'utiliser un autre navigateur s'ils ne parviennent pas à faire fonctionner leur contrôleur.