t1k:unity:ui:hud-layout
| Field | Value |
|---|---|
| Module | ui |
| Version | 3.43.4 |
| Effort | medium |
| Tools | — |
Keywords: dead band, FloatingLayer, HUD layout, HUD zoning, layout lane, LayoutGroup, OverlayLayer, RectTransform stack, screen overlap, widget anchor, widget overlap, zone
How to invoke
Section titled “How to invoke”/t1k:unity:ui:hud-layoutUnity HUD Layout Discipline
Section titled “Unity HUD Layout Discipline”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.
When this skill triggers
Section titled “When this skill triggers”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 + Nstyle 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).
Core decision tree
Section titled “Core decision tree”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 neededWidget is built at runtime (tooltip / drag ghost / popup)?├── YES → parent into FloatingLayer + SetAsLastSibling on Show└── NO → parent into the appropriate zoneWidget 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 FloatingLayerZone-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.
LayoutGroup recipes
Section titled “LayoutGroup recipes”| Zone purpose | LayoutGroup | childAlignment | childControl{Width,Height} | childForceExpand |
|---|---|---|---|---|
| Stat stack (HP, level, XP) | VerticalLayoutGroup | UpperLeft | true, true | false, false |
| Phase row (single label) | HorizontalLayoutGroup | MiddleCenter | true, true | false, false |
Action column (mutex buttons, each needs LayoutElement) | VerticalLayoutGroup | LowerCenter | true, true | false, false |
| Inventory grid | GridLayoutGroup | n/a | n/a (uses cellSize) | n/a |
| Float-above zone | None | n/a | n/a | n/a |
Modal vs HUD canvas separation (sortingOrder constants)
Section titled “Modal vs HUD canvas separation (sortingOrder constants)”public const int CanvasOrderHud = 10; // Main HUD canvaspublic 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 + CanvasGrouppublic 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 + OverlayLayer pattern
Section titled “FloatingLayer + OverlayLayer pattern”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)
Anti-pattern catalog
Section titled “Anti-pattern catalog”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-pattern | Fix |
|---|---|---|
| 1 | Stacking widgets via absolute offsets in one RectTransform | Split into a zone with a VerticalLayoutGroup |
| 2 | Runtime widgets parented to canvas root (creation-order z) | Parent into FloatingLayer + SetAsLastSibling() on Show |
| 3 | Modal panel with no backdrop dim | Full-screen Image child, RGBA 0,0,0,0.7, raycastTarget=true |
| 4 | ContentSizeFitter inside ContentSizeFitter (Unity 6 bug) | One per chain; LayoutElement.preferredHeight on the inner |
| 5 | Per-frame layout rebuild from text changes | Fixed-size container, no ContentSizeFitter |
| 6 | raycastTarget=true on decorative graphics | false on decorative; true only on interactive |
| 7 | Flash overlays without explicit sibling order | Both in OverlayLayer; SetSiblingIndex(0) vs SetAsLastSibling() |
| 8 | Empty zone container, content at sibling level | Reparent content INTO its zone. An empty zone is almost always wrong |
| 9 | Peripheral widgets anchored to canvas root at a guessed anchor % | Parent into the owning zone, or use the flank-a-zone recipe |
| 10 | Zone with sizeDelta.y=0 + childForceExpandHeight=false | Set the height, force-expand, or add a ContentSizeFitter |
| 11 | Modal Canvas matchWidthOrHeight differing from the HUD’s | Every Canvas uses the same match value unless justified inline |
| 12 | LayoutGroup childControl*=true with children lacking LayoutElement | Add LayoutElement with explicit preferred sizes |
| 13 | HUD currency view keyed by raw row index, not the wallet CurrencyId | Match-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>andwidth/height = 0→ #12.
Reference Files
Section titled “Reference Files”| File | Content |
|---|---|
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 |
Related skills
Section titled “Related skills”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 checklistt1k-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.
Sources
Section titled “Sources”- 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)
Visual change notice
Section titled “Visual change notice”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:
ScreenCapturein Play mode pert1k-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.