Skip to content

t1k:unity:ui:hud-layout

FieldValue
Moduleui
Version3.43.4
Effortmedium
Tools—

Keywords: dead band, FloatingLayer, HUD layout, HUD zoning, layout lane, LayoutGroup, OverlayLayer, RectTransform stack, screen overlap, widget anchor, widget overlap, zone

/t1k:unity:ui:hud-layout

A zone-based pattern for runtime game HUDs. Replaces absolute-pixel-offset stacking with declarative zones each owning a LayoutGroup. Built from the BackpackCrawler portrait HUD retrospective (2026-05-15) + Unity 6 uGUI research.

Activate when the user asks to:

  • Build a HUD with >3 widgets sharing one RectTransform
  • Fix HUD widgets visibly overlapping or covering each other
  • Refactor a HUD that uses UIPadding + HPBarHeight + N style absolute offsets
  • Create a portrait or landscape mobile HUD with zone separation
  • Add tooltips / drag ghosts / popups that should always render on top
  • Add full-screen flash overlays (damage flash, level-up text)

Skip for: pure modal panels (use t1k-unity-ui-ugui modal pattern); decorative-only layouts; UI Toolkit (use t1k-unity-ui-toolkit).

HUD contains >3 widgets in same RectTransform?
├── YES → split into named zones (this skill)
│ └── Each zone gets LayoutGroup OR explicit anchors
└── NO → anchors only, no LayoutGroup needed
Widget is built at runtime (tooltip / drag ghost / popup)?
├── YES → parent into FloatingLayer + SetAsLastSibling on Show
└── NO → parent into the appropriate zone
Widget is a full-screen flash or centered transient text?
├── YES → parent into OverlayLayer
│ ├── Always-bottom (e.g. DamageFlash) → SetSiblingIndex(0)
│ └── Always-top (e.g. LevelUpFlash) → SetAsLastSibling on Show
└── NO → goes in a zone or FloatingLayer

Zone-based HUD template (portrait reference: 1080×1920)

Section titled “Zone-based HUD template (portrait reference: 1080×1920)”
Canvas (ScreenSpaceOverlay, sortingOrder=10)
├── BottomPanel (35% bottom, full width)
│ ├── PhaseRow anchor=top, full width, h=PhaseHeight [HorizontalLayoutGroup]
│ ├── StatsLeftZone anchor=BL, w=StatsWidth, h=zoneH [VerticalLayoutGroup, UpperLeft]
│ ├── GridZone anchor=center, fixed w×h [no LayoutGroup; child has GridLayoutGroup]
│ ├── ActionRightZone anchor=BR, w=StatsWidth, h=zoneH [VerticalLayoutGroup, UpperRight]
│ └── ActionCenterZone anchor=B, w=ActionWidth, auto-h [VerticalLayoutGroup, LowerCenter]
├── FloatingLayer full-canvas stretch, no Image, no LayoutGroup
└── OverlayLayer full-canvas stretch, no Image, no LayoutGroup (top-most sibling)

Reference impl: Assets/Demos/RPG/BackpackCrawler/Editor/BackpackCrawlerSceneSetup.Canvas.HudZones.cs.

Zone purposeLayoutGroupchildAlignmentchildControl{Width,Height}childForceExpand
Stat stack (HP, level, XP)VerticalLayoutGroupUpperLefttrue, truefalse, false
Phase row (single label)HorizontalLayoutGroupMiddleCentertrue, truefalse, false
Action column (mutex buttons, each needs LayoutElement)VerticalLayoutGroupLowerCentertrue, truefalse, false
Inventory gridGridLayoutGroupn/an/a (uses cellSize)n/a
Float-above zoneNonen/an/an/a
Section titled “Modal vs HUD canvas separation (sortingOrder constants)”
public const int CanvasOrderHud = 10; // Main HUD canvas
public const int CanvasOrderFloatingLayer = 20; // Tooltips/ghosts (sibling of HUD root, above HUD widgets)
public const int CanvasOrderOverlayLayer = 30; // Flash panels (above floating)
public const int CanvasOrderModal = 50; // Modal panels with own Canvas + CanvasGroup
public const int CanvasOrderModalAbove = 60; // Modal-above-modal (e.g. confirm dialog atop shop)

Modals MUST get their own Canvas + CanvasGroup + GraphicRaycaster + a backdrop dim Image (full-screen, alpha 0.7). Without the backdrop the HUD beneath bleeds through visibly.

FloatingLayer is for runtime-built widgets that need explicit z-order management.

// In SceneSetup, after canvas + BottomPanel exist:
var floatingLayer = new GameObject("FloatingLayer", typeof(RectTransform));
floatingLayer.transform.SetParent(canvas.transform, false);
var fl = floatingLayer.GetComponent<RectTransform>();
fl.anchorMin = Vector2.zero; fl.anchorMax = Vector2.one;
fl.offsetMin = Vector2.zero; fl.offsetMax = Vector2.zero;
floatingLayer.transform.SetAsLastSibling();
// No Image, no LayoutGroup → never blocks raycasts when empty.
// Runtime tooltip creation:
tooltipPanel = new GameObject("TooltipPanel", typeof(Image));
tooltipPanel.transform.SetParent(floatingLayer.transform, false);
// Show:
tooltipPanel.transform.SetAsLastSibling();
tooltipPanel.SetActive(true);

OverlayLayer is identical structure but sits above FloatingLayer (further SetAsLastSibling). Use sibling-index discipline:

  • SetSiblingIndex(0) — always-bottom (e.g., DamageFlash that should stay below LevelUpText)
  • SetAsLastSibling() — most-recent-shown (e.g., LevelUpText that should always read)

Thirteen documented failures. Symptom → fix below; the full before/after, root cause, and inspector diagnostic for each is in anti-patterns.md (references/anti-patterns.md).

#Anti-patternFix
1Stacking widgets via absolute offsets in one RectTransformSplit into a zone with a VerticalLayoutGroup
2Runtime widgets parented to canvas root (creation-order z)Parent into FloatingLayer + SetAsLastSibling() on Show
3Modal panel with no backdrop dimFull-screen Image child, RGBA 0,0,0,0.7, raycastTarget=true
4ContentSizeFitter inside ContentSizeFitter (Unity 6 bug)One per chain; LayoutElement.preferredHeight on the inner
5Per-frame layout rebuild from text changesFixed-size container, no ContentSizeFitter
6raycastTarget=true on decorative graphicsfalse on decorative; true only on interactive
7Flash overlays without explicit sibling orderBoth in OverlayLayer; SetSiblingIndex(0) vs SetAsLastSibling()
8Empty zone container, content at sibling levelReparent content INTO its zone. An empty zone is almost always wrong
9Peripheral widgets anchored to canvas root at a guessed anchor %Parent into the owning zone, or use the flank-a-zone recipe
10Zone with sizeDelta.y=0 + childForceExpandHeight=falseSet the height, force-expand, or add a ContentSizeFitter
11Modal Canvas matchWidthOrHeight differing from the HUD’sEvery Canvas uses the same match value unless justified inline
12LayoutGroup childControl*=true with children lacking LayoutElementAdd LayoutElement with explicit preferred sizes
13HUD currency view keyed by raw row index, not the wallet CurrencyIdMatch-key MUST equal (int)WalletEntry.CurrencyId

The two highest-yield diagnostics, both inspector-visible without a repro:

  • A zone whose childCount == 0 → #8.
  • A RectTransform showing drivenByObject: <LayoutGroup> and width/height = 0 → #12.
FileContent
zone-template.md (references/zone-template.md)Copy-pasteable C# zone scaffold: constants, canvas + layers, all five zones, the flank-a-zone recipe, and post-build assertions
anti-patterns.md (references/anti-patterns.md)Full before/after, root cause, and inspector diagnostic for all 13 anti-patterns
  • t1k-unity-ui-ugui — Canvas, RectTransform, Image, Button, drag-and-drop API (foundation)
  • t1k-unity-ui-mobile-ui — Touch ergonomics, safe area, HUD overlap pre-commit checklist
  • t1k-unity-ui-toolkit — UXML/USS alternative; this skill is uGUI-specific
  • Frame and plate fit (sliced borders from the .meta, panel height from content, contrast, the three portrait sizes): t1k-unity-ui-ugui § “Frame fit checklist”. A zone that holds a plate is not done until that checklist passes.
  • Unity 6 uGUI research report: plans/reports/researcher-260515-1338-ugui-hud-best-practices.md
  • BackpackCrawler retrospective: plans/reports/brainstorm-260515-1337-backpackcrawler-ui-visual-overlap.md
  • Unity Learn — UI optimization tips (multi-canvas batching)
  • Unity Manual — uGUI Auto Layout (LayoutGroup performance characteristics)

A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:

  • Capture OLD before the first edit and NEW after the last (screen: ScreenCapture in Play mode per t1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file).
  • Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending: ”, never a fake image.