InputEvent

Here is a quick example, closing your game if the escape key is hit:

GDScript

C#

{
    if (@event is InputEventKey eventKey)
        if (eventKey.Pressed && eventKey.Scancode == (int)KeyList.Escape)
}

However, it is cleaner and more flexible to use the provided feature, which allows you to define input actions and assign them different keys. This way, you can define multiple keys for the same action (e.g. they keyboard escape key and the start button on a gamepad). You can then more easily change this mapping in the project settings without updating your code, and even build a key mapping feature on top of it to allow your game to change the key mapping at runtime!

You can set up your InputMap under Project > Project Settings > Input Map and then use those actions like this:

GDScript

C#

{
    if (Input.IsActionPressed("ui_right"))
    {
        // Move right.
    }

But SceneTree does not know what to do with the event, so it will give it to the viewports, starting by the “root” Viewport (the first node of the scene tree). Viewport does quite a lot of stuff with the received input, in order:

1. First of all, the standard function will be called in any node that overrides it (and hasn’t disabled input processing with Node.set_process_input()). If any function consumes the event, it can call , and the event will not spread any more. This ensures that you can filter all events of interest, even before the GUI. For gameplay input, Node._unhandled_input() is generally a better fit, because it allows the GUI to intercept the events.
2. If so far no one consumed the event, the unhandled input callback will be called if overridden (and not disabled with ). If any function consumes the event, it can call SceneTree.set_input_as_handled(), and the event will not spread any more. The unhandled input callback is ideal for full-screen gameplay events, so they are not received when a GUI is active.
3. If no one wanted the event so far, and a is assigned to the Viewport, a ray to the physics world (in the ray direction from the click) will be cast. If this ray hits an object, it will call the CollisionObject._input_event() function in the relevant physics object (bodies receive this callback by default, but areas do not. This can be configured through properties).
4. Finally, if the event was unhandled, it will be passed to the next Viewport in the tree, otherwise it will be ignored.

When sending events to all listening nodes within a scene, the viewport will do so in a reverse depth-first order: Starting with the node at the bottom of the scene tree, and ending at the root node:

GUI events also travel up the scene tree but, since these events target specific Controls, only direct ancestors of the targeted Control node receive the event.

In accordance with Godot’s node-based design, this enables specialized child nodes to handle and consume particular events, while their ancestors, and ultimately the scene root, can provide more generalized behavior if needed.

InputEvent is just a base built-in type, it does not represent anything and only contains some basic information, such as event ID (which is increased for each event), device index, etc.

An InputEvent may or may not represent a pre-defined action. Actions are useful because they abstract the input device when programming the game logic. This allows for:

• The same code to work on different devices with different inputs (e.g., keyboard on PC, Joypad on console).
• Input to be reconfigured at run-time.

Actions can be created from the Project Settings menu in the Actions tab.

Any event has the methods , InputEvent.is_pressed() and .

Alternatively, it may be desired to supply the game back with an action from the game code (a good example of this is detecting gestures). The Input singleton has a method for this: Input.parse_input_event(). You would normally use it like this:

GDScript

C#

var ev = new InputEventAction();
// Set as move_left, pressed.
ev.SetAction("move_left");
ev.SetPressed(true);

Customizing and re-mapping input from code is often desired. If your whole workflow depends on actions, the singleton is ideal for reassigning or creating different actions at run-time. This singleton is not saved (must be modified manually) and its state is run from the project settings (project.godot). So any dynamic system of this type needs to store settings in the way the programmer best sees fit.