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
articles/Intro to GUIs|Intro to GUIsguide, please do so before continuing with this tutorial.
Creating a ViewportFrame
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:
- Playtest the game and you should see a new viewport frame containing the
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 GUIsguide.
- In the next block, a basic
Partis created. Most importantly, the part is parented to the viewport frame on line 14:
- On lines 16-18, a new
Camerais created, then it is assigned to the
ViewportFrame/CurrentCamera|CurrentCameraproperty 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.
- On the final line, the new camera is positioned relative to the part by resetting its
articles/Understanding CFrame|Understanding CFramesarticle.
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.