The HUD layout

How the Template places every HUD piece as a widget so nothing overlaps, how a game names zones and modes, and how players rearrange their HUD per device in Settings.

Roblox Template / The Roblox Template

Every always-on HUD piece (the currencies, the menu, the event banner, the toasts, the boost bar, the player list, the chat) is a widget the layout places. Nothing on the HUD overlaps on any screen, and a game lays its HUD out by naming a place instead of writing pixel offsets. A player can move the widgets that are not locked from Settings, and the layout fits everything else around them; their layout is saved per device class.

Windows, dialogs and the main menu are not widgets: they open centred over the HUD. Roblox's top bar is outside the layout's area (HUD screens use the safe inset, which ends below it). Roblox's chat window, touch thumbstick and jump button are widgets with no screen of the Template's: areas kept clear exactly where Roblox reports them.

The model

Area

The HUD screens' safe area in design pixels (a 1080-pixel-tall screen), less a margin on every side: Theme.hudMargin, or the distance Roblox draws its chat window from the edge while that window shows, so the HUD lines up with it. The on-screen keyboard is not taken away: the HUD stays put while a player types.

Regions

Eight: topLeft, top, topRight, left, right, bottomLeft, bottom, bottomRight (Rules/Layout.REGIONS). A region stacks its widgets along its axis (Config/Layout.axes, vertical by default) in order, Theme.spacing.sm apart: a corner's stack is packed into its corner, top and bottom against their edge and centred along it, and left and right sit in the middle of their edge, in order from the top. A middle stack that cannot sit centred (a tall corner stack, the chat's area, the thumbstick) takes the free room nearest the middle, still in order, never over anything.

Zones

A game's own places (Config/Layout.zones), below. The eight regions are the built-in zones; anywhere a region is named, a zone works too.

Widgets

Config/Layout.widgets: a label (a Config/Strings key), a default region and order, devices (another default on one device class), priority, locked, allowed and mode, resizable with minSize and maxSize, only (the device classes it shows on) and, for an area kept clear, a fixed size. Every other widget's size is measured from its screen.

Device classes

desktop, phone, tablet, console, vr. A touch screen whose shorter side is under Config/Layout.phoneShortSide (600) is a phone. console is a ten-foot screen (a console or a TV: no chat window, read from across the room), not a controller in hand: a gamepad picked up on a computer or a handheld keeps the desktop layout, with Roblox's chat still kept clear. Defaults and saved layouts are per class.

Shapes

A widget takes the shape of its edge: a row along top and bottom, a column everywhere else. The menu becomes a row of one to four buttons tall along the top and bottom, the currencies and the demo's buttons sit side by side there and stack as a column on a side edge or in a corner, and grids fill from the edge they are packed against (UI/Util/packed). On a side edge the menu takes the fewest buttons to a row, from two to four, that fit under the currencies in the room its column really has, below Roblox's chat and above the thumbstick (LayoutController.columnRoom, Rules/Layout.columnRoom): a shorter screen adds columns before anything scrolls. It counts only Roblox's areas, so the fit never feeds back into the layout.

A player's placement is a zone and an order in it, never pixels, so a layout survives a resize, a rotation and a new device of the same class.

The Template's widgets

WidgetDefaultFlags
chatConfig/Chat.window's place (topLeft)Roblox's window: strict in Roblox's eight places, desktop and tablet. The Template's own window in custom chat mode: free, every device, resizable
thumbstickbottomLeftLocked, phone and tablet, as Roblox reports it (160 x 160 until then)
jumpbottomRightLocked, phone and tablet, as Roblox reports it (170 x 170 until then)
currenciestopLeft 2 (console: left 1)Priority 2, under the chat; on a console, which has no chat, in the middle of the left edge, clear of the top bar's icons
menutopLeft 3 (console: left 2)Priority 1, under the currencies, resizable down to one row (it scrolls when four to a row is still too tall)
eventBannertop 1Priority 1
tutorialtop 2Priority 3: the HUD makes room for it while it shows
toaststop 3Priority -1: takes the room left; with none, it draws over the top centre
playerListConfig/PlayerList.list.corner 1Priority 2; takes its room only while open (custom player list)
touchActionstopRight 2Priority 1, under the player list, phone and tablet; smaller on a phone (Theme.touchActions.phone)
booststopRight 3Under the touch actions
demoActionsbottom 1The demo's buttons; a row along the top and bottom, a column elsewhere

A widget's screen is up only while it has something to show (the banner during an event, the boost bar while a boost runs); a widget without a size takes no room.

How the solver places widgets

Rules/Layout.solve(items, options) is pure and returns each widget's rectangle, region and whether it shows. LayoutController runs it on the client.

  1. Roblox's areas and locked widgets first

    The chat window, thumbstick and jump button are placed exactly where Roblox reports them, then every locked widget in its region. Nothing moves them.

  2. Each region's stack, by priority

    The stack holding the highest priority goes first. It takes the free run along its axis nearest its ideal place; when none is long enough, its resizable widgets shrink to minSize (the menu scrolls on a short phone).

  3. One at a time, then hidden

    A stack that still does not fit places its widgets one at a time, most important first: in its own region if it has room, else the nearest region with room (of two as near, the one on the stack's own edge first: a column with no room under the chat tries the middle of the left edge before the top edge), else not shown. On a screen too small for everything, the least important widget gives way rather than overlap.

Every layout keeps these on every screen and through every resize, checked on 24 screens and window sweeps from 320 to 3,840 pixels wide (Layout.responsive.spec): nothing overlaps or leaves the area; every widget sits flush on its region's edge; Roblox's areas push a stack along its axis, never sideways; and a widget changes region only when a better place has Config/Layout.hysteresis (24) design pixels to spare, so dragging a window's edge never makes the HUD flicker between regions. While the screen changes size, and for Theme.layoutResize (0.25 seconds) after, widgets jump to each new place (LayoutController.resizing), because a glide retargeted on every frame of a drag wobbled behind the window's edge; every other move still glides.

The solver's own guarantees are checked on 4,000 seeded screens from 320 x 240 to 3,840 x 2,160, in every device class and scale, with Roblox's areas right, stale, off screen, off or never reported, then through resize sequences (Layout.property.spec):

  • Every widget the solver places and shows is inside the area, margin included.

  • No two overlap, and none overlaps one of Roblox's areas: at least Theme.spacing.sm apart.

  • A widget is cut along its stack only when it is resizable, never under its minSize, and is never made larger than it asked.

  • A widget is hidden, or out of its own region, only when it has no room there at its smallest.

Roblox's own areas are where Roblox says, so two of those may overlap or leave the screen. A widget wider than the whole area is cut to it, not hidden.

Cost. Nothing runs per frame. The layout solves again only when a widget's measured size changes by a whole design pixel, the safe area, scale or device class changes, or the placements change, at most once a frame however many changes arrive. A settled HUD solves and writes nothing. A solve takes about 20 µs at 10 widgets and 40 to 50 µs at 30 in Lune's interpreter (lune run bench -- Layout.solve; ratios, not device times).

Zones and modes

A game lays out its HUD by naming the places it wants, putting each widget's default in one, and saying where players may move what.

A zone

Config/Layout.zones[id]: scale (its rectangle as fractions of the HUD's area; absent, the whole area), offset (design pixels added), anchor (where its stack packs, x and y from 0 to 1), axis ("vertical" by default) and shape (the shape its widgets take). Its stack never runs past the rectangle along its axis: what does not fit goes to the nearest region with room.

Free mode

Config/Layout.mode = "free", the Template's: a player may put a widget in any region, and in the zones it lists in allowed.

Strict mode

"strict": a widget goes only to its allowed zones (absent: its default places, so it may only be reordered). The solver never puts a strict widget anywhere else either: with no room in its zones it is hidden. The editor lights up its zones while it is held.

A widget's own mode

A widget's mode overrides the game's, in either direction. Roblox's chat window, which Roblox draws only in a few places, is a strict widget with a fixed allowed list in every game.

Where a player may put a widget is Rules/Layout.targets(widget, config): nowhere for a locked one. The editor's drags and d-pad, the solver's fallbacks and the server's check all use it.

A strict game: Config/Overrides/Layout.luau
return {	mode = "strict",	zones = {		-- The left quarter of the screen's middle, stacking down from its top.		leftRail = { scale = { x = 0, y = 0.2, width = 0.25, height = 0.6 }, anchor = { x = 0, y = 0 } },		-- A bar across the top centre, its widgets in a row.		topBar = {			scale = { x = 0.25, y = 0, width = 0.5, height = 0 },			offset = { x = 0, y = 0, width = 0, height = 120 },			anchor = { x = 0.5, y = 0 },			axis = "horizontal",		},	},	widgets = {		currencies = { region = "topBar", order = 1, allowed = { "topBar", "leftRail" } },		menu = { region = "leftRail", order = 1, allowed = { "leftRail", "right" } },		boosts = { mode = "free" }, -- this one anywhere	},}

A free game is the Template as it ships: mode = "free", no zones, every unlocked widget movable to any of the eight regions.

Placing a game's own HUD piece

Declare the widget in Config/Overrides/Layout.luau, then bind its screen's frame to it by id. The frame sets no Position or AnchorPoint of its own.

A game's quest tracker
-- Config/Overrides/Layout.luaureturn {	widgets = {		quest = { label = "layout.quest", region = "right", order = 3 },		currencies = { locked = true }, -- a Template widget players cannot move		demoActions = false, -- a Template widget this game does not use	},}-- src/main/client/UI/Screens/QuestTracker.luaulocal panel = Panel(scope, { Size = UDim2.fromOffset(260, 0), AutomaticSize = Enum.AutomaticSize.Y })widget(scope, "quest", panel)

UI/Util/widget(scope, id, frame, options) reports the frame's measured size to LayoutController, moves it to its place (gliding through UI/Util/motion once the HUD has settled, jumping while the screen changes size) and hides it when it has no room. It returns the place as Fusion state. Options: size (a resizable widget's wanted size), horizontal (its shape along the top and bottom edges), active (false gives its room back while it is off screen) and place = false (the screen positions itself from the returned place, as the toasts and the player list do).

The layout editor

While Config/Features.layoutEditor is on (on in the Template), Settings has a Customize layout button. It opens Screens/LayoutEditor over the HUD on its own layer (Theme.layers.layoutEditor, 70, above the windows and the top bar): every widget on this device is a box with its name in a chip beside it; a locked one says so and does not move. The HUD moves live as the draft is solved, so a preview never overlaps, and a move that would push the widget elsewhere or hide it is refused.

Press a box to hold it; past Theme.layoutEditor.dragThreshold (6 design pixels) it follows the pointer, and letting go puts it down in the nearest zone it may use, at the slot under the pointer. One drag at a time.

While a box is held, every zone it may go to is lit (LayoutController.zones: every region in free mode, only a strict widget's allowed zones, and never the screen's centre), the zone it is in now brighter (Theme.layoutEditor.zoneActive), and an outline shows the widget's solved place: where letting go leaves it, which a tall neighbour or Roblox's chat may have pushed along the edge. Let go on a side edge, it sits in the middle of that edge.

Save sends the layout, Reset puts this device's widgets back to the game's places (saved by Save) and Cancel saves nothing. While the editor is open, Roblox's chat window and input bar are turned off (they would take every press) and a stand-in box takes their place; however the editor closes, they come back as the game set them. The device class stays the one the editor opened on (it edits and saves that class's layout) and is read again when the editor closes; the chat hidden for the editor is measured again then, never taken for gone.

Saved data and server checks

PlayerData.layout holds the player's placements per device class: { [class]: { [widgetId]: { region, order } } }. A class with none uses the defaults, and a saved place a widget may no longer go to (the game turned strict, or removed a zone) gives way to its default. Schema version 5 dropped the old sideways nudge from every saved placement. It is written only by SettingsService.saveLayout, in the real save and a test-mode copy alike; while layoutEditor is off it is left untouched and not applied.

The client sends settings.requestLayout: a device class (one of five literals) and at most Config/Layout.maxSaved (32) placements of { id, region, order }, ids and zones at most 32 bytes. RemoteGuard refuses anything else, an extra field included. saveLayout refuses while the switch is off and past the shared settings bucket, then Rules/Layout.clean keeps only known widgets, each in one of its targets under the game's mode, with a whole order. A player moves only their own HUD: nothing they send changes what anyone else sees or anything the game decides. The client shows what it sent until the synced save holds it, or saveWaitSeconds (10) pass.

The source note is the Template's docs/systems/Layout.md.

Updated