Frames are GuiObjects that act as containers for other GuiObjects. You can use them for UI that either displays on a user's screen or on a surface within the experience.
When you manipulate frames, you also manipulate the GuiObjects they contain. For example, if you change the position of a Frame object with a child TextLabel, you also change the position of that label. In addition, all frames are also GuiObjects, so you can customize their properties, such as BackgroundColor3, BorderMode, Transparency, and Rotation, to fit the aesthetics of your experience.
Frame Types
There are three primary frame types, each serving a specific purpose in UI design.
Frame
A Frame is a plain, empty rectangle. If you parent GuiObjects to the Frame, they display within the rectangle. Aside from its common use as a container, you can also use a Frame for background design on a screen. For example, to visually separate other UI elements, you can scale a Frame to be thin and long until it becomes a line, or create multiple Frames with different BackgroundColor3 properties.
ScrollingFrame
A ScrollingFrame is a frame made up of two elements: a customizable canvas and scroll bar. This type of frame lets you display a lot of information in a confined space, and it's useful for menus and lists.
You can set the position and size of a ScrollingFrame through its respective Position and Size properties. Note that the scrollbar takes up a portion of the ScrollingFrame size.
Canvas
The canvas is the area inside of a ScrollingFrame that is able to contain other GuiObjects. If one of the dimensions of the canvas is wider than the overall size of the ScrollingFrame, the scroll bar is visible, otherwise it is hidden.
The CanvasSize property determines how large of area you can scroll through, not the size of the ScrollingFrame itself. If you need to know how big the actual viewing area is in a ScrollingFrame, you can access it using the read-only property ScrollingFrame.AbsoluteWindowSize.
The CanvasPosition property determines your default position within the canvas in pixels, and it sets the scroll bar position accordingly. Note that this property doesn't do anything when the scroll bar isn't visible.
Scroll Bar
The scroll bar displays your position within the content of the ScrollingFrame that isn't visible. There are two types of scroll bars: a vertical scroll bar and a horizontal scroll bar. A vertical scroll bar allows you to scroll up and down, while a horizontal scroll bar allows you to scroll left and right.
Using the VerticalScrollBarPosition property, you can switch a vertical scroll bar's position either to the left or right of the canvas.
Scroll bars are made up of three images:
- Top — An image that displays on top of the scroll bar's thumb.
- Middle — An image that displays as the thumb of the scroll bar.
- Bottom — An image that displays on the bottom of the scroll bar's thumb.
You can customize these images through a scroll bar's respective TopImage, MidImage, and BottomImage properties. Note that a vertical and a horizontal scroll bar use the same images, but the horizontal scroll bar rotates the images from the vertical scroll bar by 90 degrees counterclockwise.
Each image scales based on the ScrollBarThickness property, which changes the width of a vertical scroll bar or the height of a horizontal scroll bar. This property also determines the width and height of the top and bottom scroll bar images, as well as the thickness of the middle image. However, a middle image's length scales based on both the size of the ScrollingFrame and the canvas.
ViewportFrame
A ViewportFrame is a frame that uses a camera to render 3D objects. This type of frame is a great way to display 3D objects and models in a 2D space, such as:
- A minimap of your experience directly in the corner of a user's screen.
- 3D models of items in an inventory menu.
- Rotating objects that a character has equipped.
3D objects that users view through a ViewportFrame can either move with their camera, remain static, or rotate within the ViewportFrame. This object can also include a Sky child as a cubemap for reflections.
If you want the 3D object to move with the camera:
Position your camera view within the experience so that the object you want to see within the frame is visible.
In the Properties window, assign the CurrentCamera property to the camera:
- Select the CurrentCamera property. Your cursor changes.
- In the Explorer window, click on the top-level Camera object.
Parent the desired 3D object to the new ViewportFrame. Note that if you still want to see the object within your experience, you must duplicate it in the Workspace and then parent the duplicate object to the ViewportFrame.
When you move your camera, the object will also move within the ViewportFrame.
When you want to update the view of your ViewportFrame, be sure to update the camera, not the objects within the view.