Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/roblox-ui

roblox-ui

Verified

Roblox UI with ScreenGui and PlayerGui: ResetOnSpawn, UDim2 scale and offset, UIListLayout flex, safe areas, StyleSheet, gamepad selection and touch controls. Use for Roblox HUDs, shops or settings menus, or UI that clips on phones, resets on respawn or loses controller focus. Load `game-ui-ux` too. Not for input mapping (`input-systems`) or purchase checks (`roblox-networking`).

references/input-navigation.md

View on GitHub
# Roblox UI input, selection, and motion

Read this for gamepad navigation, touch/mouse parity, modal focus, `ContextActionService`, or UI
motion. Targets Roblox's rolling platform APIs.

## Control contract

- Prefer `GuiButton.Activated` for the primary action because it unifies mouse, touch, and gamepad.
- Give every interactive state a visual response: hover where a pointer exists, pressed, selected,
  disabled, and busy if an operation can take time. Do not communicate state with color alone.
- Make touch targets comfortably hittable and separated; do not add invisible hit zones that overlap
  neighboring controls.
- Show input prompts that match `PreferredInput`, but never hide the only explanation of an action
  during device switching.

## Selection graph

On screen open, select the most likely safe action—not a destructive action. Use
`GuiService.SelectedObject`. Let automatic selection handle simple lists; assign
`NextSelectionLeft/Right/Up/Down` where layout geometry is ambiguous. Test every edge and a full
round trip through the graph.

Set initial selection only after the control is rendered and only while
`UserInputService.PreferredInput` is `Gamepad` (or `MicroGamepad`, a gamepad without a
thumbstick such as a TV remote). Capability flags mislead here: `TouchEnabled` is true on touch laptops and a
phone with a paired gamepad should navigate by focus. Re-check on
`GetPropertyChangedSignal("PreferredInput")`; do not force a selected object on a touch-first
screen.
Inspect the default adornment. A custom `SelectionImageObject` must remain a valid visible
`GuiObject` (it can live offscreen as the reusable template) and should match the interface's focus
treatment instead of adding a large glow.

When a modal opens:

1. remember the prior selected object if it still belongs to the underlying screen;
2. prevent interaction with the screen beneath it;
3. select the modal's first safe control;
4. keep directional navigation inside the modal;
5. on close, restore the prior object or a stable fallback.

To keep directional navigation inside the modal, set `GuiBase2d.SelectionGroup = true` on the modal
root and set its `SelectionBehaviorUp`/`Down`/`Left`/`Right` to `Enum.SelectionBehavior.Stop`.
Prefer these properties over the older `GuiService:AddSelectionParent()`/`AddSelectionTuple()`
groups: the properties live on the modal's own Instance, so they are visible in Explorer and
disappear with it, while a named `GuiService` group must be removed by hand.

## Context actions

Use `ContextActionService:BindAction()` for screen-level actions such as close/back, tab change, or
an ability-bar shortcut that is not already owned by a button. Bind on screen activation and
`UnbindAction()` on close. Return `Enum.ContextActionResult.Sink` only when the UI intentionally
consumes the action; otherwise allow gameplay to receive it.

Do not create a second input system inside a menu. Coordinate screen actions with `input-systems`
and preserve the project's existing action names and bindings.

For cross-device action binding defined at edit time, the Input Action System
(`InputContext`/`InputAction`/`InputBinding`) is the modern layer: it maps one action to
keyboard, gamepad, and touch at once, and an `InputContext` can be enabled/disabled (with
`Priority`/`Sink`) so a menu's actions replace gameplay actions while it is open. Use it for
screen-level action binding and cross-device parity; keep `GuiService.SelectedObject` and the
neighbor graph for moving UI focus itself.

## Motion lifecycle

- Read `GuiService.ReducedMotionEnabled`; replace spatial movement with an instant state or short
  opacity change when reduced motion is requested.
- Reuse a small timing/easing vocabulary. Typical state transitions should be quick enough not to
  delay interaction.
- Cancel or supersede an in-flight tween when the target state changes. Do not queue contradictory
  open/close animations.
- Animate a stable parent (`CanvasGroup` is useful for group transparency) instead of spawning a
  tween for every descendant.
- The logical state changes immediately; animation visualizes it. Never make server-critical state
  depend on tween completion.

## Controller verification

Use Studio's Controller Emulator and also a real controller when available. Verify initial focus,
all directions, activation, back/cancel, tab/shoulder navigation if used, scroll-following selected
items, focus restoration, and mouse-to-gamepad switching. Controller emulation proves mapping and
navigation, not TV legibility; use Device Simulator/console sizing for that.

## Primary references

- `https://create.roblox.com/docs/reference/engine/classes/GuiService`
- `https://create.roblox.com/docs/studio/testing-modes`
- `https://create.roblox.com/docs/input/input-action-system`
- `https://create.roblox.com/docs/input` (PreferredInput)
- `https://create.roblox.com/docs/production/publishing/console-guidelines`
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall