The Template interface

Fusion screens draw server state through Charm, use Theme tokens and shared components, animate through UI/Util/motion, and adapt to phone, gamepad, console, VR and accessibility settings.

Roblox Template / The Roblox Template

The interface draws what the server decided and sends intents for new actions. Fusion 0.3 builds the Instances; Charm holds state; UI/Util/fromCharm connects them. Screens know the game, reusable components take props and return Instances, and controllers prepare feature-specific display values.

The interface's owners

UI/App.luau

Mounts core screens and then the current place's screens. Every screen but the HUD and the toasts is required inside its builder, so a switched-off feature's screen is never loaded; menu windows, Settings, Feedback, Friends and the test purchase dialog load and build the first time they open, then keep their state, and the showcase stage is built on the first scenario load, not at startup. The admin panel and console are not here: they live in src/core/admin/, are built into ServerStorage.AdminSuite and are cloned into the PlayerGui of those who may use them (AdminService/Delivery), so a player who cannot use them never downloads them.

UI/Components/

Reusable controls, windows, lists, tables and grids; the charts (including Sparkline) are in UI/Components/Charts/. Components know no game rules and fire no remotes. The showcase's component gallery shows every one, and a spec fails while one is missing from it, so a new component gets a place in a gallery section.

UI/Screens/

Compose components, bind game state, send intents and own their display layer.

UI/Theme.luau

Every colour, font, text size, spacing, radius, spring preset and layer. Screens and components use tokens: colour literals fail lint-boundaries (ui-colours-from-theme), and so does a pixel literal for padding or a gap in the interface or the admin suite instead of Theme.spacing (ui-spacing-from-theme). The accent is kept for what means something (the primary button, progress, focus, and the slim Theme.marker bar on a selected tab or row); hover and selection tint with the neutral colors.highlight, never a coloured fill.

UI/Menu.luau

The game-window menu under the currencies. UI/App adds each enabled window's button at startup from its WINDOWS list and requires and builds the window the first time it opens; the HUD adds the Leaderboard's, whose window is built the same way. A menu button builds its open bar, dot and pulse the first time they show.

UI/Topbar.luau

The sole TopbarPlus owner (TopbarPlus 3.5.0), for Settings, Feedback (while platform is on), Friends (a person icon, while community or referrals is on), Players (the custom player list's button with its own icon, assets.images.icons.players, on touch, with a controller and in VR, which have no Tab key) and staff tools in Roblox's top bar; a game adds an icon with Topbar.button, and its windows go on the menu. A button a gamepad selects shows an A prompt (TopbarPlus's own is B), and TopbarPlus's highlightKey is off, so D-pad Up no longer jumps to the top bar from anywhere. Settings, Feedback, Friends and the menu's windows close each other, and none of the three dismisses the main menu. Feedback and Friends are not menu windows. UI/Util/topbarLayer lifts TopbarPlus's icons to Theme.layers.topbar, so a window's or the main menu's backdrop never dims the top bar's buttons.

UI/Util/

Fusion and Charm plumbing: fromCharm, deviceState, motion, presence, keyed, rowWindow, clock and ask; widget and packed, a HUD piece's place in the layout; scrollBar, a scroll bar only while the content really overflows, so a frame sized to its content shows no phantom bar; shortcutAllowed, so a Button's or SegmentedControl's gamepad shortcut acts only while the control is drawn and no other screen holds the selection; userNames, the display name and username of a user id (read from Players, else one Roblox lookup for every unknown id, remembered for the session); and topbarLayer. UI/Util/README.md lists them all.

All paths above start at src/core/client/. UI/Components/README.md lists existing controls (charts: UI/Components/Charts/README.md); check it before creating another one.

From server state to a screen

Use ClientState.playerData for the player's slot, ClientState.accountData for account-wide claims, SharedState for public server facts and ClientState or a local Fusion Value for interface-only state. Select the smallest needed slice with fromCharm(scope, getter). Its optional active getter pauses tracking while a view is hidden, retaining the last value.

State in, intents out. A server owner writes immutable Charm state. CharmSync replicates public facts and the current player's private data to client atoms. fromCharm turns a selected getter into a Fusion Value, and the screen draws it using components. A player action sends an intent back through Remotes for the server to decide.

Screens never require Rules, DataService or CurrencyService. A controller may derive display rows with pure rules, such as ShopController.rows (a computed getter, priced only when read); the server repeats the decision when the request arrives. Purchase prompts go through MonetizationController, sound through SoundController and celebrations through EffectsController. Use UI/Util/ask for a query's shared transport-failure handling.

The HUD is laid out, not positioned

Every always-on HUD piece (the currencies, the menu, the event banner, the toasts, the boost bar, the tutorial, the touch actions, and the custom player list and chat window) is a widget of Config/Layout, placed by LayoutController so nothing overlaps on any screen and bound to its frame with UI/Util/widget. Roblox's chat window, thumbstick and jump button are kept clear where Roblox reports them. A HUD frame sets no Position of its own: a game names a region or zone for its own piece in Config/Overrides/Layout.luau, and players move what is not locked from Settings, Customize layout. See the HUD layout.

Adding a screen

  1. Scaffold and choose data

    Run lune run new -- screen <Name> or component. Read Screens/Hud.luau, Components/Button.luau and App. Add server sync fields only when needed, and record a contract change.

  2. Build through the scope

    Use the (scope, props) -> Instance pattern with an exported Props type. Create through the Fusion scope so scope:doCleanup() owns cleanup. Lists use stable keys: Fusion 0.3's ForPairs and ForValues may rebuild a row that stays when another is removed, so a list whose rows hold state (focus, animation, a timer) uses UI/Util/keyed, which keeps a row's instance while its key stays. A long ScrollList whose rows size themselves uses UI/Util/rowWindow to build only the rows in view, as LeaderboardList and InventoryWindow do.

  3. Use the screen and theme owners

    Build the ScreenGui with Components/Screen and a Theme layer: hud 1, menu 5, windows 11, dialogs 50, topbar 60, layoutEditor 70, admin 80, effects 85, console 90, toasts 100. A piece of the HUD also declares its widget. Read images and sounds from Shared.assets; animate through UI/Util/motion with a Theme.springs preset, never scope:Spring.

  4. Wire intent and navigation

    Send choices through Remotes or a controller; show the server answer. Give a game window an entry in App's WINDOWS (its menu button, an optional dot getter, a load that requires the screen), and make gamepad focus, closing and return selection work.

  5. Verify every input mode

    Follow the ui-screen and playtest skills for mouse, touch, gamepad and VR, including refusal, resize, close and reopen.

In-world leaderboards are the ScreenGui exception: they mount SurfaceGuis in PlayerGui with tagged parts as Adornee. The bootstrap loading screen is the plain-Instance exception because it runs before packages replicate.

One interface on phone, gamepad, console and VR

Device facts come from Device.device() (input, vr, tenFoot, textSize, reducedMotion), maintained by DeviceController. The input starts as the device is (a console or TV: gamepad; a touch screen without a mouse: touch; anything else: mouse) and then follows the player's real input through LastInputTypeChanged. It does not read UserInputService.PreferredInput, which says gamepad on a PC the moment a controller is plugged in and would join the whole interface at console size. Device.inputChanged fires on a switch, for code that acts on the switch itself. A component reads the common facts from UI/Util/deviceState (touch, gamepad, vr, reducedMotion, scale, and room, the safe area and on-screen keyboard a window fits between): one shared Charm subscription per fact for the session, not one per component. Anything else goes through fromCharm over Device.device. Connected hardware flags such as TouchEnabled do not tell you the current input mode. Components/Screen applies the shared scale to design-pixel layouts; measured AbsoluteSize values must be divided by UI/Util/designScale before reuse as design offsets.

Screen safe insets keep content inside device bounds. Pressable targets grow to Theme.touchTarget, currently 44 design pixels. Touch buttons suppress hover; drags track the initiating finger. Roblox's thumbstick and jump button are locked widgets of the layout, kept clear where Roblox draws them: the menu takes more buttons to a row as its column gets shorter, and shrinks and scrolls only when four to a row still overflows, and the boost bar stacks under the touch action buttons while they are up. Windows and text inputs use shared keyboard-safe bounds instead of custom viewport loops. Orientation is landscape only (Roblox's default); a game that allows portrait runs the cross-device audit again.

The exact scale inputs live in Theme.scale and Util/DeviceScale: the scale follows the screen's height, or its width when that is shorter (so a portrait window does not outgrow its width), clamped from 0.85 to 1.5, with a 1.25 gamepad factor, a replacing 1.4 ten-foot factor or a 1.15 VR factor. The source note docs/systems/UI.md owns these values; docs/testing/Cross-device Audit.md records every screen on phone, tablet, PC, console and VR.

Accessibility

The Template follows Roblox's own accessibility settings and adds in-game ones only where Roblox has none. Each applies at once, without a rejoin.

Text size

Roblox's Preferred Text Size enlarges text itself: never use TextScaled or a font multiplier. Flowing Text grows its height and wraps, a fixed-width label truncates, and essential menus scroll so every action stays reachable at the largest size.

Reduced motion

Roblox's Reduced Motion makes every spatial animation in UI/Util/motion and presence instant, cuts menu, page and camera transitions, and EffectsController plays no particles (so no flash).

Contrast

Colours come only from Theme.colors, held to WCAG AA (4.5:1) by Theme.access.spec for every text and surface pair, button palette, hovered or selected row tint, Badge chip and the menu tiles' darkest shade. Text on a danger or accent fill uses textOnAccent; a Badge's text is its colour lightened by Theme.tint.chipText. Theme.colors.textMuted is its own value, no longer the Brand one.

Colour is never the only signal

A state also shows in text, an icon or a shape.

In-game settings

Camera motion and Vibration (Settings, Accessibility) are read by CameraTransitionController and HapticController, with per-kind volume sliders under Audio.

Not offered

No in-game high-contrast theme and no use of PreferredTransparency; captions are not needed, since no Template sound carries information that is not also on screen. A game that adds speech or audio cues captions them.

The full table is the Template's docs/testing/Accessibility Audit.md.

Text and languages

No player-facing text is typed into a screen, component, UI/Util, App, Menu or Topbar. It is a key in Config/Strings (English source, {name} placeholders), read with Localize.text("area.name", args) from Shared/Util/Localize when the label is built or inside the Computed that already rebuilds it, never per frame. A game adds or rewords strings in Config/Overrides/Strings.luau.

On the client, Localization.load runs before the interface is built: it installs Roblox's translator for the player's locale, so a Spanish player sees Spanish once the experience's localization table has it, and a key the table lacks falls back to English. Util/Format follows the locale's digit grouping, decimal mark and duration units. lune run strings writes build/localization.csv (every key, plus Config labels by source) to upload in the Creator Hub, where automatic translation fills in other languages. Config/Localization.pseudo makes every keyed string 40% longer for an overflow test in Studio.

A label and a toast
Text = Localize.text("pets.equipped", { count = use(count), max = MAX })NotificationService.notify(player, "success", "pets.hatched", { args = { name = name } })

The server sends keys too: a toast or notice from a service names a Config/Strings key and its arguments, never an English sentence. lune run lint-boundaries fails on a literal in interface code and on a key the table lacks. Staff tools and the developer showcase stay in English; Config labels and server refusal messages are shown as written and translated by Roblox by source text. Source note: docs/systems/Localization.md.

Avoid layout and performance traps

Fusion 0.3 springs never sleep, so interface code animates only through UI/Util/motion(scope, goal, style), which makes an animator while the goal moves and releases it once settled; lune run lint-boundaries fails a direct :Spring( (the ui-springs-sleep rule). UI/Util/presence handles enter and exit with separate timings, and Animated = false skips animation for values that tick. A list narrowed as the player types (Dropdown) is built with UI/Util/keyed, so a keystroke that narrows it builds nothing and one that widens it builds only the rows that come back. Pause hidden views, avoid per-frame Computeds for large visuals and springs on ticking data, and avoid size or scale animation of large windows. Countdowns read the shared UI/Util/clock(scope, open), rather than creating a loop each. Put HUD text over the world on a visible surface such as a pill or Panel. Screens.profiles.spec fails if any screen App can open animates at rest, works while closed or keeps instances after open and close cycles.

Component details worth knowing

Window and Drawer

A panel catches clicks on its empty space (a ClickSink), so clicking between fields no longer closes it as if the backdrop was clicked. Window's FitContent makes Size's height a maximum, the window as tall as its ScrollList's content; a game's own form window sets it.

Dropdown

The open list floats over later fields by default and draws above them. Inline = true makes the open list take room instead, pushing what follows down: use it inside forms and scrolling lists. While open, the field itself is the filter: on a keyboard the cursor is already in it, so typing narrows the list and Enter picks the first match; on touch, tap the field to type; a gamepad starts on the options and can move up into the field. Rows are built only while open, one per matching option. SelectedMany (a list, in place of Selected) picks several: each row has a check box that shows a tick while picked, a press toggles it and the list stays open, the closed field lists every pick (cut off with "…" where it runs out of room), and a Clear row empties the selection; a gamepad's A toggles a row and B closes. Kind = "user" takes user ids as options and shows people: each row has the headshot, the display name and the @username (UI/Util/userNames), the filter matches either name, and an option that is not a number (a me or all beside the people) stays a plain row. It works with Selected or SelectedMany.

Dialog and ListRow

Dialog sizes to its content, so both buttons always show. ListRow's inset is Padding, on both sides; while Selected (or Marked, the player's own row) it shows the accent marker on its left edge over the neutral tint, and Pressable = false keeps a label-only row (a team heading) at its own height, unhovered and unselectable.

Button

Full-width buttons do not grow on hover, so their corners never clip; Theme.colors.dangerHover is the danger button's hover colour. The disabled state shows at once, with no spring, so a list that enables its rows starts no animation per button.

Avatar, StatCard and Sparkline

Avatar's Ring draws a thick ring in a colour (a role's). A StatCard's sparkline sits in a band below its text, and a Sparkline's Max is the scale's floor, marked by a target line, not a clamp.

ChatWindow, PlayerRow and PlayerCard

The Template's chat window in custom chat mode, one row of the custom player list (with a friends mark after a friend's name), and the player card that list pops out (a still Friends mark in place of Add friend for a friend, and Trade while trading offers it). A game swaps the first two for its own with ChatController.setWindow and PlayerListController.setRow; see Chat and Player list in the systems catalogue.

Inventory and trade windows

Both are built from item tiles (an icon, a name and a badge), not rows. InventoryWindow keeps its toolbar in place and scrolls its equipment slots and a CollectionGrid with a custom Cell, one page of tiles at a time: the pattern for a game's own grid of tiles. TradeWindow shows the two offers side by side as cards of tiles, the player's tradable items as a grid of the same tiles, and a footer that stays in place with Cancel and the next step.

Toast and Notice

Each card fades as one CanvasGroup, and its outline fades by the same amount: a UIStroke is drawn outside the group's texture, so GroupTransparency alone never reaches it. A game's own fading card with an outline does the same.

The source of truth is docs/systems/UI.md, the ui-screen skill and the README inside UI/Components. Runtime checks on real touch, controller and VR devices remain part of review; pure tests cannot prove how a Roblox GUI renders.

Updated