Guide to the Godot game engine/Input

Your first game Physics 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. Joy Button: Allows you to link a controller button. Joy Axis: Allows you to link a controller joy-stick movement. 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. Function What it's foris_action_pressedActions that can be held down, like moving, or shooting an automatic weaponis_action_just_pressedActions that only run the moment the button is pressed, and cannot run again until the action is released.get_action_strengthMovement, and only for joy sticks (for precise control). Returns a float, 1 = full joy tilt or pressed and 0 = no tilt or not pressed.is_action_just_releasedActions that run only when released (Button unpressed, for example) The above methods are all called on the Input singleton. They all accept a single String argument. if Input.is_action_just_pressed("shoot"): pass # Add shooting code here 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. extends Sprite2D func _input(event): if event is InputEventMouseMotion: position += event.relative The below code creates a simple button. _gui_input() 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 var pressed = false func _gui_input(event): if event is InputEventMouseButton and event.button_index == BUTTON_LEFT: if event.pressed: get_tree().set_input_as_handled() emit_signal("button_down") pressed = true elif not event.pressed: if pressed: emit_signal("button_up") pressed = false The get_tree().set_input_as_handled() makes sure other _gui_input() and _unhandled_input() 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. func _process(): # Assume camera_pivot is a Spatial with a child Camera3D node. # The gyroscope only works when exported to Android. $camera_pivot.rotation += Input.get_gyroscope() # The accelerometer is only available when exported to mobile. # This makes you move the camera when you move the device (Not when you rotate it) $camera_pivot.rotation += Input.get_accelerometer() This is only for "rotational" motion detecting. Vibration Many popular games include vibration. You can call the below when the player is hit: Input.vibrate_handheld(100) Input.start_joy_vibration(0, .5, .4, 1.0) 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. extends Node func _ready(): InputMap.add_action("shoot") InputMap.action_add_event("shoot", create_key_action(KEY_SPACE)) func create_key_action(key) -> InputEventKey: var input = InputEventKey.new() input.pressed = true input.scancode = key return input It can be any input event, not just InputEventKey. See the "faking" input section below for more information on creating InputEvents. Other useful methods: load_from_globals(): Resets actions to those set in ProjectSettings. has_action(action: String): Returns true if the action exists. action_erase_events(action: String): Clears the action so there are no associated events. erase_action(action: String): 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: 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. Create a new AudioStreamPlayer 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: extends Node func shoot_with_a(): var input = InputEventKey.new() input.pressed = true input.scancode = KEY_A InputMap.action_erase_events("shoot") InputMap.action_add_event("shoot", 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. +Key constantsConstantAboutKEY_<letter>Letter keysKEY_<number>Number keysKEY_KP_MULTIPLYThe keypad * keyKEY_KP_DIVIDEThe keypad / keyKEY_KP_SUBTRACTThe keypad - keyKEY_KP_ADDThe keypad + keyKEY_KP_ENTERThe keypad Enter keyKEY_KP_PERIODThe keypad . keyKEY_SPACEThe Space keyKEY_ENTERThe Enter keyKEY_PLUSThe + keyKEY_MINUSThe - keyKEY_EQUALSThe = keyKEY_QUESTIONThe ? keyKEY_EXCLAIMThe ! keyKEY_QUOTEDBLThe " keyKEY_NUMBERSIGNThe # keyKEY_DOLLARThe $ keyKEY_PERCENTThe % keyKEY_AMPERSANDThe & keyKEY_APOSTROPHEThe ' keyKEY_PARENLEFTThe ( keyKEY_PARENRIGHTThe ) keyKEY_ATThe @ keyKEY_COLONThe : keyKEY_SEMICOLONThe ; keyKEY_GREATERThe > keyKEY_LESSThe < keyKEY_BRACKETLEFTThe [ keyKEY_BRACKETRIGHTThe ] keyKEY_BACKSLASHThe \ keyKEY_ASCIICIRCUMThe ^ keyKEY_UNDERSCOREThe _ keyKEY_QUOTELEFTThe ` keyKEY_BRACELEFTThe { keyKEY_BRACERIGHTThe } keyKEY_BARThe | keyKEY_ASCIITIDLEThe ~ keyKEY_STERLINGThe £ keyKEY_CENTThe ¢ keyKEY_YENThe ¥ keyKEY_COPYRIGHTThe © keyKEY_REGISTEREDThe ® keyKEY_UPThe Up arrow keyKEY_DOWNThe Down arrow keyKEY_LEFTThe Left arrow keyKEY_RIGHTThe Right arrow keyKEY_TABThe Tab keyKEY_BACKTABThe Shift + Tab keys pressed togetherKEY_ESCAPEThe Esc keyKEY_DELETEThe Delete keyKEY_INSERTThe Insert keyKEY_BACKThe Backspace keyKEY_SHIFTThe Shift keyKEY_ALTThe Alt keyKEY_CONTROLThe Ctrl key (Windows only)KEY_METAThe Meta key (Linux only)KEY_F<number 1 to 12>The F1 ect. keys on your keyboardKEY_COMMAThe , keyKEY_PERIODThe . keyKEY_ASTERISKThe * keyKEY_SLASHThe / keyKEY_HOMEThe Home keyKEY_PAUSEThe Pause keyKEY_PRINTThe Print Screen keyKEY_CLEARThe Clear keyKEY_ENDThe End keyKEY_SYSREQThe system request keyKEY_PAGEUPThe Page Up keyKEY_PAGEDOWNThe Page Down keyKEY_NUMLOCKThe Num Lock keyKEY_SCROLLLOCKThe Scroll Lock keyKEY_CAPSLOCKThe Caps Lock keyKEY_MENUThe Context Menu keyKEY_HELPThe Help keyKEY_BACKThe Media Back key. Not to be confused with the back button on an Android deviceKEY_FORWARDThe Media Forward keyKEY_STOPThe Media Stop keyKEY_MEDIAPLAYThe Media Play key 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. ctrl: Set to true if you must press "Ctrl" on your keyboard (Windows only). meta: Set to true if you must press "Meta" on your keyboard (Linux only). command: Set to true if you must press "Ctrl" (on Windows) or "Meta" (on Linux) on your keyboard. 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 Input.event_<press/release>("shoot"). It works nicely, but if you need it for calls to _input, you should instead use Input.parse_input_event(event). 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. extends Node func shoot_on_click(): var input = InputEventMouseButton.new() input.pressed = true input.button_index = BUTTON_LEFT InputMap.action_erase_events("shoot") InputMap.action_add_event("shoot",input) +VariablesVariableUsedoubleclickIf true, the button was double-clicked.factorThe factor (or delta) of the event as a float. When used for high-precision scroll events, this indicates the scroll amount. Only supported on some platforms. If unsupported on the current platform, it may be 0. +Allowed values for button_indexConstantWhat it meansBUTTON_LEFTLeft clickBUTTON_RIGHTRight clickBUTTON_MIDDLEScroll button pressed downBUTTON_WHEEL_UPScroll wheel up.BUTTON_WHEEL_DOWNScroll wheel down. InputEventMouseMotion Faking mouse motion can be harder, but sometimes very useful. If you actually want to move the mouse, instead use Input.set_mouse_position(<Vector2>). That will also generate a InputEventMouseMotion event to trigger. +VariablesVariableUsepositionThe new mouse position, relative to the nodes viewport. If called in _gui_input, it is instead relative to the Control node.relativeThe new position relative to the mouse position in the last call.speedThe mouse speed in pixels per second By default, this event is only emitted once per frame rendered at most. If you need more precise input reporting, consider using Input.set_use_accumulated_input(false) 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 harder 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! +VariablesVariableUsepositionThe new position of the finger relative to the node's viewport. If used in _gui_input, it is relative to the Control node.relativeThe finger's new position, relative to its old position.speedThe drag speed in pixels per second. InputEventScreenTouch (Only available on mobile devices) This event is for tapping (or untapping) on the screen. +VariablesVariableUsepositionThe finger's position relative to the node's viewport. If used in _gui_input, it is relative to the Control.pressedIf true, the user is putting their finger on the screen. Otherwise, they are taking their finger off the screen. InputEventJoypadButton This InputEvent is for detecting joy-con buttons (i.e: buttons on a controller, linked to a computer or a console). +VariablesVariablesAboutbutton_indexThe button that is pressed.If "true", the button is pressed. Otherwise the button is released. InputEventJoypadMotion This event is for moving the Joy stick, one axis at a time. This InputEvent can be confusing. +VariablesVariableAboutaxisA constant that has one of six values: JOY_AXIS_*, where "*" can be: 0: Left stick on the horizontal axis 1: Left stick on the vertical axis 2: Right stick on the horizontal axis 3: Right stick on the vertical axis 6: Left trigger analogue axis 7: Right trigger analogue axis The other four have no function yet, and are described as "generic game pad axises" and are just used as blank space.axis_valueA number from -1.0 to 1.0. 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. func convert_from_joypad_motion(event: InputEventJoypadMotion) -> Vector3: match event.axis: JOY_AXIS_0:# Left stick horizontal return Vector3(event.axis_value, 0, 0) JOY_AXIS_1:# Left stich vertical return Vector3(0, event.axis_value, 0) JOY_AXIS_2:# Right stick horizontal return Vector3(event.axis_value, 0, 1) JOY_AXIS_3:# Right stick vertical return Vector3(0, event.axis_value, 1) # An error occurred printerr("Invalid axis: %s in call to convert_from_joypad_motion" % [event.axis]) print_stack() # To help with debugging, print the call stack. return Vector3(0, 0, 0) <noinclude> Your first game Physics 100%