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