Skip to Content
Kinemium

ViewportFrame

Render a 3D scene inside a GUI element.

ViewportFrame draws a small 3D world into a GUI rectangle. It has its own camera, lighting, and image tint, so it's the usual choice for character previews and item viewers.

Getting started

local viewport = Instance.new("ViewportFrame")
viewport.Size = UDim2.fromOffset(320, 320)
viewport.BackgroundColor3 = Color3.fromRGB(20, 20, 24)
viewport.Parent = screenGui

local model = character:Clone()
model.Parent = viewport

local camera = Instance.new("Camera")
camera.CFrame = CFrame.new(0, 2, -8)
viewport.CurrentCamera = camera
camera.Parent = viewport

Properties

PropertyTypeAccessDefaultDescription
CurrentCameraCamera?Read/writenilCamera used to render the scene.
AmbientColor3Read/write(0.5, 0.5, 0.5)Ambient light color.
LightColorColor3Read/writeWhiteDirectional light color.
LightDirectionVector3Read/write(-1, -1, -1)Direction of the light.
ImageColor3Color3Read/writeWhiteTint applied to the rendered image.
ImageTransparencynumberRead/write0Transparency, clamped to 0 through 1.
ResolutionScalenumberRead/write1Render scale, clamped to 0.25 through 2.
UpdateRatenumberRead/write60Target updates per second, clamped to 0 through 240.
AdaptiveQualitybooleanRead/writetrueLower quality automatically when idle.
ContinuousUpdatebooleanRead/writefalseRender every frame instead of on change.
ShadowsbooleanRead/writetrueRender shadows.
PostProcessingbooleanRead/writetrueApply post-processing effects.

Camera handling

CurrentCamera must be a Camera or nil; assigning another instance type raises an error. The camera doesn't need to be parented inside the frame, but keeping it there makes the setup easy to clone.

The camera's FieldOfView, CFrame, and projection settings apply exactly as they do in the main view.

Notes

  • ImageColor3 and ImageTransparency tint the final image without re-rendering the 3D scene.
  • ResolutionScale below 1 renders fewer pixels and can improve performance.
  • AdaptiveQuality reduces work when the frame hasn't changed.
  • Children render in the frame's own world, not the workspace.
  • Inherits all GuiObject members.

See also

  • Camera for the view settings.
  • ScreenGui for the containing UI.
  • SurfaceGui for 3D surfaces instead of a GUI rectangle.

On this page