VirtualInput
Simulates mouse, keyboard, and pointer input as if it were performed by a real player.
| Memory category | Instances |
|---|
Member index 6
| History | Member | |
|---|---|---|
| 720 | SendKey(isPressed: bool, keyCode: KeyCode, isRepeatedKey: bool = false): null | |
| 720 | SendMouseButton(position: Vector2, button: UserInputType, isDown: bool, repeatCount: int = 0): null | |
| 720 | SendMouseDelta(positionDelta: Vector2): null | |
| 720 | SendMousePosition(position: Vector2): null | |
| 720 | SendPointerAction(position: Vector2, pointerAction: Dictionary): null | |
| 720 | SendTextInput(text: string): null | |
| inherited from Object | ||
| 647 | ClassName: string | |
| 647 | className: string | |
| 647 | GetPropertyChangedSignal(property: string): RBXScriptSignal | |
| 647 | IsA(className: string): bool | |
| 650 | isA(className: string): bool | |
| 647 | Changed(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
- 720 Change Security of SendTextInput from PluginSecurity to None
- 720 Change Security of SendPointerAction from PluginSecurity to None
- 720 Change Security of SendMousePosition from PluginSecurity to None
- 720 Change Security of SendMouseDelta from PluginSecurity to None
- 720 Change Security of SendMouseButton from PluginSecurity to None
- 720 Change Security of SendKey from PluginSecurity to None
- 715 Add SendTextInput
- 715 Add SendPointerAction
- 715 Add SendMousePosition
- 715 Add SendMouseDelta
- 715 Add SendMouseButton
- 715 Add SendKey
- 715 Add VirtualInput
Members 6
SendKey
| Parameters (3) | Default | |
|---|---|---|
| isPressed | bool | |
| keyCode | KeyCode | |
| isRepeatedKey | bool | false |
| 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 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.
| Thread safety | Unsafe |
|---|
SendMouseButton
| Parameters (4) | Default | |
|---|---|---|
| position | Vector2 | |
| button | UserInputType | |
| isDown | bool | |
| repeatCount | int | 0 |
| 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.
| Thread safety | Unsafe |
|---|
History 2
- 720 Change Security of SendMouseButton from PluginSecurity to None
- 715 Add SendMouseButton
SendMouseDelta
| Parameters (1) | ||
|---|---|---|
| positionDelta | Vector2 | |
| 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().
| Thread safety | Unsafe |
|---|
History 2
- 720 Change Security of SendMouseDelta from PluginSecurity to None
- 715 Add SendMouseDelta
SendMousePosition
| Parameters (1) | ||
|---|---|---|
| position | Vector2 | |
| 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.
| Thread safety | Unsafe |
|---|
History 2
- 720 Change Security of SendMousePosition from PluginSecurity to None
- 715 Add SendMousePosition
SendPointerAction
| Parameters (2) | ||
|---|---|---|
| position | Vector2 | |
| pointerAction | Dictionary | |
| 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.
| Thread safety | Unsafe |
|---|
History 2
- 720 Change Security of SendPointerAction from PluginSecurity to None
- 715 Add SendPointerAction
SendTextInput
| Parameters (1) | ||
|---|---|---|
| text | string | |
| 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.
| Thread safety | Unsafe |
|---|
History 2
- 720 Change Security of SendTextInput from PluginSecurity to None
- 715 Add SendTextInput