6 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

VirtualInput

Inherits from: Object

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.

Inherits from: Object

Memory category: Instances

Tags: NotCreatable, NotReplicated

Methods

Name	Type / Returns	Description
VirtualInput:SendKey	()	Injects a keyboard key press or release event.
VirtualInput:SendMouseButton	()	Injects a mouse button press or release event at the specified screen position.
VirtualInput:SendMouseDelta	()	Injects a relative mouse movement event. Only works while the player's cursor is locked.
VirtualInput:SendMousePosition	()	Moves the virtual mouse cursor to the specified absolute screen position.
VirtualInput:SendPointerAction	()	Injects a scroll wheel, trackpad pan, or pinch gesture event at the specified screen position.
VirtualInput:SendTextInput	()	Injects a text input event as if the specified string was typed on a keyboard.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

VirtualInput:SendKey

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 press
SendKey(true, Enum.KeyCode.Backspace, true) in a loop for each repeated event
SendKey(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.

Parameters

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

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

VirtualInput:SendMouseButton

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.

Parameters

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

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

VirtualInput:SendMouseDelta

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().

Parameters

Name	Type	Default	Description
positionDelta	Vector2		The relative mouse movement in pixels along each axis.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

VirtualInput:SendMousePosition

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.

Parameters

Name	Type	Default	Description
position	Vector2		The target screen-space position in pixels.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

VirtualInput:SendPointerAction

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.

Parameters

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

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

VirtualInput:SendTextInput

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.

Parameters

Name	Type	Default	Description
text	string		The string to inject as text input.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe

Properties

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

Events

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.