Camera¶
A class which defines a view of the 3D world.
Description¶
The Camera object defines a view of the 3D world. In a running experience,
each client has its own Camera object which resides in that client's local
Workspace, accessible through the Workspace.CurrentCamera
property.
The most important camera properties are:
-
CFrame which represents the position and orientation of the camera.
-
CameraType which is read by the experience's camera scripts and determines how the camera should update each frame.
-
CameraSubject which is read by the experience's camera scripts and determines what object the camera should follow.
-
FieldOfView which represents the visible extent of the observable world.
-
Focus which represents the point the camera is looking at. It's important this property is set, as certain visuals will be more detailed and will update more frequently depending on how close they are to the focus point.
See Customizing the Camera for more information on how to adjust and customize the camera's behavior.
Storing Multiple Cameras¶
Note that when changing Workspace.CurrentCamera to a new Camera, all other Cameras directly descending from Workspace will be destroyed. If you need to store multiple cameras and swap between them on demand, it's recommended that you store them in a Folder or Model under Workspace, inside which they will remain even when CurrentCamera is changed.
Inheritance¶
Object → Instance → PVInstance → Camera
Nova inheritance: Instance → Camera
Known subclasses: ViewportCamera
Properties¶
CameraSubject Supported Property The Humanoid or BasePart that is the Camera subject.
The Humanoid or BasePart that is the Camera subject.
CameraSubject accepts a variety of Instances. The
default camera scripts respond differently to the available settings:
-
By default, the camera scripts follow the local character's Humanoid, factoring in the humanoid's current state and Humanoid.CameraOffset.
-
When set to a BasePart, the camera scripts follow its position, with a vertical offset in the case of VehicleSeats.
CameraSubject cannot be set to nil. Attempting to do so will revert it
to its previous value.
To restore CameraSubject to its default value, set it to the local
character's Humanoid:
CameraType Supported Property Specifies the CameraType to be read by the camera scripts.
Specifies the CameraType to be read by the camera scripts.
The default Roblox camera scripts have several built-in behaviors. Setting this property toggles between the various CameraType behaviors. Note that some camera types require a valid CameraSubject to work correctly.
The default camera scripts will not move or update the camera if
CameraType is set to CameraType.Scriptable. For more information
on positioning and orienting the camera manually, see
CFrame.
For all CameraType settings except CameraType.Scriptable, the
CameraSubject property represents the object
whose position the camera's Focus is set to.
CFrame Supported Property The CFrame of the Camera, defining its position and orientation in the 3D world.
This property is the CFrame of the Camera, defining its position and orientation in the 3D world. Note that some transformations, such as the rotation of the head when using VR devices, are not reflected in this property, so you should use GetRenderCFrame() to obtain the "true" CFrame of the camera.
You can move the camera by setting this property. However, the default camera scripts also set it, so you should either:
-
Set the camera CameraType to CameraType.Scriptable so that the default camera scripts will not update the camera's CFrame. This method is simplest and recommended in most cases.
-
Completely replace the default camera scripts with alternatives. This approach is only recommended if you do not need any default camera functionality.
The most intuitive way to position and orient the Camera is by
using the CFrame.lookAt() constructor. In the following
example, the Camera is positioned at
Datatype.Vector3.new(0, 10, 0) and is oriented to be looking towards
Datatype.Vector3.new(10, 0, 0).
local camera = workspace.CurrentCamera
camera.CameraType = Enum.CameraType.Scriptable
local pos = Vector3.new(0, 10, 0)
local lookAtPos = Vector3.new(10, 0, 0)
camera.CFrame = CFrame.lookAt(pos, lookAtPos)
Although the camera can be placed in the manner demonstrated above, you may want to animate it to move smoothly from one CFrame to another. For this, you can either:
- Set the camera's position/orientation every frame with RunService.BindToRenderStep() and the CFrame.Lerp() method.
- Create and play a Tween that animates the position/orientation of the camera:
local Players = game:GetService("Players")
local TweenService = game:GetService("TweenService")
local camera = workspace.CurrentCamera
camera.CameraType = Enum.CameraType.Scriptable
local player = Players.LocalPlayer
local character = player.Character
if not character or character.Parent == nil then
character = player.CharacterAdded:Wait()
end
local pos = camera.CFrame * Vector3.new(0, 20, 0)
local lookAtPos = character.PrimaryPart.Position
local targetCFrame = CFrame.lookAt(pos, lookAtPos)
local tween = TweenService:Create(camera, TweenInfo.new(2), {CFrame = targetCFrame})
tween:Play()
CoordinateFrame Supported Property Deprecated The current position and rotation of the Camera. For most CameraTypes, the rotation is set such that the CoordinateFrame lookVector is pointing at th…
The current position and rotation of the Camera. For most CameraTypes, the rotation is set such that the CoordinateFrame lookVector is pointing at the Focus.
The old version of the CFrame property which functions identically to it.
This item should be used in a LocalScript in order to work as expected online.
FieldOfView Supported Property Sets the angle of the camera's vertical field of view.
Sets the angle of the camera's vertical field of view.
The FieldOfView (FOV) property sets how many degrees in the vertical
direction the camera can view. This property is clamped between 1 and
120 degrees and defaults at 70. Very low or very high fields of view
are not recommended as they can be disorientating to players.
Note that uniform scaling is enforced, meaning the vertical and horizontal field of view are always related by the aspect ratio of the screen.
Suggested uses for FieldOfView include:
- Reducing FOV to give the impression of magnification, for example when using binoculars.
- Increasing FOV when the player is "sprinting" to give the impression of a lack of control.
Note that FieldOfView represents the field of view that is visible by
the Camera rendering into the fullscreen area which may be
occluded by notches or screen cutouts on some devices. See
ViewportSize for more information.
Focus Supported Property Sets the area in 3D space that is prioritized by Roblox's graphical systems.
Sets the area in 3D space that is prioritized by Roblox's graphical systems.
Certain graphical operations the engine performs, such as updating
lighting, can take time or computational effort to complete. The camera's
Focus property tells the engine which area in 3D space to prioritize
when performing such operations. For example, dynamic lighting from
objects such as PointLights may not render at distances
far from the focus.
The default Roblox camera scripts automatically set Focus to follow the
CameraSubject (usually a Humanoid).
However, Focus will not automatically update when
CameraType is set to
CameraType.Scriptable or when the default camera scripts are not
being used. In these cases, you should update Focus every frame, using
RunService.BindToRenderStep() method at the
RenderPriority.Camera priority.
Focus has no bearing on the position or orientation of the camera; see
CFrame for this.
focus Supported Property Deprecated
No description available.
HeadLocked Supported Property Toggles whether the camera will automatically track the head motion of a player using a VR device.
Toggles whether the camera will automatically track the head motion of a
player using a VR device. When true (default), the engine combines
CFrame with the UserCFrame of the user's head
to render the player's view with head tracking factored in. The view will
be rendered at the following CFrame:
local UserInputService = game:GetService("UserInputService")
local camera = workspace.CurrentCamera
local headCFrame = UserInputService:GetUserCFrame(Enum.UserCFrame.Head)
headCFrame = headCFrame.Rotation + headCFrame.Position * camera.HeadScale
-- This will be equivalent to Camera:GetRenderCFrame()
local renderCFrame = camera.CFrame * headCFrame
It is recommended to not disable this property for the following reasons:
- Players may experience motion sickness if an equivalent head tracking solution is not added.
- The Roblox Engine performs latency optimizations when
HeadLockedis true.
See Also¶
- VRService.GetUserCFrame() which can be used to obtain the CFrame of the head.
- VRService.RecenterUserHeadCFrame() which is used to recenter the head to the current position and orientation of the VR device.
- The GetRenderCFrame() method which returns the CFrame combined with the CFrame of the user's head.
ViewportSize Supported Property The dimensions of the device safe area on a Roblox client.
The dimensions of the device safe area on a Roblox client.
ViewportSize returns the dimensions of the device safe area on the
current screen. This area is a rectangle which includes the Roblox top bar
area but does not include any device notches or screen cutouts. The units
of ViewportSize are Roblox UI offset units which may be different from
native display pixels.
As noted above, ViewportSize is not equal to the fullscreen area size on
displays with cutouts or notches. To obtain the fullscreen area size on
all displays, you can query the
AbsoluteSize property of a
ScreenGui with ScreenInsets set to
None. See ScreenInsets for a more
information about how screen areas are defined.
Finally, note that ViewportSize is not the actual viewport size the
camera uses for rendering (the camera renders in the fullscreen area).
Also, the FieldOfView and
DiagonalFieldOfView properties are
based on the fullscreen area, not ViewportSize.
Camera Updates¶
Only the Camera currently referred to by
Workspace.CurrentCamera has its ViewportSize updated each frame
during the PreRender step. The ViewportSize
of all other cameras in your experience won't be updated, including those
used for ViewportFrames.
Methods¶
GetPanSpeed Supported Function Deprecated Returns the current 'pan' speed of the Camera.
GetRenderCFrame Supported Function Returns the actual CFramewhere the Camera is being rendered, accounting for any roll applied and the impact of VR devices.
Returns the actual CFramewhere the Camera is being rendered, accounting for any roll applied and the impact of VR devices.
This method returns the actual CFrame of the Camera as it is rendered, including the impact of VR (VR head transformations are not applied to the CFrame property, so it is best practice to use GetRenderCFrame() to obtain the "true" CFrame of a player's view).
For example, when using VR, the Camera is actually rendered at the following CFrame:
local UserInputService = game:GetService("UserInputService")
local camera = workspace.CurrentCamera
local headCFrame = UserInputService:GetUserCFrame(Enum.UserCFrame.Head)
headCFrame = headCFrame.Rotation + headCFrame.Position * camera.HeadScale
renderCFrame = camera.CFrame * headCFrame
The camera's render CFrame will only be changed to account for the head when the HeadLocked property is true.
GetRoll Supported Function Deprecated Returns in radians the current roll, or rotation around the camera's Z-axis, applied to the Camera using SetRoll().
Returns in radians the current roll, or rotation around the camera's Z-axis, applied to the Camera using SetRoll().
This method returns, in radians, the current roll applied to the Camera using SetRoll(). Roll is defined as rotation around the camera's Z-axis.
This method only returns roll applied using the SetRoll() method. Roll manually applied to the camera's CFrame is not accounted for. To obtain the actual roll of the Camera, including roll manually applied, you can use the following snippet:
GetTiltSpeed Supported Function Deprecated Returns the current tilt speed of the Camera.
Interpolate Supported Function Deprecated Tweens the Camera in a linear fashion towards a new CFrame and Focus over a given duration.
This method tweens the Camera in a linear fashion towards a new CFrame and Focus over a given duration, for example:
local camera = workspace.CurrentCamera
camera.CameraType = Enum.CameraType.Scriptable
camera:Interpolate(
CFrame.new(0, 10, 100),
CFrame.new(0, 0, 100),
5
)
Throughout the tween, the camera's CFrame will be orientated towards the camera's Focus.
When the tween has completed, the camera's InterpolationFinished event will fire.
If this method is called while the Camera is already tweening, the older tween will be stopped (without firing InterpolationFinished) and overridden by the new tween.
Interpolate can only be used if the current
CameraType is Scriptable, regardless of
whether the default camera scripts are being used. If it is used with any
other CameraType an error will be thrown.
You are advised to use TweenService to tween the Camera instead as it is more reliable and offers a variety of easing styles. See below for an example:
local TweenService = game:GetService("TweenService")
local camera = workspace.CurrentCamera
camera.CameraType = Enum.CameraType.Scriptable
local tween = TweenService:Create(
camera,
TweenInfo.new(5, Enum.EasingStyle.Quad, Enum.EasingDirection.Out),
{
CFrame = CFrame.new(0, 10, 100),
Focus = CFrame.new(0, 0, 100)
}
)
tween:Play()
Roblox reference signature
PanUnits Supported Function Deprecated Pans the Camera around the Focus in 45 degree increments around the Y axis.
This method pans the Camera around the Focus in 45 degree increments around the Y axis.
The rotation is applied to the camera's CFrame property.
This method pans the Camera in 45 degree increments, for example:
workspace.CurrentCamera:PanUnits(1) -- 45 degrees
workspace.CurrentCamera:PanUnits(-2) -- -90 degrees
PanUnits does not require the CameraType to be
Scriptable.
ScreenPointToRay Supported Function Creates a unit Ray from a position on the screen (in pixels), at a set depth from the Camera orientated in the camera's direction. Accounts for the G…
Creates a unit Ray from a position on the screen (in pixels), at a set depth from the Camera orientated in the camera's direction. Accounts for the GUI inset.
This method creates a unit Ray from a 2D position on the screen (defined in pixels), accounting for the GUI inset. The Ray originates from the Vector3 equivalent of the 2D position in the world at the given depth (in studs) away from the Camera.
As this method acknowledges the GUI inset, the offset applied to GUI elements (such as from the top bar) is accounted for. This means the screen position specified will start in the top left corner below the top bar. For an otherwise identical method that does not account for the GUI offset, use ViewportPointToRay().
As the Ray created is a unit ray, it is only one stud long. To create a longer ray, you can do the following:
local camera = workspace.CurrentCamera
local length = 500
local unitRay = camera:ScreenPointToRay(100, 100)
local extendedRay = Ray.new(unitRay.Origin, unitRay.Direction * length)
This method only works for the current Workspace camera. Other
cameras, such as those you create for a ViewportFrame, have an
initial viewport size of (1, 1)
SetCameraPanMode Supported Function Deprecated Sets the mobile camera pan mode. Nova's input code reads it.
Sets the mobile camera pan mode. Nova's input code reads it.
Nova stores the mode and the 2016 input/camera code checks for
Classic before applying edge-bump panning.
SetRoll Supported Function Deprecated Sets camera roll. Only applies while the Camera is in Scriptable mode.
Sets camera roll. Only applies while the Camera is in Scriptable mode.
Nova applies the roll when the camera type is Scriptable/Locked; otherwise it warns and resets roll to zero. This matches the legacy behavior rather than the modern claim that it has no effect.
TiltUnits Supported Function Deprecated Tilts the Camera around its Focus in 10 degree increments around the camera's X axis.
Tilts the Camera around its Focus in 10 degree increments around the camera's X axis.
This method tilts the Camera by rotating it around the Focus around the camera's X axis by a given multiple of 10 degrees.
The rotation is applied to the camera's CFrame
property and is constrained between -81.05 and 81.05 degrees.
ViewportPointToRay Supported Function Creates a unit Ray from a position on the viewport (in pixels), at a given depth from the Camera, orientated in the camera's direction. Does not acco…
Creates a unit Ray from a position on the viewport (in pixels), at a given depth from the Camera, orientated in the camera's direction. Does not account for the CoreUISafeInsets inset.
This method creates a unit Ray from a 2D position in device safe viewport coordinates, defined in pixels. The ray originates from the Vector3 equivalent of the 2D position in the world at the given depth (in studs) away from the Camera.
As illustrated below, (0, 0) corresponds to the top‑left point of the
Roblox top bar. This means that the input 2D position does not account
for the CoreUISafeInsets inset, but it does account
for any DeviceSafeInsets.
Note that UI instances use a different coordinate system (GuiObject.AbsolutePosition uses the CoreUISafeInsets viewport coordinate system while this method uses the DeviceSafeInsets viewport coordinate system). If you would like to specify position in core UI coordinates, please use ScreenPointToRay().
Also note that this method only works for the
Workspace.CurrentCamera camera. Other cameras, such as those you
create for a ViewportFrame, have an initial viewport size of
(1, 1) and are only updated after you set them to
CurrentCamera. The mismatch in viewport
size causes the camera to return a ray with an incorrect
Ray.Direction.
This method can be used in conjunction with the ViewportSize property to create a ray from the centre of the screen, for example:
local camera = workspace.CurrentCamera
local viewportPoint = camera.ViewportSize / 2
local unitRay = camera:ViewportPointToRay(viewportPoint.X, viewportPoint.Y, 0)
As the Ray created is a unit ray, it is only one stud long. To create a longer ray, you can do the following:
WorldToScreenPoint Supported Function Returns the screen location and depth of a Vector3 worldPoint and whether this point is within the bounds of the screen. Accounts for the GUI inset.
This method returns the screen location and depth of a Vector3
worldPoint and whether this point is within the bounds of the screen.
This method takes in account the current GUI inset, such as the space occupied by the top bar, meaning that the 2D position returned is in the same term as GUI positions and can be used to place GUI elements. For an otherwise identical method that ignores the GUI inset, see WorldToViewportPoint().
local camera = workspace.CurrentCamera
local worldPoint = Vector3.new(0, 10, 0)
local vector, onScreen = camera:WorldToScreenPoint(worldPoint)
local screenPoint = Vector2.new(vector.X, vector.Y)
local depth = vector.Z
Note this method does not perform any raycasting and the boolean
indicating whether worldPoint is within the bounds of the screen will be
true regardless of whether the point is obscured by
BaseParts or Terrain.
WorldToViewportPoint Supported Function Returns the screen location and depth of a Vector3 worldPoint and whether this point is within the bounds of the screen. Does not account for the GUI…
This method returns the screen location and depth of a Vector3
worldPoint and whether this point is within the bounds of the screen.
This method does not take in account the current GUI inset, such as the space occupied by the top bar, meaning that the 2D position returned is taken from the top left corner of the viewport. Unless you are using ScreenGui.IgnoreGuiInset, this position is not appropriate for placing GUI elements.
For an otherwise identical method that accounts for the GUI inset, see WorldToScreenPoint().
local camera = workspace.CurrentCamera
local worldPoint = Vector3.new(0, 10, 0)
local vector, onScreen = camera:WorldToViewportPoint(worldPoint)
local viewportPoint = Vector2.new(vector.X, vector.Y)
local depth = vector.Z
Note this method does not perform any raycasting and the boolean
indicating whether worldPoint is within the bounds of the screen will be
true regardless of whether the point is obscured by
BaseParts or Terrain.
ViewportFrame Cameras¶
Only Workspace.CurrentCamera has its internal viewport dimensions
updated by the engine each frame. Cameras used inside a
ViewportFrame do not receive viewport updates, so the X and Y
components returned by this method will be in the range [0, 1] rather than
in pixels. In practice, this means the returned values can be used as
scale coordinates (for example,
Datatype.UDim2|UDim2.fromScale(vector.X, vector.Y)) to position GUI
elements relative to the ViewportFrame.
Zoom Supported Function
No description available.
RobloxScriptSecurityEvents¶
FirstPersonTransition Supported Event
No description available.
RobloxPlaceSecurityInterpolationFinished Supported Event Deprecated Fired when the Camera has finished interpolating usingInterpolate().
Fired when the Camera has finished interpolating usingInterpolate().
This event fires when the Camera has finished interpolating using the Camera.Interpolate() method. It will not fire if a tween is interrupted due to Camera.Interpolate() being called again.
You are advised to use TweenService to animate the Camera instead, as it is more reliable and provides more options for easing styles.
Inherited members¶
Inherited from Instance: 8 properties, 36 methods, 7 events. They are documented on the base class page.
10 modern Roblox member(s) are not implemented yet — expand to inspect
Members declared by Roblox's Camera class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.
Properties¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
DiagonalFieldOfView |
DiagonalFieldOfView: float |
Not yet | Sets the angle of the camera's diagonal field of view. | NotReplicated |
FieldOfViewMode |
FieldOfViewMode: FieldOfViewMode |
Not yet | Determines the FOV value of the Camera that's invariant under viewport size changes. | — |
HeadScale |
HeadScale: float |
Not yet | Sets the scale of the user's perspective of the world when using VR. | — |
MaxAxisFieldOfView |
MaxAxisFieldOfView: float |
Not yet | Sets the angle of the camera's field of view along the longest viewport axis. | NotReplicated |
NearPlaneZ |
NearPlaneZ: float |
Not yet | Describes the negative Z offset, in studs, of the camera's near clipping plane. | ReadOnly, NotReplicated |
VRTiltAndRollEnabled |
VRTiltAndRollEnabled: bool |
Not yet | Toggles whether to apply tilt and roll from the CFrame property while the player is using a VR device. | — |
Methods¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
GetLargestCutoffDistance |
Camera:GetLargestCutoffDistance(ignoreList: Instances): float |
Not yet | Returns how much the Camera needs to be pushed towards its Focus in order to make sure there is no obstructions between the [Focus](Camer… | — |
GetPartsObscuringTarget |
Camera:GetPartsObscuringTarget(castPoints: Array, ignoreList: Instances): Instances |
Not yet | Returns an array of BaseParts that are obscuring the lines of sight between the camera's CFrame and the cast points. | — |
SetImageServerView |
Camera:SetImageServerView(modelCoord: CFrame): null |
Not yet | — | RobloxScriptSecurity |
ZoomToExtents |
Camera:ZoomToExtents(boundingBoxCFrame: CFrame, boundingBoxSize: Vector3): null |
Not yet | Adjusts the CFrame so that the specified bounding box is fully visible within the camera's viewport. | — |
Roblox reference: Camera
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.