GSmGpE6CwX2y9JjB25B8
We use cookies on this site to enhance your user experience

ViewportFrame GUI

ViewportFrame GUI

Aug 29 2019, 9:18 AM PST 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.

Creating a ViewportFrame

A new ViewportFrame can be created as follows:

  1. Create a new ScreenGui inside the StarterGui folder.
  1. Insert a LocalScript into the new screen GUI object.
  1. Inside the script, paste the following code:
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)
  1. 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.
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
  • In the next block, a basic Part is created. Most importantly, the part is parented to the viewport frame on line 14:
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
  • 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.
local viewportCamera = Instance.new("Camera")
viewportFrame.CurrentCamera = viewportCamera
viewportCamera.Parent = viewportFrame
  • On the final line, the new camera is positioned relative to the part by resetting its datatype/CFrame|CFrame.
viewportCamera.CFrame = CFrame.new(Vector3.new(0, 2, 12), part.Position)

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.

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()

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