Guide to the Godot game engine/Input

In every game, you are able to press a button or tap on the screen for something to happen. This is called reacting to input. There are two ways to do it: using input maps and manually.

Input map
Go to your Project Settings at Project -> Project Settings... and click on the Input Map tab. You will get a list of input actions, like "ui_select". These are the default ones, and can be edited, but not removed.

You can - and should - make your own, however. After where it says "Action:", type a name for an action, like "shoot", or "move_forward". Press the "Add" button next to it. This will create your action.

You will notice that you have no input events associated with it. Press the "+" button next to your new action. You will see these options:


 * Key: Allows you to link any keyboard button.
 * 1) Joy Button: Allows you to link a controller button.
 * 2) Joy Axis: Allows you to link a controller joy-stick movement.
 * 3) Mouse Button: Allows you to link a mouse button.

For touch screen and mouse movement, please see the manual input detection section mentioned below.

There are several ways to detect whether or not they are pressed, and the method you choose depends on what the action is for. The functions below return a boolean, unless otherwise stated, and should be put inside "if" or "while" statements.

The above methods are all called on the singleton. They all accept a single String argument.

.:

The String argument must be the name of an input action defined in the input map.

Manual input detection
Let's say that you want to detect mouse movement or touch screen events, or that the input map won't work because you need input for a tool that you can't guarantee the user of the tool (or yourself) will create the input event.

This is when you need manual input detection. This is like using servers. Manual input detection is a low-level equivalent to the input map that is more complex but gives more power.

The below code moves a 2D sprite when you move your mouse, and ignores all other input.

(event): event : position += event.relative

The below code creates a simple button. is available only to Control derived nodes and runs if focused and you press a key, you pressed it with the mouse or the mouse moves over it.

extends Control signal button_up signal button_down pressed = (event): event   event.button_index == BUTTON_LEFT: event.pressed: .             pressed = event.pressed: pressed: pressed =

The  makes sure other   and   are not called.

There are many input events. They are as follows:
 * InputEventMouse:
 * InputEventMouseButton: Emitted when you click a mouse button. Read with: button_index (BUTTON_* constants), pressed.
 * InputEventMouseMotion: Emitted when you move the mouse. Read with: relative (how much the mouse moved since the last call to input), position (the mouse's new position relative to the top-left of the game window - or the node in "_gui_input" calls).
 * InputEventKey: Emitted when you press a button on the keyboard. Read with: button_index (KEY_* constants), pressed, echo (if true, the button is being held down).
 * InputEventScreen:
 * InputEventScreenTouch: Emitted when you tap the screen. Read with: position (the position you tapped on the screen), pressed (if false, you are untapping the screen).
 * InputEventScreenDrag: Emitted when you drag on the screen. Read with: position (new position), relative (how much the finger moved since the last input call), fingers.
 * InputEventJoy:
 * InputEventJoyButton: Emitted for controller button presses. Read with: pressed, button_index (JOY_* constants).
 * InputEventJoyMotion: Emitted for moving the joy stick. Read with: position, relative.

See more: The InputEvent tutorial.

Input singleton
So reading input is very fun. However, there are a few more well used methods of input. Try to think about it before you read on. What are they?

There are more things besides when using the input singleton, and this section will explain in-depth on what can be achieved and how.

Motion controls
Motion controls are in many popular games, particularly VR and/or AR games, to look around.

.rotation +=.

This is only for "rotational" motion detecting.

Vibration
Many popular games include vibration. You can call the below when the player is hit:

..

This will vibrate a controller or mobile device for 1 second.

InputMap singleton
The InputMap allows creating input actions via code. This is good in games where the player can change their controls.

See here for the rundown of InputMap.

The following code creates a shoot action which corresponds to pressing the spacebar.

(key) -> : input =. .pressed = .scancode = input

It can be any input event, not just.

See the "faking" input section below for more information on creating.

Other useful methods:
 * : Resets actions to those set in ProjectSettings.
 * 1) (action: ): Returns true if the action exists.
 * 2) (action: ): Clears the action so there are no associated events.
 * 3) (action: ): Erases the action.

As always, this does not list them all. Just a few of them.

Audio input
To record audio, you need to do 2 things:
 * 1) Press "Audio" at the bottom of the screen, and press "New Bus". Rename it "Microphone" and click "Add Effect". Press "Record" in the dropdown menu that appears.
 * 2) Create a new node for your scene. Click on the Stream value in the Inspector. Choose New AudioStreamMicrophone from the dropdown menu that appears. Set the "Bus" property to "Microphone". Whenever you want to record audio in-game, just turn the "Playing" value to true.

Reading audio for stuff like voice recognition can be done, but it is not easy, and is outside the scope of this book (and outside the knowledge of the author).

"Faking" input
So, you decided that you want to change the InputMap at runtime? But how do you do that?

Godot has several powerful classes that make input detection easier and faking it possible.

See more: The InputEvent tutorial.

InputEventKey
InputEventKey is for detecting keyboard button presses and releases.

The below code allows you to shoot with the A key:

input.pressed = input.scancode = KEY_A .  .(, input)

The "Input.event_erase_actions" clears all actions for the event specified. In this case, the space-bar will no longer make you shoot.

Any key can be specified, though it may not be obvious how to do so.

If you want to detect if certain modifiers are also pressed, you have access to these variables:
 * alt: Set to true if you must press "Alt" on your keyboard.
 * 1) ctrl: Set to true if you must press "Ctrl" on your keyboard (Windows only).
 * 2) meta: Set to true if you must press "Meta" on your keyboard (Linux only).
 * 3) command: Set to true if you must press "Ctrl" (on Windows) or "Meta" (on Linux) on your keyboard.
 * 4) shift: Set to true if you must press "shift" on your keyboard.

You may set more than one of these to true. This makes you need to press all the modifiers set.

If you want to detect releasing the key instead of pressing it, don't set "pressed" to true. If you are adding it to the InputMap, it will always be pressed if the keys for it are not, but only after they have been released for the first time. So how do you fix this then? Actually, it's quite simple!

Try. It works nicely, but if you need it for calls to _input, you should instead use.

InputEventMouse
Detecting mouse input or faking it can be explained in two ways: mouse buttons and mouse motion.

See also: mouse and input coordinates tutorial.

InputEventMouseButton
Clicking your mouse is a common action to read, but not as common to fake. It is the simplest action to read and fake, though, needing only 2 values.

input.pressed = input.button_index = BUTTON_LEFT .  .(,input)

InputEventMouseMotion
Faking mouse motion can be harder, but sometimes very useful. If you actually want to move the mouse, instead use. That will also generate a InputEventMouseMotion event to trigger.

By default, this event is only emitted once per frame rendered at most. If you need more precise input reporting, consider using  to emit events as often as possible. If you need this to draw freehand lines, consider using Bresenham's line algorithm as well to avoid gaps when you move the mouse quickly.

InputEventScreenDrag
(Only available on mobile devices)

Reading and writing screen dragging is header than InputEventMouseMotion, simply because you cannot force the user to move their finger via code. Okay, that's a lie. But to do that, you would need a degree in mind control or hypnotising, which is well outside the scope of this book!

InputEventScreenTouch
(Only available on mobile devices)

This event is for tapping (or untapping) on the screen.

InputEventJoypadButton
This InputEvent is for detecting joy-con buttons (i.e: buttons on a controller, linked to a computer or a console).

InputEventJoypadMotion
This event is for moving the Joy stick, one axis at a time. This InputEvent can be confusing.

It is important to know that this InputEvent does not have a Vector2 value you can read from. The following script converts this InputEvent into a Vector3, x and y are for position, z is for the joystick being moved.

(event: ) -> : event.axis: JOY_AXIS_0: (event.axis_value,, ) JOY_AXIS_1: (, event.axis_value, ) JOY_AXIS_2: (event.axis_value,, ) JOY_AXIS_3: (, event.axis_value, ) ( % [event.axis])