Simulate Mouse Inputs

This page provides guidance on how to test mouse inputs in your scene using GdUnit4. For more detailed information on Godot mouse events, please refer to the official Godot documentation

Function Overview

All functions listed below utilize the listed classes to simulate mouse input events.

How to Simulate Mouse Interactions

To simulate mouse interactions in your scene, you can use the provided mouse simulation functions. These functions allow you to mimic user mouse inputs for testing purposes. There are two main categories of functions:

  • Unfinished Functions
    Unfinished functions simulate the act of pressing a key without releasing it immediately. These are useful for simulating combinations, such as holding down a modifier mouse button (e.g., Left-Button) while pressing another mouse button (e.g., Right-Button). The interaction is completed when mouse release function is called.

  • Finalized Functions
    Finalized functions simulate a complete mouse press-and-release action in a single function call.

Advice
To ensure input events are processed correctly, you must wait at least one frame cycle after simulating inputs. Use the await await_input_processed() function to accomplish this.

See Synchronize Inputs Events

set_mouse_position

The set_mouse_position function is used to set the mouse cursor to given position of the viewport.

  • It takes the following arguments:

    ## Sets the mouse position to the specified vector, provided in pixels and relative to an origin at the upper left corner of the currently focused Window Manager game window.
## [member position] : The absolute position in pixels as Vector2
func set_mouse_position(position: Vector2) -> GdUnitSceneRunner:

    Here is an example of how to use set_mouse_position:

    var runner := scene_runner("res://test_scene.tscn")

# sets the current mouse position to 100, 100
runner.set_mouse_position(Vector2(100, 100))
await await_input_processed()

  • It takes the following arguments:

    /// <summary>
/// Sets the actual mouse position to the viewport.
/// </summary>
/// <param name="position">The position in x/y coordinates</param>
/// <returns></returns>
ISceneRunner SetMousePos(Vector2 position);

    Here is an example of how to use SetMousePos:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// sets the current mouse position to 100, 100
runner.SetMousePos(new Vector2(100, 100));
await AwaitIdleFrame();

We use await_input_processed() to ensure that the simulation of the mouse input is complete before moving on to the next instruction.

get_mouse_position

The get_mouse_position function is used to get the mouse cursor position from the current viewport.

  • ## Returns the mouse's position in this Viewport using the coordinate system of this Viewport.
func get_mouse_position() -> Vector2:

    Here is an example of how to use get_mouse_position:

    var runner := scene_runner("res://test_scene.tscn")

# gets the current mouse position
var mouse_position := runner.get_mouse_position()

  • /// <summary>
/// Returns the mouse's position in this Viewport using the coordinate system of this Viewport.
/// </summary>
/// <returns>Vector2</returns>
Vector2 GetMousePosition();

    Here is an example of how to use GetMousePosition:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// gets the current mouse position
var mousePosition = runner.GetMousePosition();

simulate_mouse_move

The simulate_mouse_move function is used to simulate the movement of the mouse cursor to a given position on the screen.

  • It takes the following arguments:

    # position: representing the final position of the mouse cursor after the movement is completed
func simulate_mouse_move(position: Vector2) -> GdUnitSceneRunner:

    Here is an example of how to use simulate_mouse_move:

    var runner := scene_runner("res://test_scene.tscn")

# Set mouse position to a initial position
runner.set_mouse_pos(Vector2(160, 20))
await await_input_processed()

# Simulates a mouse move to final position 200, 40
runner.simulate_mouse_move(Vector2(200, 40))
await await_input_processed()

  • It takes the following arguments:

    /// <summary>
/// Simulates a mouse moved to final position.
/// </summary>
/// <param name="position">representing the final position of the mouse cursor after the movement is completed).</param>
/// <returns>SceneRunner</returns>
ISceneRunner SimulateMouseMove(Vector2 position);

    Here is an example of how to use SimulateMouseMove:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

# Set the mouse position to a inital position
runner.SetMousePos(new Vector2(160, 20))
await AwaitIdleFrame();

# simulates a mouse move to final position 200,40
runner.SimulateMouseMove(new Vector2(200, 40))
await AwaitIdleFrame();

We use await_input_processed() to ensure that the simulation of the mouse input is complete before moving on to the next instruction.

simulate_mouse_move_relative

The simulate_mouse_move_relative function simulates a mouse move to a relative position within a specified time.

  • It takes the following arguments:

    ## Simulates a mouse move to the relative coordinates (offset).
## [member relative] : The relative position, indicating the mouse position offset.
## [member time] : The time to move the mouse by the relative position in seconds (default is 1 second).
## [member trans_type] : Sets the type of transition used (default is TRANS_LINEAR).
func simulate_mouse_move_relative(relative: Vector2, time: float = 1.0, trans_type: Tween.TransitionType = Tween.TRANS_LINEAR) -> GdUnitSceneRunner:

    Here is an example of how to use simulate_mouse_move_relative:

    var runner := scene_runner("res://test_scene.tscn")

# Set mouse position to an initial position
runner.set_mouse_pos(Vector2(10, 20))
await await_input_processed()

# Simulate a mouse move from the current position to the relative position within 1 second
# the final position will be (410, 220) when is completed
await runner.simulate_mouse_move_relative(Vector2(400, 200), 1)

  • /// <summary>
/// Simulates a mouse move to the relative coordinates (offset).
/// </summary>
/// <param name="relative">The relative position, e.g. the mouse position offset</param>
/// <param name="time">The time to move the mouse by the relative position in seconds (default is 1 second).</param>
/// <param name="transitionType">Sets the type of transition used (default is Linear).</param>
/// <returns>SceneRunner</returns>
Task SimulateMouseMoveRelative(Vector2 relative, double time = 1.0, Tween.TransitionType transitionType = Tween.TransitionType.Linear);

    Here is an example of how to use SimulateMouseMoveRelative:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// Set mouse position to an initial position
sceneRunner.SimulateMouseMove(Vector2(10, 20));
await ISceneRunner.SyncProcessFrame;

// Simulate a mouse move from the current position to the relative position within 1 second
// the final position will be (410, 220) when is completed
await sceneRunner.SimulateMouseMoveRelative(new Vector2(400, 200));

simulate_mouse_move_absolute

The simulate_mouse_move_absolute function simulates a mouse move to an absolute position within a specified time.

  • It takes the following arguments:

    ## Simulates a mouse move to the absolute coordinates.
## [member position] : The final position of the mouse.
## [member time] : The time to move the mouse to the final position in seconds (default is 1 second).
## [member trans_type] : Sets the type of transition used (default is TRANS_LINEAR).
func simulate_mouse_move_absolute(position: Vector2, time: float = 1.0, trans_type: Tween.TransitionType = Tween.TRANS_LINEAR) -> GdUnitSceneRunner:

    Here is an example of how to use simulate_mouse_move_absolute:

    var runner := scene_runner("res://test_scene.tscn")

# Set mouse position to an initial position
runner.set_mouse_pos(Vector2(10, 20))
await await_input_processed()

# Simulate a mouse move from the current position to the absolute position within 1 second
# the final position will be (400, 200) when is completed
await runner.simulate_mouse_move_absolute(Vector2(400, 200), 1)

  • /// <summary>
/// Simulates a mouse move to the absolute coordinates.
/// </summary>
/// <param name="position">The final position of the mouse.</param>
/// <param name="time">The time to move the mouse to the final position in seconds (default is 1 second).</param>
/// <param name="transitionType">Sets the type of transition used (default is Linear).</param>
/// <returns>SceneRunner</returns>
Task SimulateMouseMoveAbsolute(Vector2 position, double time = 1.0, Tween.TransitionType transitionType = Tween.TransitionType.Linear);

    Here is an example of how to use SimulateMouseMoveAbsolute:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// Set mouse position to an initial position
sceneRunner.SimulateMouseMove(Vector2(10, 20));
await ISceneRunner.SyncProcessFrame;

// Simulate a mouse move from the current position to the absolute position within 1 second
// the final position will be (400, 200) when is completed
await sceneRunner.SimulateMouseMoveAbsolute(new Vector2(400, 200));

simulate_mouse_button_pressed

The simulate_mouse_button_pressed function is used to simulate that a mouse button is pressed.

  • It takes the following arguments:

    # button_index: The mouse button identifier, one of the ButtonList button or button wheel constants.
# double_click: set to true to simulate a double-click
func simulate_mouse_button_pressed(button_index: MouseButton, double_click := false) -> GdUnitSceneRunner:

    Here is an example of how to use simulate_mouse_button_pressed:

    var runner := scene_runner("res://test_scene.tscn")

# Simulates pressing the left mouse button
runner.simulate_mouse_button_pressed(BUTTON_LEFT)
await await_input_processed()

  • It takes the following arguments:

    /// <summary>
/// Simulates a mouse button pressed.
/// </summary>
/// <param name="button">The mouse button identifier, one of the ButtonList button or button wheel constants.</param>
/// <returns>SceneRunner</returns>
ISceneRunner SimulateMouseButtonPressed(ButtonList button);

    Here is an example of how to use SimulateMouseButtonPressed:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// Simulates pressing the left mouse button
runner.SimulateMouseButtonPressed(ButtonList.Left);
await AwaitIdleFrame();

We use await_input_processed() to ensure that the simulation of the mouse input is complete before moving on to the next instruction.

simulate_mouse_button_press

The simulate_mouse_button_press function is used to simulate holding down a mouse button.

  • It takes the following arguments:

    # buttonIndex: The mouse button identifier, one of the ButtonList button or button wheel constants.
# button_index: Set to true to simulate a double-click
func simulate_mouse_button_press(button_index: int, double_click := false) -> GdUnitSceneRunner:

    Here is an example of how to use simulate_mouse_button_press:

    var runner := scene_runner("res://test_scene.tscn")

# simulates mouse left button is press
runner.simulate_mouse_button_press(BUTTON_LEFT)
await await_input_processed()

  • It takes the following arguments:

    /// <summary>
/// Simulates a mouse button press. (holding)
/// </summary>
/// <param name="button">The mouse button identifier, one of the ButtonList button or button wheel constants.</param>
/// <param name="doubleClick">Set to true to simulate a double-click.</param>
/// <returns>SceneRunner</returns>
ISceneRunner SimulateMouseButtonPress(ButtonList button);

    Here is an example of how to use SimulateMouseButtonPress:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// simulates mouse left button is press
runner.SimulateMouseButtonPress(ButtonList.Left);
await AwaitIdleFrame();

We use await_input_processed() to ensure that the simulation of the mouse input is complete before moving on to the next instruction.

simulate_mouse_button_release

The simulate_mouse_button_release function is used to simulate a mouse button is released.

  • It takes the following arguments:

    # button_index: The mouse button identifier, one of the ButtonList button or button wheel constants.
func simulate_mouse_button_release(button_index: int) -> GdUnitSceneRunner:

    Here is an example of how to use simulate_mouse_button_release:

    var runner := scene_runner("res://test_scene.tscn")

# Simulates a mouse left button is released
runner.simulate_mouse_button_release(BUTTON_LEFT)
await await_input_processed()

  • It takes the following arguments:

    /// <summary>
/// Simulates a mouse button released.
/// </summary>
/// <param name="button">The mouse button identifier, one of the ButtonList button or button wheel constants.</param>
/// <returns>SceneRunner</returns>
ISceneRunner SimulateMouseButtonRelease(ButtonList button);

    Here is an example of how to use SimulateMouseButtonRelease:

    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// Simulates a mouse left button is released
runner.SimulateMouseButtonRelease(ButtonList.Left);
await AwaitIdleFrame();

We use await_input_processed() to ensure that the simulation of the mouse input is complete before moving on to the next instruction.

document version v4.4.0

Copyright © 2021-2024 Mike Schulze. Distributed by an MIT license.