Input examples

    Note

    For a detailed overview of how Godot’s input event system works, see .

    Events versus polling

    Sometimes you want your game to respond to a certain input event - pressing the “jump” button, for example. For other situations, you might want something to happen as long as a key is pressed, such as movement. In the first case, you can use the function, which will be called whenever an input event occurs. In the second case, Godot provides the Input singleton, which you can use to query the state of an input.

    Examples:

    GDScript

    C#

    1. public override void _Input(InputEvent inputEvent)
    2. {
    3.     if (inputEvent.IsActionPressed("jump"))
    4.     {
    5.         Jump();
    6.     }
    7. }
    9. public override void _PhysicsProcess(float delta)
    10. {
    11.     if (Input.IsActionPressed("move_right"))
    12.     {
    13.         // Move as long as the key/button is pressed.
    14.         position.x += speed * delta;
    15.     }
    16. }

    This gives you the flexibility to mix-and-match the type of input processing you do.

    For the remainder of this tutorial, we’ll focus on capturing individual events in _input().

    Input events are objects that inherit from . Depending on the event type, the object will contain specific properties related to that event. To see what events actually look like, add a Node and attach the following script:

    GDScript

    C#

    1. extends Node
    4. func _input(event):
    5.     print(event.as_text())
    1. using Godot;
    2. using System;
    4. public class Node : Godot.Node
    5. {
    6.     public override void _Input(InputEvent inputEvent)
    7.     {
    8.         GD.Print(inputEvent.AsText());
    9.     }
    10. }

    As you press keys, move the mouse, and perform other inputs, you’ll see each event scroll by in the output window. Here’s an example of the output:

    1. A
    2. InputEventMouseMotion : button_mask=0, position=(108, 108), relative=(26, 1), speed=(164.152496, 159.119843), pressure=(0), tilt=(0, 0)
    3. InputEventMouseButton : button_index=BUTTON_LEFT, pressed=true, position=(108, 107), button_mask=1, doubleclick=false
    4. InputEventMouseButton : button_index=BUTTON_LEFT, pressed=false, position=(108, 107), button_mask=0, doubleclick=false
    5. S
    6. F
    7. Alt
    8. InputEventMouseMotion : button_mask=0, position=(108, 107), relative=(0, -1), speed=(164.152496, 159.119843), pressure=(0), tilt=(0, 0)

    As you can see, the results are very different for the different types of input. Key events are even printed as their key symbols. For example, let’s consider InputEventMouseButton. It inherits from the following classes:

    • - the base class for all input events
    • InputEventMouse - adds mouse event properties, such as position
    • - contains the index of the button that was pressed, whether it was a double-click, etc.

    Tip

    You can encounter errors if you try to access a property on an input type that doesn’t contain it - calling position on InputEventKey for example. To avoid this, make sure to test the event type first:

    GDScript

    C#

    1. public override void _Input(InputEvent inputEvent)
    2. {
    3.     if (inputEvent is InputEventMouseButton mouseEvent)
    4.     {
    5.         GD.Print($"mouse button event at {mouseEvent.Position}");
    6.     }
    7. }

    InputMap

    The InputMap is the most flexible way to handle a variety of inputs. You use this by creating named input actions, to which you can assign any number of input events, such as keypresses or mouse clicks. A new Godot project includes a number of default actions already defined. To see them, and to add your own, open Project -> Project Settings and select the InputMap tab:

    Once you’ve defined your actions, you can process them in your scripts using and is_action_released() by passing the name of the action you’re looking for:

    GDScript

    C#

    1. func _input(event):
    2.     if event.is_action_pressed("my_action"):
    3.         print("my_action occurred!")
    1. public override void _Input(InputEvent inputEvent)
    2. {
    3.     if (inputEvent.IsActionPressed("my_action"))
    4.     {
    5.         GD.Print("my_action occurred!");
    6.     }
    7. }

    Keyboard events are captured in . While it’s recommended to use input actions instead, there may be cases where you want to specifically look at key events. For this example, let’s check for the T:

    GDScript

    C#

    1. func _input(event):
    2.     if event is InputEventKey and event.pressed:
    3.         if event.scancode == KEY_T:
    4.             print("T was pressed")

    Tip

    See @GlobalScope_KeyList for a list of scancode constants.

    Modifier properties are inherited from . This allows you to check for modifier combinations using boolean properties. Let’s imagine you want one thing to happen when the T is pressed, but something different when it’s Shift + T:

    C#

    1. func _input(event):
    2.     if event is InputEventKey and event.pressed:
    3.         if event.scancode == KEY_T:
    4.             if event.shift:
    5.                 print("Shift+T was pressed")
    6.             else:
    7.                 print("T was pressed")
    1. public override void _Input(InputEvent inputEvent)
    2. {
    3.     if (inputEvent is InputEventKey keyEvent && keyEvent.Pressed)
    4.     {
    5.         switch ((KeyList)keyEvent.Scancode)
    6.         {
    7.             case KeyList.T:
    8.                 GD.Print(keyEvent.Shift ? "Shift+T was pressed" : "T was pressed");
    9.                 break;
    10.         }
    11.     }
    12. }

    Tip

    See @GlobalScope_KeyList for a list of scancode constants.

    Mouse events

    Mouse events stem from the class, and are separated into two types: InputEventMouseButton and . Note that this means that all mouse events will contain a position property.

    Capturing mouse buttons is very similar to handling key events. @GlobalScope_ButtonList contains a list of BUTTON_* constants for each possible button, which will be reported in the event’s button_index property. Note that the scrollwheel also counts as a button - two buttons, to be precise, with both BUTTON_WHEEL_UP and BUTTON_WHEEL_DOWN being separate events.

    GDScript

    C#

    1. func _input(event):
    2.     if event is InputEventMouseButton:
    3.         if event.button_index == BUTTON_LEFT and event.pressed:
    4.             print("Left button was clicked at ", event.position)
    5.         if event.button_index == BUTTON_WHEEL_UP and event.pressed:
    6.             print("Wheel up")
    1. public override void _Input(InputEvent inputEvent)
    2. {
    3.     if (inputEvent as InputEventMouseButton mouseEvent && mouseEvent.Pressed)
    4.         switch ((ButtonList)mouseEvent.ButtonIndex)
    6.             case ButtonList.Left:
    7.                 GD.Print($"Left button was clicked at {mouseEvent.Position}");
    8.                 break;
    9.             case ButtonList.WheelUp:
    10.                 GD.Print("Wheel up");
    11.                 break;
    12.         }
    13.     }
    14. }

    events occur whenever the mouse moves. You can find the move’s distance with the relative property.

    Here’s an example using mouse events to drag-and-drop a Sprite node:

    GDScript

    C#

    1. using Godot;
    2. using System;
    4. public class Node2D : Godot.Node2D
    5. {
    6.     private bool dragging = false;
    7.     private int clickRadius = 32; // Size of the sprite.
    9.     public override void _Input(InputEvent inputEvent)
    10.     {
    11.         Sprite sprite = GetNodeOrNull<Sprite>("Sprite");
    12.         if (sprite == null)
    13.         {
    14.             return; // No suitable node was found.
    15.         }
    17.         if (inputEvent is InputEventMouseButton mouseEvent && (ButtonList)mouseEvent.ButtonIndex == ButtonList.Left)
    18.         {
    19.             if ((mouseEvent.Position - sprite.Position).Length() < clickRadius)
    20.             {
    21.                 // Start dragging if the click is on the sprite.
    22.                 if (!dragging && mouseEvent.Pressed)
    23.                 {
    24.                     dragging = true;
    25.                 }
    26.             }
    27.             // Stop dragging if the button is released.
    28.             if (dragging && !mouseEvent.Pressed)
    29.             {
    30.                 dragging = false;
    31.             }
    32.         }
    33.         else
    34.         {
    35.             if (inputEvent is InputEventMouseMotion motionEvent && dragging)
    36.             {
    37.                 // While dragging, move the sprite with the mouse.
    38.                 sprite.Position = motionEvent.Position;
    39.             }
    40.         }
    41. }

    If you are using a touchscreen device, you can generate touch events. is equivalent to a mouse click event, and InputEventScreenDrag works much the same as mouse motion.

    Tip

    To test your touch events on a non-touchscreen device, open Project Settings and go to the “Input Devices/Pointing” section. Enable “Emulate Touch From Mouse” and your project will interpret mouse clicks and motion as touch events.