What is it?

Managing input is usually complex, no matter the OS or platform. To easethis a little, a special built-in type is provided,InputEvent.This datatype can be configured to contain several types of inputevents. Input events travel through the engine and can be received inmultiple locations, depending on the purpose.

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

func_unhandled_input(event):ifeventisInputEventKey:ifevent.pressedandevent.keycode==KEY_ESCAPE:get_tree().quit()

publicoverridevoid_UnhandledInput(InputEvent@event){if(@eventisInputEventKeyeventKey)if(eventKey.Pressed&&eventKey.Keycode==Key.Escape)GetTree().Quit();}

However, it is cleaner and more flexible to use the providedInputMap 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. the 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 underProject > Project Settings > Input Map and then use those actions like this:

func_process(delta):ifInput.is_action_pressed("ui_right"):# Move right.

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

How does it work?

Every input event is originated from the user/player (though it'spossible to generate an InputEvent and feed them back to the engine,which is useful for gestures). The DisplayServer for each platform will readevents from the operating system, then feed them to the rootWindow.

The window'sViewport does quite a lot of stuff with thereceived input, in order:

1. If the Viewport is embedding Windows, the Viewport tries to interpret the event in itscapability as a Window-Manager (e.g. for resizing or moving Windows).

2. Next if an embedded Window is focused, the event is sent to that Window and processed inthe Windows Viewport and afterwards treated as handled. If no embedded Window is focused,the event is sent to the nodes of the current viewport in the following order.

3. First of all, the standardNode._input() functionwill be called in any node that overrides it (and hasn't disabled input processing withNode.set_process_input()).If any function consumes the event, it can callViewport.set_input_as_handled(), and the event willnot 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.

4. Second, it will try to feed the input to the GUI, and see if anycontrol can receive it. If so, theControl will be called via thevirtual functionControl._gui_input() and the signal"gui_input" will be emitted (this function is re-implementable byscript by inheriting from it). If the control wants to "consume" theevent, it will callControl.accept_event() and the event willnot spread any more. Use theControl.mouse_filterproperty to control whether aControl is notifiedof mouse events viaControl._gui_input()callback, and whether these events are propagated further.

5. If so far no one consumed the event, theNode._shortcut_input() callbackwill be called if overridden (and not disabled withNode.set_process_shortcut_input()).This happens only forInputEventKey,InputEventShortcut andInputEventJoypadButton.If any function consumes the event, it can callViewport.set_input_as_handled(), and theevent will not spread any more. The shortcut input callback is ideal for treating events that are intended as shortcuts.

6. If so far no one consumed the event, theNode._unhandled_key_input() callbackwill be called if overridden (and not disabled withNode.set_process_unhandled_key_input()).This happens only if the event is anInputEventKey.If any function consumes the event, it can callViewport.set_input_as_handled(), and theevent will not spread any more. The unhandled key input callback is ideal for key events.

7. If so far no one consumed the event, theNode._unhandled_input() callbackwill be called if overridden (and not disabled withNode.set_process_unhandled_input()).If any function consumes the event, it can callViewport.set_input_as_handled(), and theevent 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.

8. If no one wanted the event so far, andObject Pickingis turned on, the event is used for object picking. For the root viewport, this can also beenabled inProject Settings.In the case of a 3D scene if aCamera3D is assigned to the Viewport, a rayto the physics world (in the ray direction from the click) will be cast. If this ray hits an object,it will call theCollisionObject3D._input_event()function in the relevant physics object.In the case of a 2D scene, conceptually the same happens withCollisionObject2D._input_event().

When sending events to its child and descendant nodes, the viewport will do so, as depicted inthe following graphic, in a reverse depth-first order, starting with the node at the bottom ofthe scene tree, and ending at the root node. Excluded from this process are Windowsand SubViewports.

Since Viewports don't send events to otherSubViewports, one of the followingmethods has to be used:

1. Use aSubViewportContainer, which automaticallysends events to its childSubViewports afterNode._input() orControl._gui_input().

2. Implement event propagation based on the individual requirements.

In accordance with Godot's node-based design, this enablesspecialized child nodes to handle and consume particular events, whiletheir ancestors, and ultimately the scene root, can provide moregeneralized behavior if needed.

Anatomy of an InputEvent

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

There are several specialized types of InputEvent, described in the table below:

Input actions

Input actions are a grouping of zero or more InputEvents into a commonlyunderstood title (for example, the default "ui_left" action grouping both joypad-left input and a keyboard's left arrow key). They are not required to represent anInputEvent but are useful because they abstract various inputs whenprogramming 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 runtime.

• Actions to be triggered programmatically at runtime.

Actions can be created from the Project Settings menu in theInput Maptab and assigned input events.

Any event has the methodsInputEvent.is_action(),InputEvent.is_pressed() andInputEvent.is_echo().

Alternatively, it may be desired to supply the game back with an actionfrom 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:

varev=InputEventAction.new()# Set as ui_left, pressed.ev.action="ui_left"ev.pressed=true# Feedback.Input.parse_input_event(ev)

varev=newInputEventAction();// Set as ui_left, pressed.ev.Action="ui_left";ev.Pressed=true;// Feedback.Input.ParseInputEvent(ev);

InputMap

Customizing and re-mapping input from code is often desired. If yourwhole workflow depends on actions, theInputMap singleton isideal for reassigning or creating different actions at runtime. Thissingleton is not saved (must be modified manually) and its state is runfrom the project settings (project.godot). So any dynamic system of thistype needs to store settings in the way the programmer best sees fit.