Class
VirtualInput
NotCreatableNotReplicated
Simulates mouse, keyboard, and pointer input as if it were performed by a real player.
VirtualInput simulates mouse, keyboard, and pointer input as if it
were performed by a real player. It is intended for testing purposes only
and can only be obtained by calling
UserInputService:CreateVirtualInput().
All input methods throw a runtime error if the simulated input would interact
with Roblox's built-in UI (CoreGui), such as the top bar, chat window,
or escape menu. This prevents automation tests from accidentally interfering
with system UI that players depend on.
Methods 6#
| SendKey | Injects a keyboard key press or release event. |
| SendMouseButton | Injects a mouse button press or release event at the specified screen position. |
| SendMouseDelta | Injects a relative mouse movement event. Only works while the player's cursor is locked. |
| SendMousePosition | Moves the virtual mouse cursor to the specified absolute screen position. |
| SendPointerAction | Injects a scroll wheel, trackpad pan, or pinch gesture event at the specified screen position. |
| SendTextInput | Injects a text input event as if the specified string was typed on a keyboard. |
SendKey(isPressed: boolean, keyCode: KeyCode, isRepeatedKey: boolean = false): ()#
This method injects a keyboard key press or release event, processed identically to a real hardware key event.
This method throws a runtime error if CoreGui has keyboard focus,
which includes a TextBox inside CoreGui being focused, a
CoreGui element selected for keyboard or gamepad navigation, or
the in-game escape menu being open. It also throws if the requested key is
permanently bound to a Roblox core action (for example, the
Escape key).
isRepeatedKey#
Set isRepeatedKey to true only when simulating the OS auto-repeat
behavior that occurs while a player physically holds a key down which
fires a stream of repeated events after the initial key press. This is
meaningful only for text-manipulation keys: KeyCode.Backspace,
KeyCode.Delete, and the arrow keys (KeyCode.Left,
KeyCode.Right, KeyCode.Up, and KeyCode.Down). Passing
true for any other key throws a runtime error.
For example, to simulate holding Backspace to delete multiple characters, call:
SendKey(true, Enum.KeyCode.Backspace, false)for the initial pressSendKey(true, Enum.KeyCode.Backspace, true)in a loop for each repeated eventSendKey(false, Enum.KeyCode.Backspace, false)for the release
Do not pass isRepeatedKey as true for the initial press or the
release. For any key that does not involve text editing (game action keys,
modifier keys, function keys, etc.), always pass false.
| Name | Type | Default | Description |
|---|---|---|---|
isPressed | boolean | Whether to simulate a key press (true) or a key release (false). | |
keyCode | KeyCode | The KeyCode of the key to inject. | |
isRepeatedKey | boolean | false | Whether this is an auto-repeat event, as occurs when a key is held
down. Only valid for text-manipulation keys such as
KeyCode.Backspace, KeyCode.Delete, and the arrow keys.
Defaults to false. |
Returns
()
SendMouseButton(position: Vector2, button: UserInputType, isDown: boolean, repeatCount: int = 0): ()#
This method injects a mouse button press or release event at the given screen-space position, processed identically to a real hardware mouse event.
Only UserInputType.MouseButton1, UserInputType.MouseButton2,
and UserInputType.MouseButton3 are supported; passing any other
value throws a runtime error.
This method throws a runtime error if the specified position overlaps an
interactive CoreGui element such as a button or an active overlay
in the top bar, chat window, or escape menu. It also throws if the
specified button is already in the requested state, for example pressing a
button that is already pressed.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | The screen-space position in pixels at which to inject the event. | |
button | UserInputType | The mouse button to use. Supported values are
UserInputType.MouseButton1, UserInputType.MouseButton2,
and UserInputType.MouseButton3. | |
isDown | boolean | Whether to simulate a button press (true) or a button release
(false). | |
repeatCount | int | 0 | The consecutive-click count for multi-click detection, such as a
double- or triple-click. Defaults to 0. |
Returns
()
SendMouseDelta(positionDelta: Vector2): ()#
This method injects a relative mouse movement event, representing how far the mouse moved rather than where it is on screen. This is intended for use while the player's cursor is locked, such as in first-person camera mode.
This method throws a runtime error when the cursor is not locked. To move
the cursor to an absolute screen position instead, use
SendMousePosition().
| Name | Type | Default | Description |
|---|---|---|---|
positionDelta | Vector2 | The relative mouse movement in pixels along each axis. |
Returns
()
SendMousePosition(position: Vector2): ()#
This method moves the virtual mouse cursor to the specified absolute screen-space position, processed identically to a real hardware mouse-move event.
This method throws a runtime error when the specified position overlaps an interactive Roblox UI element (such as a button or active overlay in the top bar, chat window, or escape menu).
To inject relative mouse movement while the cursor is locked, use
SendMouseDelta() instead.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | The target screen-space position in pixels. |
Returns
()
SendPointerAction(position: Vector2, pointerAction: Dictionary): ()#
This method injects a pointer action event at the given screen-space
position. The pointerAction dictionary accepts the following keys:
Wheel(number) — Scroll wheel delta. Positive values scroll forward, negative values scroll backward.Pan(Vector2) — Trackpad pan delta in pixels.Pinch(number) — Pinch-to-zoom delta. Positive values zoom in, negative values zoom out.
This method throws a runtime error if the specified position overlaps an
interactive Roblox UI element (such as a button or active overlay in the
top bar, chat window, or escape menu). If all values in pointerAction
are zero, the call returns without injecting any event.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | The screen-space position in pixels at which to inject the event. | |
pointerAction | Dictionary | A dictionary describing the pointer action to inject. Accepted keys
are Wheel (number), Pan (Vector2), and Pinch
(number). At least one key must have a non-zero value. |
Returns
()
SendTextInput(text: string): ()#
This method injects a text input event, routing the given string directly
to the focused TextBox or the experience's text input handler as
if the player typed it on a physical keyboard. This is useful for
populating text fields without needing to simulate individual key presses.
This method throws a runtime error if CoreGui has keyboard focus,
which includes a TextBox inside CoreGui being focused, a
CoreGui element selected for keyboard or gamepad navigation, or
the in-game escape menu being open.
| Name | Type | Default | Description |
|---|---|---|---|
text | string | The string to inject as text input. |
Returns
()