agentleFS
rodrigo-guerraarodrigo-guerraa/roblox-hub/skills/vendored/game-ui-ux/SKILL.md

game-ui-ux

Skill2 starsChanged 31 days agoMITView on GitHub

Engine-agnostic game UI/UX design guidance, adapted for Roblox ScreenGuis. Covers responsive scale-based layout, safe areas, gamepad focus navigation, a panel/screen stack, event-driven HUD updates, accessibility and localization. Use when building or fixing a Roblox HUD, menu, shop, modal window or overlay; when UI breaks on phones, tablets or consoles, collides with the top bar, thumbstick or jump button, or can't be used with a gamepad; when a HUD polls state every frame; or when structuring panel flow so only one window is open at a time.

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Layout: use Scale sizes with AnchorPoint, UIAspectRatioConstraint, and UIListLayout/UIGridLayout/UIPadding.

    line 14
  2. Very specific:

    Panel stack: use a UIManager-style client module.

    line 16
  3. Very specific:

    Event-driven: update on RemoteEvent pushes or GetAttributeChangedSignal, never by polling in RenderStepped.

    line 22
  4. Very specific:

    Localization: use LocalizationTable and AutoLocalize, and let text containers grow with AutomaticSize.

    line 23
  5. Distinctive:

    Verify at real sizes: a phone in landscape (about 749×367 usable), a tablet, 1080p, and gamepad-only.

    line 33

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Game UI/UX

Where this conflicts with the roblox-lessons skill, roblox-lessons wins. Read roblox-lessons references/ui.md before building UI. It holds the TextScaled, inset, canvas-size and aspect-constraint traps.

Build HUDs and menus that stay correct on a phone in landscape, a desktop monitor and a TV with a gamepad.

On Roblox

  • Layout: use Scale sizes with AnchorPoint, UIAspectRatioConstraint, and UIListLayout/UIGridLayout/UIPadding. Never use offset-only pixel layouts. Size windows from the screen with a maximum cap.
  • Layering: give each layer its own ScreenGui with a fixed DisplayOrder (ladder: HUD 2–4, windows 5, notices 6, reveals 7, tutorial 9, effects 20, loading 100). Set ResetOnSpawn = false on persistent UI.
  • Panel stack: use a UIManager-style client module. Panels register by name, opening one closes the others, Escape or gamepad B closes the top one, and a changed signal lets HUD tiles hide under an open window.
  • Safe areas:
    • The top bar: GuiService:GetGuiInset() and IgnoreGuiInset.
    • Notches: ScreenGui.ScreenInsets.
    • On phones, the thumbstick (bottom-left), the jump button (bottom-right) and the chat button (top-left). Read TouchGui positions at runtime.
  • Gamepad and console: set the initial focus with GuiService.SelectedObject, set explicit neighbours with NextSelectionUp/Down/Left/Right, and mark controls Selectable. Style focus with SelectionImageObject. Track the input device with UserInputService.LastInputTypeChanged.
  • Event-driven: update on RemoteEvent pushes or GetAttributeChangedSignal, never by polling in RenderStepped. Build list rows once and update them in place.
  • Localization: use LocalizationTable and AutoLocalize, and let text containers grow with AutomaticSize.

Workflow

  1. Lay out with anchors, scale and layouts, never absolute pixel positions.
  2. Pick one scaling policy for the whole UI (size from screen height with caps), and decide where extra width goes.
  3. Inset critical UI from the top bar, notches and touch controls. Decorative art can bleed to the edges.
  4. Make every screen reachable by gamepad: give it an initial focus, neighbours and a visible focus style.
  5. Model screens as a stack (push an overlay, pop on back) instead of boolean flags.
  6. Drive the HUD from events.
  7. Verify at real sizes: a phone in landscape (about 749×367 usable), a tablet, 1080p, and gamepad-only. Report what you observed at each size.

Pitfalls

  • Offset sizes designed on one monitor overflow phones.
  • TextScaled turned off by setting TextWrapped afterwards (roblox-lessons ui.md).
  • HUD under the top bar, a notch or the thumbstick.
  • Nothing focused when a window opens, so the gamepad does nothing.
  • Polling player state every frame instead of reacting to pushes.
  • Rebuilding lists on every push, which restarts every progress bar.
  • Tiny fixed text; text with no size cap that balloons on big screens.
  • Menu flow as flags (isShopOpen, inSettings, ...). Use a stack.
  • English baked into fixed-width buttons, so translations overflow.
  • A refusal toast drawn under the window that triggered it.

References

  • references/layout-and-flow.md: scaling, safe-area math, focus navigation, a panel-stack sketch, world-space UI (BillboardGui, SurfaceGui, ProximityPrompt), accessibility, and localization-ready layout.

Related: game-feel (pops and transitions on top of this layout), roblox-lessons.


Adapted from awesome-gamedev-agent-skills (Apache-2.0). Modified; see SOURCE.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.