VRService
VRService is responsible for handling interactions between Roblox and Virtual Reality (VR). Its methods, properties, and events help you provide the best experience for end users seeking to experience Roblox on VR devices.
Since this service is client-side only, it will only work when used in a LocalScript or a Script with RunContext of Client.
See VR Guidelines for more information on publishing an experience for VR devices.
Code Samples
local VRService = game:GetService("VRService")
local part = workspace.Part
local handOffset = VRService:GetUserCFrame(Enum.UserCFrame.LeftHand)
-- Account for headscale
handOffset = handOffset.Rotation + handOffset.Position * workspace.CurrentCamera.HeadScale
part.CFrame = workspace.CurrentCamera.CFrame * handOffset
Summary
Properties
- read parallel
Automatically adjusts scaling in VR to align the player with their avatar.
- not browsableread parallel
- read parallel
When true, a VR player's view will fade to black when their head collides with an object.
- not replicatedread parallel
Describes what UserCFrame is responsible for input in VR.
- read onlynot replicatedread parallel
Describes whether the user is using a virtual reality device.
Methods
Returns the VRTouchpadMode indicating the mode of a specified VRTouchpad.
Returns a CFrame describing the position & orientation of a specified virtual reality device as an offset from a point in real world space.
Returns true if the specified UserCFrame is available to be listened to.
Recenters the CFrame to the current location of the VR headset being worn by the user.
Requests navigation to the specified CFrame, using the specified Enum.UserCFrame as the origin for the visualizer parabola.
Sets the mode of the specified VRTouchpad to the specified VRTouchpadMode.
Events
Fired when navigation is requested from the VRService.
Fires if the VRTouchpadMode of a VRTouchpad is changed.
Fired when a UserCFrame is changed.
Fires when a UserCFrame gets enabled or disabled.
Properties
AutomaticScaling
When VRService.AutomaticScaling is set to World, Camera.HeadScale adjusts so that the scale of the world is seen from the avatar's perspective. A player with a small avatar will perceive the objects around them as larger than a player with a large avatar will.
AvatarGestures
FadeOutViewOnCollision
When true, a VR player's view fades to black when their head collides with an object. This property prevents players from being able to see through walls while in VR. The default value is true.
GuiInputUserCFrame
The GuiInputUserCFrame property describes what Enum.UserCFrame is responsible for input in VR. For instance, if a VR headset is responsible, the value of this property will be UserCFrame.Head.
To check if Roblox detects any VR devices, which would be responsible for input in VR, you can check the VRService.VREnabled property.
Since VRService only runs client-side, this property will only work when used in a LocalScript.
Code Samples
local VRService = game:GetService("VRService")
if VRService.VREnabled then
print(VRService.GuiInputUserCFrame.Name)
else
print("No VR device detected!")
end
ThirdPersonFollowCamEnabled
VREnabled
This property describes whether the user is using a virtual reality (VR) device.
If a VR device is enabled, you can interact with its location and movement through functions such as UserInputService:GetUserCFrame(). You can also react to VR device movement using the UserInputService.UserCFrameChanged event.
local userInputService = game:GetService("UserInputService")local isUsingVR = userInputService.VREnabledif isUsingVR thenprint("User is using a VR headset!")elseprint("User is not using a VR headset!")end
As UserInputService is client-side only, this property can only be used in a LocalScript.
See also:
Code Samples
local UserInputService = game:GetService("UserInputService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.CharacterAdded:Wait()
local head = character:WaitForChild("Head")
local function TrackHead(inputType, value)
if inputType == Enum.UserCFrame.Head then
head.CFrame = value
end
end
if UserInputService.VREnabled then
-- Set the inital CFrame
head.CFrame = UserInputService:GetUserCFrame(Enum.UserCFrame.Head)
-- Track VR headset movement and mirror for character's head
UserInputService.UserCFrameChanged:Connect(TrackHead)
end
Methods
GetTouchpadMode
The GetTouchpadMode function returns the Enum.VRTouchpadMode indicating the mode of a specified Enum.VRTouchpad.
The returned mode indicates how the user interacts with their touchpad to play the game. For more information about the different types of modes, see the Enum.VRTouchpadMode page.
This can also be used alongside the several UserInputService VR functions and events.
Since VRService only runs client-side, this function will only work when used in a LocalScript.
Parameters
The specified VRTouchpad.
Returns
The mode of the specified VRTouchpad.
Code Samples
local VRService = game:GetService("VRService")
VRService:GetTouchpadMode(Enum.VRTouchpad.Left)
GetUserCFrame
The GetUserCFrame function returns a CFrame describing the position & orientation of a specified virtual reality (VR) device as an offset from a point in real world space.
This function should be used when implementing VR compatibility into a game to obtain and track the movement of a connected VR device.
By using the function, players can implement features such as re-positioning the user's in-game character corresponding to the location of a connected VR device. This can be done by changing the CFrame of the user's in-game character to match the CFrame of the specified VR device using the UserCFrame enum and CFrame value arguments passed by the event.
The VRService service also provides an event VRService.UserCFrameChanged that automatically fires when the CFrame of connected VR device changes - so long it is used in a LocalScript.
Since VRService only runs client-side, this function will only work when used in a LocalScript.
Parameters
The specified UserCFrame.
Returns
Code Samples
local Workspace = game:GetService("Workspace")
local VRService = game:GetService("VRService")
local camera = Workspace.CurrentCamera
local part = script.Parent.Part
local handOffset = VRService:GetUserCFrame(Enum.UserCFrame.LeftHand)
-- Account for headscale
handOffset = handOffset.Rotation + handOffset.Position * camera.HeadScale
part.CFrame = camera.CFrame * handOffset
GetUserCFrameEnabled
The GetUserCFrameEnabled function returns true if the specified Enum.UserCFrame virtual reality device (VR) is available to be listened to.
This can be used to determine whether a specified VR device, (e.g. UserCFrame.Head), is connected to the user's game. If the specified VR device is connected, is it enabled (true). Otherwise, it is disabled (false).
This can also be used alongside the several UserInputService VR functions and events.
Since VRService only runs client-side, this function will only work when used in a LocalScript.
Parameters
The specified type of VR device.
Returns
A boolean indicating whether the specified VR device is enabled (true) or disabled (false).
Code Samples
local VRService = game:GetService("VRService")
local isEnabled = VRService:GetUserCFrameEnabled(Enum.UserCFrame.Head)
if isEnabled then
print("VR device is enabled!")
else
print("VR device is disabled!")
end
RecenterUserHeadCFrame
The RecentUserHeadCFrame function recenters the CFrame of the user's head to the current location of the VR headset being worn by the user.
This function can be used to ensure that the user's in-game head is positioned according to the location of the user's VR headset.
This behaves identically to the UserInputService function, UserInputService:RecenterUserHeadCFrame().
Since VRServiceService only runs client-side, this function will only work when used in a LocalScript.
Returns
Code Samples
local VRService = game:GetService("VRService")
VRService:RecenterUserHeadCFrame()
RequestNavigation
The RequestNavigation function requests navigation to the specified CFrame, using the specified Enum.UserCFrame as the origin for the visualizer parabola.
This can be used to incorporate virtual reality (VR) into your game by providing a means to visualize a navigation path from the user's VR device to a destination.
The VRService has a similar event, VRService.NavigationRequested, used to detect such requests. This can also be used alongside the several UserInputService VR functions and events.
Since VRService only runs client-side, this function will only work when used in a LocalScript.
Parameters
The specified CFrame coordinates.
The VR device for which the navigation is requested.
Returns
Code Samples
local VRService = game:GetService("VRService")
local destination = workspace:FindFirstChild("NavigationDestination")
VRService:RequestNavigation(Enum.UserCFrame.Head, destination.CFrame)
SetTouchpadMode
The SetTouchpadMode function sets the mode of the specified Enum.VRTouchpad to the specified Enum.VRTouchpadMode.
This can be used to change the user's virtual reality (VR) touchpad mode so that the user interacts with the game different using the touchpad. For more information about the different types of modes, see the Enum.VRTouchpadMode page.
This can also be used alongside the several UserInputService VR functions and events.
Since VRService only runs client-side, this function will only work when used in a LocalScript.
Parameters
The specified VRTouchpad you want to set the mode of.
The mode you want to set the specified VRTouchpad to.
Returns
Code Samples
local VRService = game:GetService("VRService")
VRService:SetTouchpadMode(Enum.VRTouchpad.Left, Enum.VRTouchpadMode.Touch)
Events
NavigationRequested
The NavigationRequested event fires when navigation is requested from the VRService for a specified Enum.UserCFrame VR device.
This is fired with a CFrame coordinate and specified UserCFrame indicating the device requesting the navigation.
This VRService event can be used alongside UserInputService service events and functions.
Since the event fires locally, it can only be used in a LocalScript.
Parameters
The requested CFrame coordinates.
Indicates the VR device for which navigation is requested.
Code Samples
local VRService = game:GetService("VRService")
VRService.TouchpadModeChanged:Connect(function(cframe, inputUserCFrame)
print(inputUserCFrame.Name .. " made request with CFrame: " .. cframe)
end)
TouchpadModeChanged
The TouchpadModeChanged event fires if the Enum.VRTouchpadMode of a Enum.VRTouchpad is changed. This event indicates the VRTouchpad that changes, and its new state.
You can use this event to track the states of VRTouchpads connected via the user's client.
This VRService event can be used alongside UserInputService service events and functions.
Since the event fires locally, it can only be used in a LocalScript.
Parameters
The touchpad that changed mode.
The new mode.
Code Samples
local VRService = game:GetService("VRService")
VRService.NavigationRequested:Connect(function(pad, mode)
print(pad.Name .. " Touchpad changed to state: " .. mode.Name)
end)
UserCFrameChanged
The UserCFrameChanged even fires when a Enum.UserCFrame is changed. For instance, this event fires when the user moves a connected VR device.
This can be used alongside VRService:GetUserCFrame() to track the CFrame coordinates of a VR devices, and when it changes/moves. It can also be used alongside UserInputService service events and functions.
Since the event fires locally, it can only be used in a LocalScript.
Parameters
The type of VR device that changed.
The updated CFrame coordinates of the VR device after the change.
Code Samples
local VRService = game:GetService("VRService")
VRService.UserCFrameChanged:Connect(function(userCFrameType, cframeValue)
print(userCFrameType.Name .. " changed. Updated Frame: " .. tostring(cframeValue))
end)
UserCFrameEnabled
The UserCFrameEnabled event fires when a Enum.UserCFrame gets enabled or disabled.
This can be used alongside VRService:GetUserCFrameEnabled() to track whether a specified UserCFrame is enabled, and when its state changes. It can also be used alongside UserInputService service events and functions.
Since the event fires locally, it can only be used in a LocalScript.
Parameters
The UserCFrame getting enabled or disabled.
A boolean indicating whether the UserCFrame is enabled (true) or disabled (false).
Code Samples
local VRService = game:GetService("VRService")
VRService.UserCFrameEnabled:Connect(function(type, enabled)
if enabled then
print(type.Name .. " got enabled!")
else
print(type.Name .. " got disabled!")
end
end)