Camera

Show Deprecated
Not Replicated

The Camera object defines a view of the 3D game world.

Where the Camera object is found

In an instance of the game, each client has its own Camera object associated with it. Camera objects exist only upon the viewer's client, residing in that user's local Workspace, and therefore cannot be edited directly from the server.

Each client's particular Camera object can be accessed through the Workspace.CurrentCamera property of the Workspace on that client.

Note, Workspace.CurrentCamera can also be used to find the Camera object in Roblox Studio.

How the Camera object works

The Camera's properties define the current view of the 3D game world. The most important of these being:

  • The Camera.CFrame property represents the position and orientation of the camera.
  • The Camera.Focus property represents the point the camera is looking at. It is important this property is set as it also represents where the game thinks you are in the world. Certain visuals will be more detailed and will update more frequently, depending on how close they are to the Focus. Roblox's default camera scripts take care of this.
  • The Camera.CameraType property is read by the game's camera scripts and determines how the Camera should update each frame.
  • The Camera.CameraSubject property is read by the game's camera scripts and determines what object the Camera should follow.
  • The Camera.FieldOfView property represents the extent of the observable world visible.

How to work with the Camera

Roblox's camera scripts update the Camera's properties every frame dependent on the current Camera.CameraType. This means developers looking to control the Camera themselves have two options.

  1. Setting the Camera.CameraType property to 'Scriptable'. When the Camera is in 'Scriptable' mode the default camera scripts will not update the camera. In most cases this is the easiest option.
  2. Replacing or modifying the default camera scripts in StarterPlayer.StarterPlayerScripts. This is only recommended for advanced developers.

Summary

Properties

The CFrame of the Camera, defining its position and orientation in the 3D world.

The Humanoid or BasePart that is the Camera's subject.

Specifies the CameraType to be read by the camera scripts.

Sets the angle of the Camera's diagonal field of view.

NOT REPLICATED

Sets the angle of the Camera's vertical field of view.

Determines the FOV value of the Camera that's invariant under viewport size changes.

Sets the area in 3D space that is prioritized by Roblox's graphical systems.

Toggles whether the Camera will automatically track the head motion of a player using a VR device.

Sets the scale of the user's head when using VR.

Sets the angle of the Camera's field of view along the longest viewport axis.

NOT REPLICATED

Describes the negative z-offset, in studs, of the Camera's near clipping plane.

READ ONLY
NOT REPLICATED

Describes the dimensions, in pixels, of the client's viewport.

READ ONLY
NOT REPLICATED

Events


Fires when the local user's Camera switches in and out of first person mode.


Fired when the Camera has finished interpolating usingCamera:Interpolate().

Methods


Returns the current 'pan' speed of the Camera.

GetPartsObscuringTarget(castPoints: Array, ignoreList: Objects): Objects  

Returns an array of BaseParts that are obscuring the lines of sight between the Camera's Camera.CFrame and the castPoints.


Returns the actual CFramewhere the Camera is being rendered, accounting for any roll applied and the impact of VR devices.


Returns in radians the current roll, or rotation around the Camera's Z-axis, applied to the Camera using Camera:SetRoll().


Returns the current 'tilt' speed of the Camera.

ScreenPointToRay(x: number, y: number, depth: number): Ray  

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.


Sets the CameraPanMode to be used by the Camera on mobile devices.

SetImageServerView(modelCoord: CFrame): void  


SetRoll(rollAngle: number): void  

Sets the current rotation applied around the Camera's Z-axis.


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 GUI inset.

WorldToScreenPoint(worldPoint: Vector3): Tuple  

Returns the 2D screen location of a Vector3 position in the world, the depth of it from the screen and whether it is visible. Accounts for the GUI inset.


Returns the 2D screen location of a Vector3 position in the world, but does not account for the GUI inset.

Zoom(distance: number): boolean  


Properties

CFrame

This property is the CFrame of the Camera and definies its position and orientation in the 3D world.

Some transformations, such as the rotation of the head when using VR devices are not reflected in this property. For this reason, developers should use Camera:GetRenderCFrame() to obtain the 'true' CFrame of the camera.

How to set the camera's CFrame

You can move the camera by setting the CFrame property. However, the default camera scripts also set the CFrame property. When manually setting the CFrame property, it may be overwritten by the [camera scripts][1] which update every frame. There are two options to address this:

  1. Set the camera Camera.CameraType to 'Scriptable'. When the camera is 'Scriptable' the default scripts will not update the CFrame. This method is simplest and recommended in most cases

  2. Replace the default camera scripts with an alternative that doesn't interfere with the developer's desired implementation. This is only recommended when developers do not need any default camera's functionality

How the Camera CFrame works

Like all CFrame data, the camera CFrame represents a position and an orientation.

The most intuitive way to position and orientate the Camera is by using the new CFrame constructor with the pos and lookAt parameters, for example:


1local pos = Vector3.new(0, 10, 0)
2local lookAt = Vector3.new(10, 0, 0)
3local cameraCFrame = CFrame.new(pos, lookAt)
4workspace.CurrentCamera.CFrame = cameraCFrame
5

In the above example the Camera is positioned at Vector3.new(0, 10, 0) and oriented to be looking towards Vector3.new(10, 0, 0).

Animating the Camera CFrame

Although the camera can be placed in the manner demonstrated above, you may want to animate the Camera to smoothly move from one CFrame to another. For this, there are a number of options:

  1. Creating a Tween using TweenService that animates the CFrame property of the camera. See the code sample below for an example of this
  2. Setting the camera CFrame every frame with RunService:BindToRenderStep() and the lerp CFrame method

CameraSubject

When using the default camera scripts, the CameraSubject property has two roles:

  • Defining the object the Camera is to follow, in the case of the 'Follow', 'Attach', 'Track', 'Watch' and 'Custom' CameraTypes
  • For all CameraTypes but 'Scriptable', the object whose position the Camera's Camera.Focus will be set to

CameraSubject accepts a variety of Instances. The default camera scripts respond differently to different CameraSubject types:

You can configure the Camera to follow a Model by setting the CameraSubject to the model's Model.PrimaryPart.

The CameraSubject cannot be set to nil. If it is, it will revert to its previous value.

To restore the CameraSubject to its default value, set it to the LocalPlayer's Humanoid like so:


1local Players = game:GetService("Players")
2
3local localPlayer = Players.LocalPlayer
4
5local function resetCameraSubject()
6 if workspace.CurrentCamera and localPlayer.Character then
7 local humanoid = localPlayer.Character:FindFirstChildOfClass("Humanoid")
8 if humanoid then
9 workspace.CurrentCamera.CameraSubject = humanoid
10 end
11 end
12end
13

CameraType

The default Roblox camera scripts have several built in behaviors. Setting the CameraType of a player's Camera will toggle between these behaviors. Note some CameraType's require a valid Camera.CameraSubject to work correctly.

The above only applies when you use the default Roblox [camera scripts][1]. If you write your own camera scripts, you can choose to listen to CameraType and implement your own behaviors or ignore the property entirely.

Manually controlling the Camera

In some cases you may wish to manually control the Camera (for example during a cut-scene). The best way to do this is by setting the CameraType to 'Scriptable'. The default camera scripts will not move or update the Camera on its own if CameraType is set to 'Scriptable'. This means you can freely modify the Camera using its properties and functions. For more information on positioning and orientating the Camera manually see the Camera.CFrame page.

If you want complete control over the camera at all times, you may replace the default camera scripts with your own.

DiagonalFieldOfView

Not Replicated

Sets how many degrees in the diagonal direction (from one corner of the viewport to its opposite corner) the camera can view.

See FieldOfView for a more general explanation of FOV.

FieldOfView

Field of view, often shortened to FOV, is the extent of the observable game world that can be seen on screen at a given moment. The FieldOfView 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.

The FieldOfView property sets how many degrees in the vertical direction (y-axis) the camera can view. Uniform scaling is enforced meaning the vertical and horizontal field of view are always related by the aspect ratio of the screen. This means the FieldOfView property also determines the horizontal field of view.

See the images below for an example of how different FieldOfView settings can impact the extent of the perceptive game world. At a FOV of 70, a considerable portion of the game world is visible:

A demonstration of the default FOV of 70

However when the FOV is reduced to 30, although the Camera's Camera.CFrame has not changed, a much smaller portion of the game world is rendered:

A demonstration of a reduced FOV of 30

Suggested uses for FieldOfView

Changing FOV can produce a variety of effects, such as:

  • 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

FieldOfViewMode

The Camera's FOV must be updated to reflect ViewportSize changes. The value of the FieldOfViewMode property determines which FOV value will be kept constant.

For example, when the value of FieldOfViewMode is set to FieldOfViewMode.Vertical, the horizontal FOV is updated when the viewport is resized, while the vertical FOV is kept constant. On the other hand, if the value is set to FieldOfViewMode.Diagonal, both horizontal and vertical FOV might be changed to keep the diagonal FOV constant.

Focus

The Camera Focus is a CFrame that determines the area in 3D space the graphics engine will prioritize.

Certain graphical operations Roblox performs, such as updating lighting, can take a lot of time or computational effort to complete. Focus tells Roblox the 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 the Focus to follow the Camera.CameraSubject (usually a Humanoid). However, Focus will not be automatically updated in the following cases:

  • When the Camera.CameraType is set to 'Scriptable'
  • When the default camera scripts are not being used

In these cases, you should update Focus every frame, using RunService:BindToRenderStep() function at the 'Camera' RenderPriority.

Focus has no bearing on the positioning or orientation of the Camera (see Camera.CFrame for this).

HeadLocked

Un-linking the camera from a VR user's head motions can cause motion sickness. This property should only be set to false after extensive testing.

Toggles whether the Camera will automatically track the head motion of a player using a VR device.

When HeadLocked is true, the engine will combine the Camera Camera.CFrame with the CFrame of the user's head to render the position and orientation of the Camera correctly. The camera will be rendered at the following CFrame:


1local UserInputService = game:GetService("UserInputService")
2local headCFrame = UserInputService:GetUserCFrame(Enum.UserCFrame.Head)
3renderCFrame = workspace.CurrentCamera.CFrame * headCFrame
4

Disabling HeadLocked

You are recommended not to disable HeadLocked 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 HeadLocked is true

However in some circumstances you may wish to develop your own head tracking systems. For example, you may want custom camera transformations that restrict or augment the CFrame of the head.

See also:

HeadScale

HeadScale is the scale of the user's head when using VR.

The unit scale of Roblox, from the user's perspective in VR, is defined as follows:

unitScale = HeadScale (in studs) / Feet ^ 2

This means the larger the HeadScale value, the smaller the world will look from the user's perspective when using VR devices.

When not using VR, this property has no effect.

This property should not be confused with Humanoid HeadScale, which is a NumberValue parented to a Humanoid to control its scaling.

See also:

The following are also useful when developing for VR:

MaxAxisFieldOfView

Not Replicated

The MaxAxisFieldOfView property sets how many degrees along the longest viewport axis the camera can view.

When the longest axis is the vertical axis, this property will behave similar to the FieldOfView property. This is generally the case when a device is in a portrait orientation. In a landscape orientation the longest axis will be the horizontal axis. In this case, the property describes the horizontal FOV of the Camera.

See FieldOfView for a more general explanation of FOV.

NearPlaneZ

Read Only
Not Replicated

The NearPlaneZ property describes how far away the Camera's near clipping plane is in studs. The near clipping plane is a geometric plane that sits in-front of the Camera's Camera.CFrame. Anything between this plane and the camera will not render. This creates a cutaway view when viewing objects at very short distances. See the images below for a visual example of this:

A demonstration of how the near clipping plane resides in front of the camera's view A demonstration of how anything falling behind the clipping plane is not rendered

The value of NearPlaneZ varies across different platforms, but is currently always between -0.1 and -0.5.

  • Most windows systems, all Xbox systems and most iOS systems support the more precise value of -0.1
  • Currently Mac and Android systems only support a NearPlaneZ of -0.5, although this may change in the future

ViewportSize

Read Only
Not Replicated

ViewportSize describes the dimensions, in pixels, of the client's viewport.

A visual demonstration of the ViewportSize

  • This property ignores the GUI inset applied by the top bar, meaning the center of the screen can be found at precisely at 50% of the ViewportSize in both directions
  • You can find the position of a Vector3 in the world on the viewport using Camera:WorldToViewportPoint()

Events

FirstPersonTransition

Local User Security

Broken: This event is broken and should not be used.

This event fires when the local user's Camera switches in and out of first person mode.

This event no longer functions and cannot be used by developers due to its security context.

You can instead check the distance between the Camera's Camera.CFrame and Camera.Focus to determine if the local user is in first person mode. For example:


1local camera = workspace.CurrentCamera
2local distance = (camera.CFrame.p - camera.Focus.p).magnitude
3local isFirstPerson = distance <= 0.5
4

Parameters

entering: boolean

Whether the local user's Camera is entering or leaving first person mode.


InterpolationFinished

This event fires when the Camera has finished interpolating using the Camera:Interpolate() function.

This event 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.


Methods

GetPanSpeed

This function is broken and should not be used This function returns the current 'pan' speed of the Camera.

The 'pan' speed of the Camera describes the speed at which the Camera is rotating around its Camera.Focus around the Y axis.

See also:


Returns

The speed at which the Camera is rotating around its Camera.Focus on the Y axis.

GetPartsObscuringTarget

This function returns an array of BaseParts that are obscuring the lines of sight between Camera's Camera.CFrame and the castPoints.

GetPartsObscuringTarget is used by the 'Invisicam' in in the default camera scripts to hide parts between the Camera's Camera.CFrame and Camera.Focus.

Any Instances included in the ignoreList array will, along with their descendants, be ignored.

See below for a visual example of this function. The Camera is represented by the grey camera model and the cast points are represented by the colored dots. The Parts highlighted in red are the ones that would be returned.

A visual demonstration of the function

The castPoints parameter is given as an array of Vector3s, for example:


1local castPoints = {Vector3.new(0, 10, 0), Vector3.new(0, 15, 0)}
2local ignoreList = {}
3workspace.CurrentCamera:GetPartsObscuringTarget(castPoints, ignoreList)
4

The array of BaseParts returned is in an arbitrary order, and no additional raycast data is provided (for example hit position, hit material and surface normal). If this information is required, you should a Workspace raycast function such as Workspace.FindPartOnRayWithIgnoreList.

If Terrain obscures a cast point, BaseParts obscuring the cast point between the obscuring Terrain and the cast point will not be returned.

Note, this function benefits from internal optimisations that make it more performant than casting a ray for each cast point individually.

Parameters

castPoints: Array

An array of Vector3 positions of cast points.

ignoreList: Objects

An array of Instances that, along with their descendants, are to be ignored.


Returns

An array of BaseParts that obscure the lines of sight between the Camera's Camera.CFrame and the castPoints.

Code Samples

X-Ray Function

1local function XRay(castPoints, ignoreList)
2 ignoreList = ignoreList or {}
3 local parts = workspace.CurrentCamera:GetPartsObscuringTarget(castPoints, ignoreList)
4
5 for _, part in pairs(parts) do
6 part.LocalTransparencyModifier = 0.75
7 for _, child in pairs(part:GetChildren()) do
8 if child:IsA("Decal") or child:IsA("Texture") then
9 child.LocalTransparencyModifier = 0.75
10 end
11 end
12 end
13end
14
15XRay({ Vector3.new() })

GetRenderCFrame

This function returns the actual CFrame of the Camera as it is rendered. This includes any roll applied using Camera:SetRoll() and the impact of VR.

VR head transformations, along with roll applied using Camera:SetRoll() is not applied to the Camera.CFrame property. For this reason, it is best practice to use Camera:GetRenderCFrame() to obtain the 'true' CFrame of the Camera.

For example, when using VR the Camera is actually rendered at the following CFrame:


1local UserInputService = game:GetService("UserInputService")
2
3local headCFrame = UserInputService:GetUserCFrame(Enum.UserCFrame.Head)
4renderCFrame = workspace.CurrentCamera.CFrame * headCFrame
5

The Camera's render CFrame will only be changed to account for the head when the Camera.HeadLocked property is true.


Returns

The CFrame the Camera is being rendered at.

GetRoll

This function returns, in radians, the current roll applied to the Camera using Camera:SetRoll(). Roll is defined as rotation around the Camera's Z-axis.

This function only returns roll applied using the Camera:SetRoll() function. Roll manually applied to the Camera's Camera.CFrame is not accounted for. To obtain the actual roll of the Camera, including roll manually applied, you can use the following snippet:


1local function getActualRoll()
2 local camera = workspace.CurrentCamera
3
4 local trueUp = Vector3.new(0, 1, 0)
5 local cameraUp = camera:GetRenderCFrame().upVector
6
7 return math.acos(trueUp:Dot(cameraUp))
8end
9

Returns

The current roll applied by Camera:SetRoll(), in radians.

Code Samples

Camera:GetRoll

1local currentRoll = math.deg(workspace.CurrentCamera:GetRoll()) -- Gets the current roll of the camera in degrees.
2
3if currentRoll ~= 20 then
4 workspace.CurrentCamera:SetRoll(math.rad(20)) -- If the camera isn't at 20 degrees roll, the roll is set to 20 degrees.
5end

GetTiltSpeed

This function is broken and should not be used.

This function returns the current 'tilt' speed of the Camera.

The 'tilt' speed of the Camera describes the speed at which the Camera is rotating around its Camera.Focus around the Camera's X axis.

See also:

Camera:GetPanSpeed() for the speed the Camera is rotating around the Camera.Focus around the Y axis Camera:PanUnits() to 'pan' the camera Camera:TiltUnits() to 'tilt' the camera


Returns

The speed at which the Camera is rotating around its Camera.Focus around the Camera's X axis.

ScreenPointToRay

This function creates a unit Ray from a 2D position on the screen (defined in pixels). This position accounts 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 function accounts for 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 function that does not account for the GUI offset, use Camera: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:


1local camera = workspace.CurrentCamera
2local length = 500
3local unitRay = camera:ScreenPointToRay(100, 100)
4local ray = Ray.new(unitRay.Origin, unitRay.Direction * length)
5

Parameters

The position on the X axis, in pixels, of the screen point at which to originate the Ray. This position accounts for the GUI inset.

The position on the Y axis, in pixels, of the screen point at which to originate the Ray. This position accounts for the GUI inset.

depth: number

The depth from the Camera, in studs, from which to offset the origin of the Ray.

Default Value: "0"

Returns

A unit Ray, originating from the equivalent Vector3 world position of the given screen coordinates at the given depth away from the Camera. This ray is orientated in the direction of the Camera.

Code Samples

Creating a Cube In-game Using the Mouse Position on Screen

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4
5local mouse = player:GetMouse()
6local camera = workspace.CurrentCamera
7
8--This will create a cube facing centered at the origin of the [[Ray]] returned and facing in the same direction. The center of the cube will be one stud in front of the camera.
9mouse.Button1Down:Connect(function()
10 local ray = camera:ScreenPointToRay(mouse.X, mouse.Y, 1)
11 local cube = Instance.new("Part")
12 cube.Size = Vector3.new(1, 1, 1)
13 cube.CFrame = CFrame.new(ray.Origin, ray.Origin + ray.Direction)
14 cube.Anchored = true
15 cube.Parent = workspace
16end)

SetCameraPanMode

void

This function sets the CameraPanMode to be used by the Camera on mobile devices.

When the *'EdgeBump' CameraPanMode is used, swipe to pan is disabled and the edge bump camera controls are enabled.

SetCameraPan mode has no effect on PC / Mac users.

Parameters

The CameraPanMode to set the Camera to.

Default Value: "Classic"

Returns

void

No return.

SetImageServerView

void
Roblox Script Security

Parameters

modelCoord: CFrame

Returns

void

SetRoll

void

This function is outdated and no longer considered best practice.

This function sets the current roll, in radians, of the Camera. The roll is applied after the Camera.CFrame and represents the rotation around the Camera's Z-axis.

For example, the following would invert the Camera:


1workspace.CurrentCamera:SetRoll(math.pi) -- math.pi radians = 180 degrees
2

SetRoll has no effect on any roll applied using the Camera.CFrame property. Roll applied using SetRoll is not reflected in the Camera.CFrame property but is reflected in in the CFrame returned byCamera:GetRenderCFrame().

This function can only be used when the Camera.CameraType is set to 'Scriptable', regardless of whether the default camera scripts are being used. If it is used with any other Camera.CameraType a warning is given in the output.

Any roll applied using this function will be lost when the Camera.CameraType is changed from 'Scriptable'.

To obtain the roll set using this function use Camera:GetRoll().

As this function is outdated, you are advised to instead apply roll to the Camera using the Camera.CFrame property. For example:


1local currentCFrame = workspace.CurrentCamera.CFrame
2local rollCFrame = CFrame.Angles(0, 0, roll)
3workspace.CurrentCamera.CFrame = currentCFrame * rollCFrame
4

Parameters

rollAngle: number

The roll angle, in radians, to be applied to the Camera.


Returns

void

No return.

ViewportPointToRay

This function creates a unit Ray from a 2D position on the viewport (defined in pixels). This position does not account 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 function does not account for the GUI inset, the viewport position given is not equivalent to the screen position used by GUI elements. If you are not using ScreenGui.IgnoreGuiInset and need an otherwise identical function that accounts for the GUI offset, use Camera:ScreenPointToRay().

This function can be used in conjunction with the Camera.ViewportSize property to create a ray from the centre of the screen, for example:


1local camera = workspace.CurrentCamera
2local viewportPoint = camera.ViewportSize / 2
3local unitRay = camera:ViewportPointToRay(viewportPoint.X, viewportPoint.Y, 0)
4

As the Ray created is a unit ray it is only one stud long. To create a longer ray, you can do the following:


1local camera = workspace.CurrentCamera
2local length = 500
3local unitRay = camera:ScreenPointToRay(100, 100)
4local ray = Ray.new(unitRay.Origin, unitRay.Direction * length)
5

Parameters

The position on the X axis, in pixels, of the viewport point at which to originate the Ray. This position does not account for the GUI inset.

The position on the Y axis, in pixels, of the viewport point at which to originate the Ray. This position does not account for the GUI inset.

depth: number

The depth from the Camera, in studs, from which to offset the origin of the Ray.

Default Value: "0"

Returns

A unit Ray, originating from the equivalent Vector3 world position of the given viewport coordinates at the given depth away from the Camera. This ray is orientated in the direction of the Camera.

WorldToScreenPoint

This function returns the screen location and depth of a Vector3 worldPoint and whether this point is visible on the screen or not.

In-game example

This function takes in account the current GUI inset (such as the space occupied by the top bar). This means the 2D position returned is in the same term as GUI positions and can be used to place GUI elements. For an otherwise identical function that ignores the GUI inset, see Camera:WorldToViewportPoint().

For example:


1local camera = workspace.CurrentCamera
2local worldPoint = Vector3.new(0, 10, 0)
3local vector, onScreen = camera:WorldToScreenPoint(worldPoint)
4
5local screenPoint = Vector2.new(vector.X, vector.Y)
6local depth = vector.Z
7

Note this function does not perform any raycasting, meaning the visible bool will be true regardless if the worldPoint is obscured by BaseParts or Terrain.

Parameters

worldPoint: Vector3

The Vector3 world position.


Returns

A tuple containing, in order:

A Vector3 whose X and Y components represent the offset of the worldPoint from the top left corner of the screen, in pixels. The Vector3's Z component represents the depth of the worldPoint from the screen (in studs).

A bool indicating if the worldPoint is within the bounds of the screen

WorldToViewportPoint

This function returns the screen location and depth of a Vector3 worldPoint and whether this point is visible on the screen or not.

In-game example

This function does not take in account the current GUI inset (such as the space occupied by the top bar). This means the 2D position returned is taken from the top left corner of the viewport. This means, unless you are using ScreenGui.IgnoreGuiInset this position is not appropriate for placing GUI elements.

For an otherwise identical function that accounts for the GUI inset, see Camera:WorldToScreenPoint().

For example:


1local camera = workspace.CurrentCamera
2local worldPoint = Vector3.new(0, 10, 0)
3local vector, inViewport = camera:WorldToViewportPoint(worldPoint)
4
5local viewportPoint = Vector2.new(vector.X, vector.Y)
6local depth = vector.Z
7

Note this function does not perform any raycasting, meaning the visible bool will be true regardless if the worldPoint is obscured by BaseParts or Terrain.

Parameters

worldPoint: Vector3

The Vector3 world position.


Returns

A tuple containing, in order:

A Vector3 whose X and Y components represent the offset of the worldPoint from the top left corner of the viewport, in pixels. The Vector3's Z component represents the depth of the worldPoint from the screen (in studs).

A bool indicating if the worldPoint is within the bounds of the viewport.

Code Samples

Check if a point is visible

1local function isPointVisible(worldPoint)
2 local camera = workspace.CurrentCamera
3 local _, onScreen = camera:WorldToViewportPoint(worldPoint)
4
5 if onScreen then
6 local origin = camera.CFrame.p
7 local ray = Ray.new(origin, worldPoint - origin)
8 local hit = workspace:FindPartOnRay(ray)
9 if hit then
10 return false
11 end
12 else
13 return false
14 end
15 return true
16end
17
18print(isPointVisible(Vector3.new(20, 0, 0)))
Roblox Script Security

Parameters

distance: number

Returns