ViewportFrame GUI

5 min

A ViewportFrame is a type of GuiObject that can render 3D objects inside its bounds. This is a great way to display 3D objects/models in a 2D GUI space like a ScreenGui.

If you haven't read the articles/Intro to GUIs|Intro to GUIs guide, please do so before continuing with this tutorial.

Creating a ViewportFrame

A new ViewportFrame can be created as follows:

Create a new ScreenGui inside the StarterGui folder.

Insert a LocalScript into the new screen GUI object.

Inside the script, paste the following code:

			
				Expected Output
			
				Expand
				
			local viewportFrame = Instance.new("ViewportFrame")
viewportFrame.Size = UDim2.new(0.3, 0, 0.4, 0)
viewportFrame.Position = UDim2.new(0, 15, 0, 15)
viewportFrame.BackgroundColor3 = Color3.new(0, 0, 0)
viewportFrame.BorderColor3 = Color3.new(0.6, 0.5, 0.4)
viewportFrame.BorderSizePixel = 2
viewportFrame.BackgroundTransparency = 0.25
viewportFrame.Parent = script.Parent

local part = Instance.new("Part")
part.Material = Enum.Material.Concrete
part.Color = Color3.new(0.25, 0.75, 1)
part.Position = Vector3.new(0, 0, 0)
part.Parent = viewportFrame

local viewportCamera = Instance.new("Camera")
viewportFrame.CurrentCamera = viewportCamera
viewportCamera.Parent = viewportFrame

viewportCamera.CFrame = CFrame.new(Vector3.new(0, 2, 12), part.Position)
		
				Copy Code
			
				Light Theme

Playtest the game and you should see a new viewport frame containing the part object.

Key Points

Let’s inspect the main factors within the script for creating a viewport frame:

Lines 1-8 set up the basic viewport frame and parent it to the ScreenGui. Many of the properties are similar to those illustrated in the articles/Intro to GUIs|Intro to GUIs guide.

			
				Expected Output
			
				Expand
				
			local viewportFrame = Instance.new("ViewportFrame")
viewportFrame.Size = UDim2.new(0.3, 0, 0.4, 0)
viewportFrame.Position = UDim2.new(0, 15, 0, 15)
viewportFrame.BackgroundColor3 = Color3.new(0, 0, 0)
viewportFrame.BorderColor3 = Color3.new(0.6, 0.5, 0.4)
viewportFrame.BorderSizePixel = 2
viewportFrame.BackgroundTransparency = 0.25
viewportFrame.Parent = script.Parent
		
				Copy Code
			
				Light Theme

In the next block, a basic Part is created. Most importantly, the part is parented to the viewport frame on line 14:

			
				Expected Output
			
				Expand
				
			local part = Instance.new("Part")
part.Material = Enum.Material.Concrete
part.Color = Color3.new(0.25, 0.75, 1)
part.Position = Vector3.new(0, 0, 0)
part.Parent = viewportFrame
		
				Copy Code
			
				Light Theme

On lines 16-18, a new Camera is created, then it is assigned to the ViewportFrame/CurrentCamera|CurrentCamera property and parented to viewportFrame. This is a critical aspect since viewports do not use the default world camera, but rather their own camera for rendering the “view” that players see.

			
				Expected Output
			
				Expand
				
			local viewportCamera = Instance.new("Camera")
viewportFrame.CurrentCamera = viewportCamera
viewportCamera.Parent = viewportFrame
		
				Copy Code
			
				Light Theme

On the final line, the new camera is positioned relative to the part by resetting its datatype/CFrame|CFrame.

			
				Expected Output
			
				Expand
				
			viewportCamera.CFrame = CFrame.new(Vector3.new(0, 2, 12), part.Position)
		
				Copy Code
			
				Light Theme

If you're not familiar with CFrames, please review the articles/Understanding CFrame|Understanding CFrames article.

Controlling the Camera

As shown above, the viewport’s camera can be moved by resetting its datatype/CFrame|CFrame. This means that the frame’s in-game view can be dynamically changed by manipulating the camera’s orientation.

Consider the following addition to the script. On the first line, we get the TweenService service for gradually moving the camera. Then, after 2 seconds, we configure and play a new Tween which moves the camera closer to the part.

			
				Expected Output
			
				Expand
				
			local TweenService = game:GetService("TweenService")

local viewportFrame = Instance.new("ViewportFrame")
viewportFrame.Size = UDim2.new(0.3, 0, 0.4, 0)
viewportFrame.Position = UDim2.new(0, 15, 0, 15)
viewportFrame.BackgroundColor3 = Color3.new(0, 0, 0)
viewportFrame.BorderColor3 = Color3.new(0.6, 0.5, 0.4)
viewportFrame.BorderSizePixel = 2
viewportFrame.BackgroundTransparency = 0.25
viewportFrame.Parent = script.Parent

local part = Instance.new("Part")
part.Material = Enum.Material.Concrete
part.Color = Color3.new(0.25, 0.75, 1)
part.Position = Vector3.new(0, 0, 0)
part.Parent = viewportFrame

local viewportCamera = Instance.new("Camera")
viewportFrame.CurrentCamera = viewportCamera
viewportCamera.Parent = viewportFrame

viewportCamera.CFrame = CFrame.new(Vector3.new(0, 2, 12), part.Position)

wait(2)

local cameraGoal = {
	CFrame = CFrame.new(Vector3.new(0, 6, 4), part.Position)
}

local tweenInfo = TweenInfo.new(2, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)

local tween = TweenService:Create(viewportCamera, tweenInfo, cameraGoal)

tween:Play()
		
				Copy Code
			
				Light Theme

Notes / Performance

Here are some important considerations for creating viewport frames:

Each viewport frame will create a texture for rendering. The texture has a max size limit, so if the frame is too big, the contents may look blurry.
The viewport will only update when its children (camera or objects within) are changed.
Moving a viewport’s physical children is less performant than keeping them static. If you need to update the view, it’s better to move the camera than move the parts/models.
A viewport frame is not designed for rendering a large number of complex objects — it may be slow if you put too many objects inside.
Objects inside viewports will be rendered using a fixed lighting setting, although more options may become available in the future. No shadows or post effects are currently available.

Tags:

viewport
gui
ui

ViewportFrame GUI

ViewportFrame GUI

Creating a ViewportFrame

Key Points

Controlling the Camera

Notes / Performance

Related Articles

Intro to GUIs