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
LocalScript
into the new screen GUI object.

- Inside the script, paste the following code:
- 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 thearticles/Intro to GUIs|Intro to GUIs
guide.
- In the next block, a basic
Part
is created. Most importantly, the part is parented to the viewport frame on line 14:
- On lines 16-18, a new
Camera
is created, then it is assigned to theViewportFrame/CurrentCamera|CurrentCamera
property 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.
- On the final line, the new camera is positioned relative to the part by resetting its
datatype/CFrame|CFrame
.
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.
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.