Virtual Cursor Update: APIs!
Do you have a complex, mouse-driven UI in your game, that doesn’t work as well on a gamepad? Our solution, the Gamepad Virtual Cursor, just got even better!
We’re excited to bring you the next major update for Virtual Cursor: APIs! Through the API, developers are given additional options to set the state of the Virtual Cursor within code. This API includes:
- Toggle the Virtual Cursor On/Off
- Example - turn on when a popup UI appears, turn off after a selection is made
- Specify a starting UI object/location when Virtual Cursor when appears
- If no start object is specified, the cursor starts in the default starting location
- Query the current state of the Virtual Cursor
- Combine Virtual Cursor with the default UI selection (highlight) mode
- Using the API, developers can use Virtual Cursor in specific menus/UI’s and the default UI selection mode everywhere else
- Several bug fixes and smaller improvements (details below)
Demo Example
VCAPI_Menu_Example.rbxl (40.1 KB)
Previous Posts
Functions
EnableGamepadCursor
GamepadService:EnableGamepadCursor(guiObject: Instance)
For any situation where the cursor starts, it fires a property changed signal on GamepadCursorEnabled.
Input: (guiOjbect: Instance) |
Cursor Starting Position |
|---|---|
nil |
Default position. |
| Not a GuiObject | Cursor does not appear, errors. |
| Not a child of BasePlayerGui | Cursor does not appear, errors. |
GuiObject has Visible set to false or any parent visible set to false. |
Default position with warning. |
Child of ScreenGui with Enabled set to false |
Default position with warning. |
| Child of BillboardGui or SurfaceGui | Default position with warning. |
| GuiObject outside the viewport (Or, any part of the gui object that’s off screen) | Default position with warning. |
| Child of ScrollingFrame with clipping set to false: GuiObject outside of scrolling frame (Object child of scrolling frame and not visible on screen) | Default position with warning. |
| Child of ScrollingFrame with clipping set to true: GuiObject outside scrolling frame window but inside viewport | GuiObject moves into the scrolling frame and starts the cursor centered over the object. |
| GuiObject inside the frame and visible | Cursor starts centered on the GuiObject. |
If the cursor is already active, calling EnableGamepadCursor again will reposition the cursor over that object (if it is valid). If it isn’t valid, it will print the same warning and the cursor will not move position.
DisableGamepadCursor
GamepadService:DisableGamepadCursor()
Turns off the Virtual Cursor if it is on and fires a property changed signal on GamepadCursorEnabled
Property
GamepadCursorEnabled: True when the gamepad cursor is active, false otherwise
Code Examples:
Example 1: Basic toggle
In this example, the user must press buttonX on a gamepad to enable the cursor on the specified UI button and press buttonY to disable the cursor. Paste this into a LocalScript that is a child of a GuiObject (TextButton, ImageButton, etc) under StarterGui.
-- In a LocalScript:
local GamepadService = game:GetService("GamepadService")
local UserInputService = game:GetService("UserInputService")
local button = script.Parent
UserInputService.InputBegan:Connect(function(input, processed)
if input.KeyCode == Enum.KeyCode.ButtonX then
GamepadService:EnableGamepadCursor(button)
end
end)
UserInputService.InputBegan:Connect(function(input, processed)
if input.KeyCode == Enum.KeyCode.ButtonY then
GamepadService:DisableGamepadCursor()
end
end)
Example 2: Start Virtual Cursor on popup
This example starts the Virtual Cursor when a popup appears. Try it out here!
VCAPI_Menu_Example.rbxl (40.1 KB)
This LocalScript under the TextLabel in StarterGui waits for the user to press ButtonX on their gamepad. It then enables the menu and positions the Virtual Cursor over the cancel button.
-- In a LocalScript:
local GamepadService = game:GetService("GamepadService")
local UserInputService = game:GetService("UserInputService")
local button = script.Parent
local teleportMenu = button.Parent.TeleportMenu
local buttonCancel = teleportMenu.Cancel
UserInputService.InputBegan:Connect(function(input, processed)
if input.KeyCode == Enum.KeyCode.ButtonX then
teleportMenu.Visible = true
button.Visible = false
GamepadService:EnableGamepadCursor(buttonCancel)
end
end)
When the cancel button is activated, the menu closes and the Virtual Cursor disappears.
-- In a LocalScript
local GamepadService = game:GetService("GamepadService")
local button = script.Parent
local teleportMenu = button.Parent.Parent.TextLabel
button.Activated:Connect(function(obj, num)
teleportMenu.Visible = true
button.Parent.Visible = false
GamepadService:DisableGamepadCursor()
end)
How to Turn On the Virtual Cursor
Use the property on StarterGui called VirtualCursorMode, to opt-in to the Virtual Cursor!
This property includes three settings:
- Disabled - turns off the Virtual Cursor and uses the current UI navigation behavior
- Enabled - turns on the Virtual Cursor
- Default - this is currently set as “Disabled”
Set the Virtual Cursor “ Enabled ” to allow your players to use this feature.
Additional Fixes & Improvements
- TextBox support
- Virtual Cursor will toggle back on if it was active
- The new flow is: Virtual Cursor on → other input (keyboard/mouse/etc) disables it → gamepad input → Virtual Cursor will toggle back on
- Virtual Cursor triggers mouse events
- Mouse move/enter/leave will fire from left thumbstick inputs
- Mouse down/up/click/etc will fire from buttonA inputs
- Suports dragging, billboard and surfacegui, click detector, various API’s
- Virtual Cursor moves to the bottom of the screen correctly
- Virtual Cursor can interact with proximity prompts
- Virtual Cursor is able to equip and activate tools
- Virtual Cursor can scroll frames with right thumbstick
- Virtual Cursor doesn’t show the scroll icons if it cannot scroll in that direction
Known Issues:
-
Virtual Cursor APIs not currently active for version of Roblox that is downloaded from the Windows Store
The Virtual Cursor APIs now work for Roblox downloaded from the Windows Store. -
The starting position for the Virtual Cursor is slightly off on XBox.
The starting position for the Virtual Cursor is now fixed on XBox.
Feedback
The API was the top request we received from the community on this feature.
If you have additional feedback or issues, please reply with the details in a comment on this post. Also, if you enable the Virtual Cursor in your experience, please leave a link to it below as we’d like to test it out in your game!
We are particularly interested in hearing whether you were interested in this feature, but didn’t have enough control over it, and the API now suits your needs.
Your feedback will help us continually improve this feature.
