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 intoServerStorage.AdminSuiteand are cloned into thePlayerGuiof 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 inUI/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 ofTheme.spacing(ui-spacing-from-theme). The accent is kept for what means something (the primary button, progress, focus, and the slimTheme.markerbar on a selected tab or row); hover and selection tint with the neutralcolors.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
platformis on), Friends (a person icon, whilecommunityorreferralsis 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 withTopbar.button, and its windows go on the menu. A button a gamepad selects shows an A prompt (TopbarPlus's own is B), and TopbarPlus'shighlightKeyis 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/topbarLayerlifts TopbarPlus's icons toTheme.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,clockandask;widgetandpacked, 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 aButton's orSegmentedControl'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 fromPlayers, else one Roblox lookup for every unknown id, remembered for the session); andtopbarLayer.UI/Util/README.mdlists 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.
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
Scaffold and choose data
Run
lune run new -- screen <Name>orcomponent. ReadScreens/Hud.luau,Components/Button.luauand App. Add server sync fields only when needed, and record a contract change.Build through the scope
Use the
(scope, props) -> Instancepattern with an exported Props type. Create through the Fusion scope soscope:doCleanup()owns cleanup. Lists use stable keys: Fusion 0.3'sForPairsandForValuesmay rebuild a row that stays when another is removed, so a list whose rows hold state (focus, animation, a timer) usesUI/Util/keyed, which keeps a row's instance while its key stays. A longScrollListwhose rows size themselves usesUI/Util/rowWindowto build only the rows in view, asLeaderboardListandInventoryWindowdo.Use the screen and theme owners
Build the ScreenGui with
Components/Screenand a Theme layer:hud1,menu5,windows11,dialogs50,topbar60,layoutEditor70,admin80,effects85,console90,toasts100. A piece of the HUD also declares its widget. Read images and sounds from Shared.assets; animate throughUI/Util/motionwith aTheme.springspreset, neverscope:Spring.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.
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
TextScaledor a font multiplier. FlowingTextgrows 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/motionandpresenceinstant, cuts menu, page and camera transitions, andEffectsControllerplays no particles (so no flash).- Contrast
Colours come only from
Theme.colors, held to WCAG AA (4.5:1) byTheme.access.specfor every text and surface pair, button palette, hovered or selected row tint,Badgechip and the menu tiles' darkest shade. Text on adangeroraccentfill usestextOnAccent; aBadge's text is its colour lightened byTheme.tint.chipText.Theme.colors.textMutedis 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
CameraTransitionControllerandHapticController, 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.
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'sFitContentmakesSize's height a maximum, the window as tall as itsScrollList'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 = truemakes 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 ofSelected) 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 (ameorallbeside the people) stays a plain row. It works withSelectedorSelectedMany.- Dialog and ListRow
Dialogsizes to its content, so both buttons always show.ListRow's inset isPadding, on both sides; whileSelected(orMarked, the player's own row) it shows the accent marker on its left edge over the neutral tint, andPressable = falsekeeps 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.dangerHoveris 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'sRingdraws a thick ring in a colour (a role's). AStatCard's sparkline sits in a band below its text, and aSparkline'sMaxis 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.setWindowandPlayerListController.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.
InventoryWindowkeeps its toolbar in place and scrolls its equipment slots and aCollectionGridwith a customCell, one page of tiles at a time: the pattern for a game's own grid of tiles.TradeWindowshows 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: aUIStrokeis drawn outside the group's texture, soGroupTransparencyalone 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.
Keep display state and server decisions in their owners.
See where screens, controllers and state live.
Updated