Introduction

In this tutorial, you'll learn how to use Godot'sInputEventsystem to capture player input. There are many different types of input yourgame may use - keyboard, gamepad, mouse, etc. - and many different ways toturn those inputs into actions in your game. This document will show you someof the most common scenarios, which you can use as starting points for yourown projects.

Events versus polling

Sometimes you want your game to respond to a certain input event - pressingthe "jump" button, for example. For other situations, you might want somethingto happen as long as a key is pressed, such as movement. In the first case,you can use the_input() function, which will be called whenever an inputevent occurs. In the second case, Godot provides theInputsingleton, which you can use to query the state of an input.

Examples:

func_input(event):ifevent.is_action_pressed("jump"):jump()func_physics_process(delta):ifInput.is_action_pressed("move_right"):# Move as long as the key/button is pressed.position.x+=speed*delta

publicoverridevoid_Input(InputEvent@event){if(@event.IsActionPressed("jump")){Jump();}}publicoverridevoid_PhysicsProcess(doubledelta){if(Input.IsActionPressed("move_right")){// Move as long as the key/button is pressed.position.X+=speed*(float)delta;}}

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

For the remainder of this tutorial, we'll focus on capturing individualevents in_input().

Input events

Input events are objects that inherit fromInputEvent.Depending on the event type, the object will contain specific propertiesrelated to that event. To see what events actually look like, add a Node andattach the following script:

extendsNodefunc_input(event):print(event.as_text())

usingGodot;publicpartialclassNode:Godot.Node{publicoverridevoid_Input(InputEvent@event){GD.Print(@event.AsText());}}

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

AMousemotionatposition((971,5))withvelocity((0,0))RightMouseButtonMousemotionatposition((870,243))withvelocity((0.454937,-0.454937))LeftMouseButtonMouseWheelUpABShiftAlt+ShiftAltShift+TMousemotionatposition((868,242))withvelocity((-2.134768,2.134768))

As you can see, the results are very different for the different types ofinput. Key events are even printed as their key symbols. For example, let'sconsiderInputEventMouseButton.It inherits from the following classes:

• InputEvent - the base class for all input events

• InputEventWithModifiers - adds the ability to check if modifiers are pressed, such asShift orAlt.

• InputEventMouse - adds mouse event properties, such asposition

• InputEventMouseButton - contains the index of the button that was pressed, whether it was a double-click, etc.

You can encounter errors if you try to access a property on an input type thatdoesn't contain it - callingposition onInputEventKey for example. Toavoid this, make sure to test the event type first:

func_input(event):ifeventisInputEventMouseButton:print("mouse button event at ",event.position)

publicoverridevoid_Input(InputEvent@event){if(@eventisInputEventMouseButtonmouseEvent){GD.Print("mouse button event at ",mouseEvent.Position);}}

InputMap

TheInputMap is the most flexible way to handle avariety of inputs. You use this by creating named inputactions, to whichyou can assign any number of input events, such as keypresses or mouse clicks.To see them, and to add your own, open Project -> Project Settings and selectthe InputMap tab:

func_input(event):ifevent.is_action_pressed("my_action"):print("my_action occurred!")

publicoverridevoid_Input(InputEvent@event){if(@event.IsActionPressed("my_action")){GD.Print("my_action occurred!");}}

Keyboard events

Keyboard events are captured inInputEventKey.While it's recommended to use input actions instead, there may be cases whereyou want to specifically look at key events. For this example, let's check fortheT:

func_input(event):ifeventisInputEventKeyandevent.pressed:ifevent.keycode==KEY_T:print("T was pressed")

publicoverridevoid_Input(InputEvent@event){if(@eventisInputEventKeykeyEvent&&keyEvent.Pressed){if(keyEvent.Keycode==Key.T){GD.Print("T was pressed");}}}

func_input(event):ifeventisInputEventKeyandevent.pressed:ifevent.keycode==KEY_T:ifevent.shift_pressed:print("Shift+T was pressed")else:print("T was pressed")

publicoverridevoid_Input(InputEvent@event){if(@eventisInputEventKeykeyEvent&&keyEvent.Pressed){switch(keyEvent.Keycode){caseKey.T:GD.Print(keyEvent.ShiftPressed?"Shift+T was pressed":"T was pressed");break;}}}

Mouse events

Mouse events stem from theInputEventMouse class, andare separated into two types:InputEventMouseButtonandInputEventMouseMotion. Note that thismeans that all mouse events will contain aposition property.

func_input(event):ifeventisInputEventMouseButton:ifevent.button_index==MOUSE_BUTTON_LEFTandevent.pressed:print("Left button was clicked at ",event.position)ifevent.button_index==MOUSE_BUTTON_WHEEL_UPandevent.pressed:print("Wheel up")

publicoverridevoid_Input(InputEvent@event){if(@eventisInputEventMouseButtonmouseEvent&&mouseEvent.Pressed){switch(mouseEvent.ButtonIndex){caseMouseButton.Left:GD.Print($"Left button was clicked at {mouseEvent.Position}");break;caseMouseButton.WheelUp:GD.Print("Wheel up");break;}}}

extendsNodevardragging=falsevarclick_radius=32# Size of the sprite.func_input(event):ifeventisInputEventMouseButtonandevent.button_index==MOUSE_BUTTON_LEFT:if(event.position-$Sprite2D.position).length()<click_radius:# Start dragging if the click is on the sprite.ifnotdraggingandevent.pressed:dragging=true# Stop dragging if the button is released.ifdraggingandnotevent.pressed:dragging=falseifeventisInputEventMouseMotionanddragging:# While dragging, move the sprite with the mouse.$Sprite2D.position=event.position

usingGodot;publicpartialclassMyNode2D:Node2D{privatebool_dragging=false;privateint_clickRadius=32;// Size of the sprite.publicoverridevoid_Input(InputEvent@event){Sprite2Dsprite=GetNodeOrNull<Sprite2D>("Sprite2D");if(sprite==null){return;// No suitable node was found.}if(@eventisInputEventMouseButtonmouseEvent&&mouseEvent.ButtonIndex==MouseButton.Left){if((mouseEvent.Position-sprite.Position).Length()<_clickRadius){// Start dragging if the click is on the sprite.if(!_dragging&&mouseEvent.Pressed){_dragging=true;}}// Stop dragging if the button is released.if(_dragging&&!mouseEvent.Pressed){_dragging=false;}}else{if(@eventisInputEventMouseMotionmotionEvent&&_dragging){// While dragging, move the sprite with the mouse.sprite.Position=motionEvent.Position;}}}}

Touch events

If you are using a touchscreen device, you can generate touch events.InputEventScreenTouch is equivalent toa mouse click event, andInputEventScreenDragworks much the same as mouse motion.