GutInputSender

The GutInputSender class. It sends input to places.

Description

This class can be used to send InputEvent* events to various objects. It also allows you to script out a series of inputs and play them back in real time. You could use it to:

Verify that jump height depends on how long the jump button is pressed.
Double tap a direction performs a dash.
Down, Down-Forward, Forward + punch throws a fireball.

And much much more.

As of 9.3.1 you can use GutInputSender instead of InputSender. It’s the same thing, but GutInputSender is a class_name so you may have less warnings and auto-complete will work.

Warning

If you move the Godot window to a different monitor while tests are running it can cause input tests to fail. This issue has more details.

Properties

Variant	mouse_warp	`false`
Variant	draw_mouse	`true`

Methods

void	_init(r = null)
Variant	action_down(which, strength = 1.0)
Variant	action_up(which, strength = 1.0)
void	add_receiver(obj)
void	clear()
Variant	get_auto_flush_input()
Variant	get_receivers()
Variant	hold_for(duration)
Variant	hold_frames(duration: int)
Variant	hold_seconds(duration: float)
Variant	is_action_pressed(which)
Variant	is_idle()
Variant	is_key_pressed(which)
Variant	is_mouse_button_pressed(which)
Variant	key_down(which)
Variant	key_echo()
Variant	key_up(which)
Variant	mouse_double_click(position = null, global_position = null)
Variant	mouse_left_button_down(position = null, global_position = null)
Variant	mouse_left_button_up(position = null, global_position = null)
Variant	mouse_left_click_at(where, duration = “5f”)
Variant	mouse_motion(position, global_position = null)
Variant	mouse_relative_motion(offset, speed = Vector2(0, 0))
Variant	mouse_right_button_down(position = null, global_position = null)
Variant	mouse_right_button_up(position = null, global_position = null)
Variant	mouse_set_position(position, global_position = null)
Variant	release_all()
Variant	send_event(event)
void	set_auto_flush_input(val)
Variant	wait(t)
Variant	wait_frames(num_frames)
Variant	wait_secs(num_secs)

Signals

idle() 🔗

Emitted when all events in the input queue have been sent.

Constants

INPUT_WARN = "If using Input as a reciever it will not respond to *_down events until a *_up event is recieved. Call the appropriate *_up event or use hold_for(...) to automatically release after some duration." 🔗

Local reference to the GutInputFactory static class

Property Descriptions

Variant mouse_warp = false 🔗

Warp mouse when sending InputEventMouse* events

Variant draw_mouse = true 🔗

Draw mouse position cross hairs. Useful to see where the mouse is at when not using mouse_warp

Method Descriptions

void _init(r = null) 🔗

Accepts a single optional receiver.

void add_receiver(obj) 🔗

Add an object to receive input events.

Variant get_receivers() 🔗

Returns the receivers that have been added.

Variant is_idle() 🔗

Returns true if the input queue has items to be processed, false if not.

Variant is_key_pressed(which) 🔗

No description

Variant is_action_pressed(which) 🔗

No description

Variant is_mouse_button_pressed(which) 🔗

No description

Variant get_auto_flush_input() 🔗

Get the value of set_auto_flush_input.

void set_auto_flush_input(val) 🔗

Enable/Disable auto flushing of input. When enabled the GutInputSender will call Input.flush_buffered_events after each event is sent. See the “use_accumulated_input” section in Mocking-Input for more information.

Variant wait(t) 🔗

Adds a delay between the last input queue item added and any queue item added next. By default this will wait t seconds. You can specify a number of frames to wait by passing a string composed of a number and “f”. For example wait("5f") will wait 5 frames.

void clear() 🔗

Clears the input queue and any state such as the last event sent and any pressed actions/buttons. Does not clear the list of receivers.

This should be done between each test when the GutInputSender is a class level variable so that state does not leak between tests.

Variant key_up(which) 🔗

Sends a InputEventKey event with pressed = false. which can be a character or a KEY_* constant.

Variant key_down(which) 🔗

Sends a InputEventKey event with pressed = true. which can be a character or a KEY_* constant.

Variant key_echo() 🔗

Sends an echo InputEventKey event of the last key event.

Variant action_up(which, strength = 1.0) 🔗

Sends a “action up” InputEventAction instance. which is the name of the action defined in the Key Map.

Variant action_down(which, strength = 1.0) 🔗

Sends a “action down” InputEventAction instance. which is the name of the action defined in the Key Map.

Variant mouse_left_button_down(position = null, global_position = null) 🔗

Sends a “button down” InputEventMouseButton for the left mouse button.

Variant mouse_left_button_up(position = null, global_position = null) 🔗

Sends a “button up” InputEventMouseButton for the left mouse button.

Variant mouse_double_click(position = null, global_position = null) 🔗

Sends a “double click” InputEventMouseButton for the left mouse button.

Variant mouse_right_button_down(position = null, global_position = null) 🔗

Sends a “button down” InputEventMouseButton for the right mouse button.

Variant mouse_right_button_up(position = null, global_position = null) 🔗

Sends a “button up” InputEventMouseButton for the right mouse button.

Variant mouse_motion(position, global_position = null) 🔗

Sends a InputEventMouseMotion to move the mouse the specified positions.

Variant mouse_relative_motion(offset, speed = Vector2(0, 0)) 🔗

Sends a InputEventMouseMotion that moves the mouse offset from the last mouse_motion or mouse_set_position call.

Variant mouse_set_position(position, global_position = null) 🔗

Sets the mouse’s position. This does not send an event. This position will be used for the next call to mouse_relative_motion.

Variant mouse_left_click_at(where, duration = “5f”) 🔗

Performs a left click at the given position.

Variant send_event(event) 🔗

Create your own event and use this to send it to all receivers.

Variant release_all() 🔗

Releases all InputEventKey, InputEventAction, and InputEventMouseButton events that have passed through this instance. These events could have been generated via the various _down methods or passed to send_event.

This will send the “release” event (pressed = false) to all receivers. This should be done between each test when using Input as a receiver.

Variant wait_frames(num_frames) 🔗

Same as wait but only accepts a number of frames to wait.

Variant wait_secs(num_secs) 🔗

Same as wait but only accepts a number of seconds to wait.

Variant hold_for(duration) 🔗

This is a special wait that will emit the previous input queue item with pressed = false after a delay. If you pass a number then it will wait that many seconds. You can also use the “4f” format to wait a specific number of frames.

For example sender.action_down('jump').hold_for("10f") will cause two InputEventAction instances to be sent. The “jump-down” event from action_down and then a “jump-up” event after 10 frames.

Variant hold_frames(duration: int) 🔗

Same as hold_for but specifically holds for a number of physics frames.

Variant hold_seconds(duration: float) 🔗

Same as hold_for but specifically holds for a number of seconds.