Reference API Roblox

Engine API

Website

Related

Reference API Roblox

VirtualInput

Simulates mouse, keyboard, and pointer input as if it were performed by a real player.

This class is not replicated. Its interface does not cross the network boundary.
This class is not creatable. Instances of this class cannot be created with Instance.new.
Tags: [NotCreatable, NotReplicated]

Member index 6

HistoryMember
720SendKey(isPressed: bool, keyCode: KeyCode, isRepeatedKey: bool = false): null
720SendMouseButton(position: Vector2, button: UserInputType, isDown: bool, repeatCount: int = 0): null
720SendMouseDelta(positionDelta: Vector2): null
720SendMousePosition(position: Vector2): null
720SendPointerAction(position: Vector2, pointerAction: Dictionary): null
720SendTextInput(text: string): null
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Description

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.

History 13

Members 6

SendKey

Parameters (3)Default
isPressedbool
keyCodeKeyCode
isRepeatedKeyboolfalse
Returns (1)
null

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.

History 2

SendMouseButton

Parameters (4)Default
positionVector2
buttonUserInputType
isDownbool
repeatCountint0
Returns (1)
null

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.

History 2

SendMouseDelta

Parameters (1)
positionDeltaVector2
Returns (1)
null

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

History 2

SendMousePosition

Parameters (1)
positionVector2
Returns (1)
null

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.

History 2

SendPointerAction

Parameters (2)
positionVector2
pointerActionDictionary
Returns (1)
null

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.

History 2

SendTextInput

Parameters (1)
textstring
Returns (1)
null

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.

History 2

Settings