5 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Viewport frames

A ViewportFrame uses a camera to render 3D objects into a 2D viewport. Ideal use cases include:

• A minimap of your game directly in the corner of a user's screen.
• 3D models of items in an inventory menu.
• Rotating objects that a character has equipped.

Viewport configurations

3D objects that users view through a ViewportFrame can either move with their camera, remain static, or rotate within the ViewportFrame. This object can also include a Sky child as a cubemap for reflections.

With Camera

If you want a 3D object to move with the camera:

1. Position your camera view within the game so that the object you want to see within the frame is visible.

2. Add a new ViewportFrame to the screen and then make sure it's selected in the Explorer.

3. In the Properties window, assign the CurrentCamera property to the camera:

   1. Select the CurrentCamera property. Your cursor changes.
   2. In the Explorer window, click on the top-level Camera object.

4. Parent the desired 3D object to the new ViewportFrame. Note that if you still want to see the object within your game, you must duplicate it in the Workspace and then parent the duplicate object to the ViewportFrame.

When you move your camera, the object will also move within the ViewportFrame.

Note

When you want to update the view of your ViewportFrame, be sure to update the camera, not the objects within the view.

Static

If you want the 3D object to remain static:

1. Position your camera view within the game so that the object you want to see is in the exact position you want to see it within the frame.

2. In the Explorer window, duplicate the top-level Camera object, then rename it to an identifiable name like ViewportCam.

3. Add a new ViewportFrame to the screen and then make sure it's selected in the Explorer.

4. In the Properties window, assign the frame's CurrentCamera property to the duplicated camera:

   1. Select the CurrentCamera property. Your cursor changes.
   2. In the Explorer window, click on the duplicated camera object.

5. Parent the desired 3D object to the new ViewportFrame. Note that if you still want to see the object within your game, you must duplicate it in the Workspace and then parent the duplicate object to the ViewportFrame.

Rotation

If you want a 3D object such as a BasePart to rotate on its own within the frame:

1. Add a new ViewportFrame to the screen.

2. In the Explorer window, drag the desired BasePart into the new ViewportFrame.

3. Insert a new LocalScript into the ViewportFrame and paste in the following code.

   local RunService = game:GetService("RunService")
   
   local viewportFrame = script.Parent
   
   -- Parameters to experiment with
   local cameraDistance = 10
   local cameraFieldOfView = 50
   local objectPitchAngle = 40
   local objectRotationSpeed = 50
   
   -- Viewport camera initialization
   local viewportCamera = Instance.new("Camera")
   viewportCamera.FieldOfView = cameraFieldOfView
   viewportFrame.CurrentCamera = viewportCamera
   viewportCamera.Parent = viewportFrame
   
   -- Viewport object initialization
   local object = viewportFrame:FindFirstChildWhichIsA("BasePart")
   if object then
       object.CFrame = CFrame.new(0, 0, 0) * CFrame.Angles(math.rad(objectPitchAngle), 0, 0)
   
       -- Update loop
       local t = 0
       RunService.PostSimulation:Connect(function(delta)
           t += delta
           viewportCamera.CFrame = CFrame.Angles(0, math.rad(t * objectRotationSpeed), 0) * CFrame.new(0, 0, cameraDistance)
       end)
   else
       warn("3D object not found as child of viewport frame")
   end

Skybox Reflections

ViewportFrames can use a Sky child as a cubemap for reflections, in which case only the Sky object's six Skybox[…] properties are used. Assuming these properties are valid, lighting inside the ViewportFrame acts similarly to when Lighting.EnvironmentSpecularScale and Lighting.EnvironmentDiffuseScale are both set to 1.

To implement skybox cubemap reflections:

1. Insert a Sky object as a direct child of the ViewportFrame.
2. Set the Sky object's six texture properties (SkyboxBk, SkyboxDn, SkyboxFt, SkyboxLf, SkyboxRt, SkyboxUp).
3. For Parts that should appear within the frame, set their Reflectance property greater than 0, or use a reflectant material like Glass or Foil. For MeshParts that should appear within the frame, apply a SurfaceAppearance with a properly-configured MetalnessMap.

Lighting and appearance

Lighting within a ViewportFrame is controlled through three properties:

Additionally, you can adjust the overall rendered appearance of the viewport throuugh the following properties: