Controllers, gamepads, and joysticks

Controllers are supported on Windows, macOS, Linux, Android, iOS, and HTML5.

Note that more specialized devices such as steering wheels, rudder pedals and HOTAS are less tested and may not always work as expected. Overriding force feedback for those devices is also not implemented yet. If you have access to one of those devices, don’t hesitate to .

In this guide, you will learn:

How to write your input logic to support both keyboard and controller inputs.
How controllers can behave differently from keyboard/mouse input.

Thanks to Godot’s input action system, Godot makes it possible to support both keyboard and controller input without having to write separate code paths. Instead of hardcoding keys or controller buttons in your scripts, you should create input actions in the Project Settings which will then refer to specified key and controller inputs.

Input actions are explained in detail on the page.

Note

Unlike keyboard input, supporting both mouse and controller input for an action (such as looking around in a first-person game) will require different code paths since these have to be handled separately.

When you have two axes (such as joystick or WASD movement) and want both axes to behave as a single input, use :

GDScript C#

// `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")).Clamped(1);

When you have one axis that can go both ways (such as a throttle on a flight stick), or when you want to handle separate axes individually, use Input.get_axis():

GDScript C#

# `walk` will be a floating-point number between `-1.0` and `1.0`.
var walk = Input.get_action_strength("move_right") - Input.get_action_strength("move_left")

For other types of analog input, such as handling a trigger or handling one direction at a time, use Input.get_action_strength():

GDScript C#

# `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");

For non-analog digital/boolean input (only “pressed” or “not pressed” values), such as controller buttons, mouse buttons or keyboard keys, use Input.is_action_pressed():

GDScript

// `jumping` will be a boolean with a value of `true` or `false`.
bool jumping = Input.IsActionPressed("jump");

In Godot versions before 3.4, such as 3.3, Input.get_vector() and Input.get_axis() aren’t available. Only Input.get_action_strength() and Input.is_action_pressed() are available in Godot 3.3.

If you’re used to handling keyboard and mouse input, you may be surprised by how controllers handle specific situations.

Dead zone

Unlike keyboards and mice, controllers offer axes with analog inputs. The upside of analog inputs is that they offer additional flexibility for actions. Unlike digital inputs which can only provide strengths of 0.0 and , an analog input can provide any strength between 0.0 and 1.0. The downside is that without a deadzone system, an analog axis’ strength will never be equal to 0.0 due to how the controller is physically built. Instead, it will linger at a low value such as 0.062. This phenomenon is known as drifting and can be more noticeable on old or faulty controllers.

Let’s take a racing game as a real-world example. Thanks to analog inputs, we can steer the car slowly in one direction or another. However, without a deadzone system, the car would slowly steer by itself even if the player isn’t touching the joystick. This is because the directional axis strength won’t be equal to 0.0 when we expect it to. Since we don’t want our car to steer by itself in this case, we define a “dead zone” value of 0.2 which will ignore all input whose strength is lower than 0.2. An ideal dead zone value is high enough to ignore the input caused by joystick drifting, but is low enough to not ignore actual input from the player.

Unlike keyboard input, holding down a controller button such as a D-pad direction will not generate repeated input events at fixed intervals (also known as “echo” events). This is because the operating system never sends “echo” events for controller input in the first place.

If you want controller buttons to send echo events, you will have to generate InputEvent objects by code and parse them using at regular intervals. This can be accomplished with the help of a Timer node.

My controller isn’t recognized by 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.

If buttons are incorrectly mapped, this may be due to an erroneous mapping from the SDL game controller database. You can contribute an updated mapping to be included in the next Godot version by opening a pull request on the linked repository.

There are many ways to create mappings. One option is to use the mapping wizard in the . Once you have a working mapping for your controller, you can test it by defining the SDL_GAMECONTROLLERCONFIG environment variable before running Godot:

Linux/macOSWindows (cmd)Windows (powershell)

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

$env:SDL_GAMECONTROLLERCONFIG="your:mapping:here"

To test mappings on non-desktop platforms or to distribute your project with additional controller mappings, you can add them by calling Input.add_joy_mapping() as early as possible in a script’s function.

My controller works on a given platform, but not on another platform.

Linux

Prior to Godot 3.3, official Godot binaries were compiled with udev support but self-compiled binaries were compiled without udev support unless udev=yes was passed on the SCons command line. This made controller hotplugging support unavailable in self-compiled binaries.

HTML5

Also, note that controller support was significantly improved in Godot 3.3 and later.