Render a real 3D Roblox model inside a GUI element with ViewportFrame and a Camera, so UI can show a live preview of a vehicle, item, or character.
You know how a shop shows a spinning 3D preview of the car you're about to buy? That isn't a picture — it's a real Roblox model rendered live into a GUI rectangle called a ViewportFrame. It lets you show genuine 3D objects inside your interface instead of a flat image. This lesson gives your UI a window into the 3D world.
A ViewportFrame is a GUI element (a GuiObject, just like a Frame) that renders a separate, miniature 3D scene inside a rectangle on screen. Whatever models you put inside it get drawn as if a second camera were watching them — completely independent of the main game camera.
ScreenGui
└── ViewportFrame ← the rectangle (size + position, like any GUI)
└── Model ← a clone of the thing to preview
└── Camera ← the miniature camera that sees it
It's the difference between a shop that shows a photo of an item and a shop that shows the item itself — rotating, lit, and real.
What does a ViewportFrame draw inside a GUI rectangle?
Use a ViewportFrame anywhere a UI needs a real 3D preview:
Reach for it when a static icon loses information (angle, shape, color) and a full 3D scene would be too heavy. It's GUI-sized 3D — lightweight enough to run inline in menus.
ViewportFrames are lightweight, but every one renders an extra scene. For a long inventory list, prefer icons or only render the frames currently visible — not dozens at once.
First, lay down the rectangle (like any GUI element — see the GUIs lesson):
local screenGui = Instance.new("ScreenGui")
screenGui.Parent = player.PlayerGui
local viewport = Instance.new("ViewportFrame")
viewport.Size = UDim2.new(0, 200, 0, 150)
viewport.Position = UDim2.new(0.5, 0, 0.4, 0)
viewport.AnchorPoint = Vector2.new(0.5, 0.5)
viewport.BackgroundColor3 = Color3.fromRGB(40, 40, 48)
viewport.Parent = screenGui
Now the second piece: a Camera. A Camera is what "sees" inside the frame. Create one, parent it to the ViewportFrame, and give it a field of view (in degrees):
local camera = Instance.new("Camera")
camera.Parent = viewport
camera.FieldOfView = 50
A ViewportFrame renders its scene through a object parented inside it.
A ViewportFrame doesn't share your — it's a separate scene. So you don't use the real model; you clone it and parent the clone inside the frame:
local garage = workspace.Garage
local car = garage:FindFirstChild("SportsCar") -- the model to preview
local preview = car:Clone()
preview.Parent = viewport
Cloning keeps the real car untouched — the isn't driving the preview, they're looking at a copy. If the model has internal references, sometimes you need the clone's ImmediateParent set too; the simplest path is cloning straight into the frame as shown.
The model you clone must live in a place your can see ( or ReplicatedStorage). A ViewportFrame is a client-side GUI, so this preview code belongs in a LocalScript.
Your game has a 'Potion' model in ReplicatedStorage. Write the two lines that copy it into the viewport frame.
local ReplicatedStorage = game:GetService("ReplicatedStorage")\n-- copy the potion model into the viewportCloning the model isn't enough — the camera needs to actually see it. Set the camera to the frame's camera, place it a little off to the side, and aim its focus at the model's center:
viewport.CurrentCamera = camera
camera.CFrame = CFrame.lookAt(Vector3.new(3, 1.5, 4), Vector3.new(0, 0, 0))
viewport.CurrentCamera = camera — tells the frame which camera to render through.CFrame.lookAt(eye, target) — positions the camera at eye and points it at target. Here it backs the camera off to the side and looks at the origin, where the cloned model sits.If the model isn't centered at the origin, aim at its actual center instead:
local center = preview:GetBoundingBox().Position
camera.CFrame = CFrame.lookAt(center + Vector3.new(3, 1.5, 4), center)
GetBoundingBox() returns a box that encloses the whole model, so center is always its true middle — no more guessing.
What does viewport.CurrentCamera = camera actually do?
A static preview is okay; a rotating one sells it. Rotate just the model (not the camera) each frame so it spins in place:
local heart = workspace.Chest:FindFirstChild("HeartGem")
local preview = heart:Clone()
preview.Parent = viewport
game:GetService("RunService").Heartbeat:Connect(function(deltaTime)
preview:SetPrimaryPartCFrame(preview:GetPivot() * CFrame.Angles(0, deltaTime, 0))
end)
SetPrimaryPartCFrame positions the model's primary — rotating it by the small per-frame deltaTime angle gives a smooth, constant spin no matter the frame rate. Rotating the model (not the camera) keeps the and framing consistent.
GetPivot() returns the model's current position and rotation; multiplying by CFrame.Angles(0, deltaTime, 0) adds a tiny yaw each frame. Swap the middle value for a different rotation axis, or remove this entirely for a static preview.
Each frame, spin a preview model around the vertical axis by deltaTime. Write the SetPrimaryPartCFrame line.
game:GetService("RunService").Heartbeat:Connect(function(deltaTime)\n -- rotate the preview around Y by deltaTime\nend)Tie it together — a shop card that shows a live, rotating preview of the selected vehicle:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local screenGui = Instance.new("ScreenGui")
screenGui.Parent = player.PlayerGui
local viewport = Instance.new("ViewportFrame")
viewport.Size = UDim2.new(0, 240, 0, 160)
viewport.Position = UDim2.new(0.5, 0, 0.35, 0)
viewport.AnchorPoint = Vector2.new(0.5, 0.5)
viewport.BackgroundColor3 = Color3.fromRGB(24, 26, 32)
viewport.Parent = screenGui
local camera = Instance.new("Camera")
camera.Parent = viewport
camera.FieldOfView = 50
viewport.CurrentCamera = camera
local preview = ReplicatedStorage.Shop.SportsCar:Clone()
preview.Parent = viewport
local center = preview:GetBoundingBox().Position
camera.CFrame = CFrame.lookAt(center + Vector3.new(3, 1.5, 4), center)
game:GetService("RunService").Heartbeat:Connect(function(dt)
preview:SetPrimaryPartCFrame(preview:GetPivot() * CFrame.Angles(0, dt, 0))
end)
From frame → camera → clone → focus → spin, this is the whole ViewportFrame recipe in one place.
Add a "Buy" button under the viewport. When clicked, have it hide the preview and show a confirmation label — the classic shop flow wrapped around your new 3D window.
CurrentCamera. A frame is blank until you assign a Camera with viewport.CurrentCamera = camera.GetBoundingBox().Position so you always aim at the model's true center.player.PlayerGui.Next: turning repetitive Studio tasks into one-button tools with plugins.