Skip to content

UI Theming Practices

This project centralizes UI styling in demos/shared/theme/grid_builder_demo_theme.tres to keep the demos clear, readable, and consistent.

  • Use the shared theme by assigning it at a high-level HUD root (e.g., HUDRoot in demo scenes). Prefer inheritance over per-node overrides.
  • Prefer PanelContainer for backgrounds. It renders the theme panel automatically and avoids custom textures.
  • Avoid per-node theme_override_* except when absolutely necessary. If you must override, keep it local and minimal.

Scene patterns

  • Action Bar: PanelContainer → MarginContainer → HBoxContainer
  • Build Log: PanelContainer → MarginContainer → VBoxContainer with a header Label and RichTextLabel content.
  • Debug Info (top-left): PanelContainer → MarginContainer → VBoxContainer with Label rows.
  • Placeable Selection UI: PanelContainer → MarginContainer → TabContainer → grids of Button views.

Intent

  • Centralize appearance in the shared theme for maintainability.
  • Ensure legibility on various backgrounds via dark panels, light text, and consistent spacing.
  • Keep scene files simple—structure first, visuals from theme.

HUD layout specifications

  • Always-on HUD must not overlap other always-on HUD.
  • Treat persistent HUD (e.g., resource display, action bar, debug info, target informer) as reserved regions.
  • Use edge anchoring and consistent margins so panels don’t collide at different resolutions.
  • Keep the center of the screen visually clear for gameplay.
  • Prefer corners/edges: top-left (resources/debug), top-right (save/load), bottom-center (action bar), right edge (target informer).
  • Do not place persistent panels over the crosshair/character focus area.
  • Exceptions: major UI interactions (e.g., trading, shopping, main menu) may take center and can pause gameplay.
  • When active, they may cover gameplay; otherwise return to the clear-center layout.
  • Scaling & safety margins
  • Anchor to edges with 8–24 px theme margins; avoid absolute screen-center offsets for persistent HUD.
  • Test at multiple resolutions; verify via Runtime Scene Analyzer UI report for anchors/offsets.