---
read_when: "Choose screen or world-space containers and configure layout behavior"
last_reviewed: 2026-06-17
---

# GUI containers (ScreenGui, CanvasGroup, SurfaceGui, BillboardGui, ScrollingFrame, ViewportFrame)

Full details from the Roblox docs for [on-screen containers](https://create.roblox.com/docs/en-us/ui/on-screen-containers) and [in-experience containers](https://create.roblox.com/docs/en-us/ui/in-experience-containers).

## ScreenGui (2D overlay on the player's screen)

- Must ultimately live under a Player's PlayerGui to be visible to that player (cloned from StarterGui on spawn, or created at runtime on the client).
- .Enabled is the simplest visibility toggle (contents do not process input or render when false).
- Multiple ScreenGuis are layered by .DisplayOrder (higher numbers render on top).
- .ScreenInsets controls safe area:
  - CoreUISafeInsets (default): avoids Roblox top bar + device cutouts/notches. Recommended for interactive UI.
  - DeviceSafeInsets: avoids only device hardware (camera notch etc.), allows overlap with top bar.
  - TopbarSafeInsets: positions between top bar and right edge of device safe area; auto-flexes horizontally.
  - None: full screen, can be completely obscured by notches or top bar. Only for non-interactive background art.
- .ResetOnSpawn: true by default. False only works reliably when the ScreenGui is a *direct* child of StarterGui (not inside a Folder or other container).
- .ZIndexBehavior: `Global` (default, ZIndex is compared across the whole ScreenGui) vs `Sibling` (ZIndex only compared among siblings with the same parent). Use `Sibling` when you want nested containers to manage their own layering independently; use `Global` for a flat HUD where absolute ZIndex values matter.
- All logic that manipulates ScreenGui contents at runtime belongs on the client (LocalScript or required client module).

**Access pattern (LocalScript):**
```lua
local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local hud = playerGui:WaitForChild("MainHUD")
local shop = playerGui:WaitForChild("ShopMenu")
```

## CanvasGroup (group transparency, color, and clipping)

- A container that renders its descendants into a shared texture, then applies `GroupTransparency` and `GroupColor3` to the whole group.
- The only built-in way to get **rounded clipping**: set `UICorner` on a CanvasGroup and child content that overflows the corners will be clipped. Regular Frames do not clip descendants with rounded corners.
- Because it allocates a render target, CanvasGroup has a real texture/memory cost proportional to its on-screen size. It is cheaper than many individual moving particles, but not free; avoid large CanvasGroups on low-end devices or stacking many of them.

## SurfaceGui (projected onto a part face in the 3D world)

- Can be parented directly to a BasePart (respects .Face = Front/Back/Left/Right/Top/Bottom).
- Alternative (more flexible for runtime): place in StarterGui, set .Adornee to any BasePart and .Face.
- The "canvas" fills the chosen face. Child GuiObjects are positioned/sized with the usual UDim2 rules relative to the canvas size (PixelsPerStud and CanvasSize control density).
- .AlwaysOnTop: renders above 3D geometry regardless of occlusion.
- .Brightness (0-1000): scales emitted light when **LightInfluence is 0**. Has no effect when `LightInfluence` is `1`.
- .LightInfluence (0-1): how much world lighting affects the UI appearance.
- .MaxDistance: culling distance (0 = infinite).
- .ZOffset: sort order when multiple SurfaceGuis share the same face (does not physically lift the UI off the surface).
- **Critical input rule:** Buttons and other interactive elements only receive player input if the SurfaceGui (or an ancestor) is ultimately under that player's PlayerGui. The target part must also have CanQuery = true.

Use for in-world computers, vehicle HUDs, keypads, interactive signs, etc.

## BillboardGui (always faces the camera, floats in 3D space)

- Similar lighting/occlusion/MaxDistance properties to SurfaceGui.
- Sizing is in *studs*: the scale components of .Size define the world-space dimensions (e.g. UDim2.fromScale(6, 4) is a 6-stud wide by 4-stud tall billboard whose on-screen size shrinks/grows with camera distance).
- .StudsOffset: offset in studs **relative to the camera orientation**; use `.StudsOffsetWorldSpace` for an offset along world X/Y/Z axes.
- **Input rule:** Interactive children only receive input if `BillboardGui.Active = true` **and** the child button's `Active = true`, in addition to the PlayerGui ancestry rule.
- Excellent for nameplates above heads, floating damage numbers, health bars, quest markers, contextual icons.
- Same PlayerGui ancestry rule as SurfaceGui for interactive children.

**Text scaling tip:** When using TextLabel inside a scale-sized BillboardGui, enable TextScaled so the text remains legible at varying distances. Pair it with a `UITextSizeConstraint` (MaxTextSize / MinTextSize) to prevent unreadably huge or tiny text.

## ScrollingFrame (scrollable content region)

- Set `AutomaticCanvasSize` to `X`, `Y`, or `XY` to auto-resize the canvas based on child `AbsoluteContentSize` (especially useful with UIListLayout). The child layout's `FillDirection` should match the scrolling axis.
- **Gotcha:** `AutomaticCanvasSize` can conflict with children sized via scale or with `UIScale`. If the canvas grows indefinitely or scrollbars flicker, switch the scrolling content to offset/AutomaticSize or set an explicit `CanvasSize` while driving it from the layout's `AbsoluteContentSize` manually.
- Use `ScrollingDirection`, `ScrollBarThickness`, `ScrollBarImageColor3`, `ScrollBarImageTransparency`, and `VerticalScrollBarPosition` to match your design.
- `CanvasPosition` can be tweened for smooth scrolling.

## ViewportFrame (2D rectangle that renders a 3D world)

- Lives inside any Gui container (usually ScreenGui or a Frame inside one).
- Has its own `.CurrentCamera` (required for rendering). Parent models, parts, meshes, cameras, and rigs directly to the ViewportFrame. There is no separate `.World` property.
- You can play AnimationTracks on rigs inside the viewport and run IKControl. Real `ParticleEmitter`, `Beam`, `Trail`, and `Light` objects do **not** render inside `ViewportFrame`; use the built-in `Ambient`, `LightColor`, and `LightDirection` properties for lighting.
- Common for 3D item/character previews in shops or inventories, ability visualizers, "portal" effects, or embedding world particles as "UI particles".
- Performance cost is real: treat active ViewportFrames like expensive transparent elements. Limit concurrent visible ones and lower internal complexity on low-end devices.

## Common patterns and gotchas

- **Scale vs Offset:** Prefer scale for almost everything responsive. Offset is still the right tool for thin 1px separators/hairlines, crisp borders that must stay 1 pixel wide, fixed-size hit targets (e.g. 44×44 pt minimums), and fixed-width popovers that should not stretch.
- **UICorner clipping:** `UICorner` only rounds the object's own background; it does **not** clip descendant content to the rounded shape. Use a `CanvasGroup` with `UICorner` when you need rounded clipping.
- **TextScaled constraints:** `TextScaled` alone can make text shrink or grow without bounds. Add a `UITextSizeConstraint` with sensible `MinTextSize` and `MaxTextSize` values.
- **Gamepad/keyboard focus:** Set `GuiService.SelectedObject` to the first interactive button when opening a menu, and use `GuiService.SelectedObjectChanged` to keep visual focus indicators in sync. Without this, controller/keyboard players cannot navigate your UI.

## General container properties and patterns

- ZIndex (per GuiObject) for layering within one container.
- For world containers, combine AlwaysOnTop + high Brightness + appropriate MaxDistance to keep important markers visible.
- Organize complex UIs with multiple ScreenGuis (one for HUD, one for modals, one for toasts) and toggle .Enabled or use DisplayOrder rather than constantly re-parenting.

See the parent SKILL.md and the other references/ files for how to combine these containers with layouts, strokes, and the "particles in UI" techniques.

---
read_when: "Build 2D particle effects or combine UI with 3D previews"
last_reviewed: 2026-06-17
---

# Particles and effects inside UI

Direct `ParticleEmitter` instances live in the 3D world (parented to BasePart or Attachment) and do not render inside ScreenGui hierarchies. This file covers the practical techniques used in real high-quality Roblox experiences to achieve particle-like, VFX, or animated visual effects *within* 2D UI.

## Technique 1: scripted 2D particle pools (most common for HUD/rewards)

Create a small pool of ImageLabel (or Frame with UIGradient/UIStroke) instances, usually inside a CanvasGroup or dedicated "Effects" Frame.

On demand (button click, reward, hit marker, level up, etc.):
- Take a pooled instance.
- Set its Image, initial Position (scale), Size, Transparency, Rotation, Color.
- Tween several properties over a short lifetime (Position in a direction or with gravity simulation, Size, Transparency to 1, Rotation).
- On tween Completed or after a lifetime, reset and return to pool.

**Advantages:** Full control, cheap, easy to integrate with UI layouts and tweens from the animation skill.
**Performance notes:** 
- Cap the maximum concurrent particles (e.g. 30-80 depending on device).
- Recycle instead of Destroy/Instance.new every time.
- Use small, low-resolution textures with alpha.
- Test at lowest graphics quality: transparent overdraw adds up fast.

Many community assets exist (Emitter2D style), but a simple hand-rolled pool inside a ModuleScript is more maintainable and customizable.

## Technique 2: ViewportFrame + 3D content (best for "3D in UI")

1. Place a ViewportFrame inside your ScreenGui (or a panel).
2. Give it a CurrentCamera.
3. Parent a small "effect world" model directly to the ViewportFrame (there is no separate `.World` property) containing parts, meshes, and optionally a small rigged model playing an AnimationTrack or driven by IKControl.
4. Tween the ViewportFrame's own Size/Position/GroupTransparency (via a parent CanvasGroup) for entrance/exit.
5. Or tween things *inside* the viewport (camera CFrame for a sweeping reveal, part positions, rig poses).

**Important:** Real `ParticleEmitter`, `Beam`, `Trail`, and `Light` objects do **not** render inside `ViewportFrame`. Use the viewport's built-in `Ambient`, `LightColor`, and `LightDirection` properties for lighting, or fake particle effects with scripted ImageLabels/CanvasGroup techniques from this reference.

**Gotchas:**
- ViewportFrames have a non-trivial cost. Don't have 5 of them active and visible at once on mobile.
- Lighting inside the viewport is independent: match or deliberately contrast with the main scene.
- Size the internal content appropriately so it doesn't require extreme camera distances.

## Technique 3: CanvasGroup + group effects + UIStroke / gradient animation

- Wrap a panel or icon in a CanvasGroup.
- Rapidly tween GroupTransparency + GroupColor3 for "flash", "dissolve", or "pop" group effects.
- Animate a UIStroke's Thickness/Color/Transparency in a loop (or via a short tween sequence) for energy/shimmer borders.
- Combine with a UIGradient whose offset or color keys are tweened for moving highlight or charging effects.

CanvasGroup allocates a render target proportional to its on-screen size. Compare its cost with individual ImageLabel particles; large or stacked CanvasGroups can be expensive.

## Technique 4: text + MaxVisibleGraphemes + supporting particles

The typewriter effect (detailed in the animation skill's ui-tweens reference) can be augmented with tiny per-character "dust" or "spark" ImageLabels that are created, tweened outward/upward with slight random variation, and then cleaned up.

This gives a very high-production "magical text" or "holographic" feel without heavy cost.

## Integration with the rest of the toolset

- Drive UI particle bursts from AnimationTrack markers (see roblox-animation skill). A "FootStep" or "AbilityCast" marker can call a function that spawns the appropriate 2D reward burst or ViewportFrame effect.
- Combine with roblox-vfx best practices (flipbooks, proper transparency sequences, low rate + clever size, WindAffectsDrag where relevant) when driving effects from animation markers. Remember that real ParticleEmitters/Beams/Trails do not render inside ViewportFrame.
- Respect the performance guidance in the roblox-core skill (fill rate, overdraw, mobile caps).

## Concrete starter pattern (2D pool)

See `scripts/UIParticlePool.lua` for a basic example module. Typical API:
- `pool:emit(config)` where config contains texture, count, lifetime, velocity range, size range, color, etc.
- Internally grabs from pool, tweens, schedules return.

Always profile. The difference between "a few tasteful particles" and "it looks like a particle bomb went off" is the difference between smooth 60 fps on phone and a slideshow.

These techniques, used judiciously and synchronized via the animation and UI systems, are what make interfaces feel like a living part of the experience rather than static menus.