ViewportFrame GUI
ViewportFrame GUI
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.
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
LocalScriptinto the new screen GUI object.
- 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)
- Playtest the game and you should see a new viewport frame containing the
partobject.
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 thearticles/Intro to GUIs|Intro to GUIsguide.
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
Partis 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
Camerais created, then it is assigned to theViewportFrame/CurrentCamera|CurrentCameraproperty and parented toviewportFrame. 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)
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.
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.