.. _doc_input_examples: Input examples ============== Introduction ------------ In this tutorial, you'll learn how to use Godot's `InputEvent` system to capture player input. There are many different types of input your game may use - keyboard, gamepad, mouse, etc. - and many different ways to turn those inputs into actions in your game. This document will show you some of the most common scenarios, which you can use as starting points for your own projects. .. note:: For a detailed overview of how Godot's input event system works, see `doc_inputevent`. 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 `_input()` 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 GDScript ``` func _input(event): if event.is_action_pressed("jump"): jump() func _physics_process(delta): if Input.is_action_pressed("move_right"): # Move as long as the key/button is pressed. position.x += speed * delta ``` 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 ------------ Input events are objects that inherit from `InputEvent`. 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 GDScript ``` extends Node func _input(event): print(event.as_text()) ``` 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: :: A InputEventMouseMotion : button_mask=0, position=(108, 108), relative=(26, 1), speed=(164.152496, 159.119843), pressure=(0), tilt=(0, 0) InputEventMouseButton : button_index=BUTTON_LEFT, pressed=true, position=(108, 107), button_mask=1, doubleclick=false InputEventMouseButton : button_index=BUTTON_LEFT, pressed=false, position=(108, 107), button_mask=0, doubleclick=false S F Alt 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: - `InputEvent` - the base class for all input events - `InputEventWithModifiers` - adds the ability to check if modifiers are pressed, such as :kbd:`Shift` or :kbd:`Alt`. - `InputEventMouse` - adds mouse event properties, such as `position` - `InputEventMouseButton` - contains the index of the button that was pressed, whether it was a double-click, etc. .. tip:: It's a good idea to keep the class reference open while you're working with events so you can check the event type's available properties and methods. 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 GDScript ``` func _input(event): if event is InputEventMouseButton: print("mouse button event at ", event.position) ``` 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: ![](img/inputs_inputmap.png) Capturing actions ~~~~~~~~~~~~~~~~~ Once you've defined your actions, you can process them in your scripts using `is_action_pressed()` and `is_action_released()` by passing the name of the action you're looking for: gdscript GDScript ``` func _input(event): if event.is_action_pressed("my_action"): print("my_action occurred!") ``` Keyboard events --------------- Keyboard events are captured in `InputEventKey`. 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 :kbd:`T`: gdscript GDScript ``` func _input(event): if event is InputEventKey and event.pressed: if event.scancode == KEY_T: print("T was pressed") ``` .. tip:: See `@GlobalScope_KeyList