Game UI/HUD Patterns (Godot 4)

For responsive layouts that adapt to resolution changes, use Container nodes (HBoxContainer, VBoxContainer, MarginContainer) rather than hardcoding pixel offsets.

Theme Resources

Create a shared Theme resource for consistent styling. Apply at the root Control node — all children inherit automatically. Theme defines fonts, colors, styleboxes, and spacing for every Control type.

HUD Elements

Key HUD components:

• Health/Mana bars: TextureProgressBar for polished, ProgressBar + theme overrides for quick prototyping. Use smooth lerp to target value. Layered bars for damage-flash effect.
• Minimap: SubViewportContainer → SubViewport → Camera2D following player at low zoom.
• Buff icons: TextureRect + timer overlay with radial cooldown shader progress.
• XP bar: ProgressBar anchored bottom center showing level + current/max XP.
• Currency: Animated counter that smoothly interpolates displayed value toward target.

See references/gdscript-implementations.md for full implementations of all HUD components.

Inventory UI

Grid-Based Inventory

Use GridContainer (columns = 8) to lay out inventory slots. Each slot is a PanelContainer with icon and stack count label.

Drag and drop: Godot's built-in _get_drag_data, _can_drop_data, _drop_data on Control nodes. Always set set_drag_preview() with a visual clone of the item.

Tooltip: Autoload on a high CanvasLayer (layer = 30). Always clamp tooltip position to viewport bounds.

Equipment Slots

Named slots (not a grid). Map body parts to slot containers.

Equipment slots reuse the drag-and-drop interface but add type checking in _can_drop_data:

return data["item"].get("equip_slot", "") == slot_type

Item comparison: On hover over equippable, show side-by-side stats with color-coded diffs (green = upgrade, red = downgrade).

See references/gdscript-implementations.md for inventory grid, slot, and tooltip implementations.

Dialog System

RichTextLabel with BBCode

Key Dialog Patterns

• Typewriter effect: Use visible_characters on RichTextLabel, incrementing at characters_per_second. Emit line_finished signal when complete. Allow player to skip via ui_accept.
• Portrait display: TextureRect that swaps texture based on speaker + emotion.
• Branching dialog trees: Store in external JSON files — separates content from logic, enables localization. Dialog manager autoload processes the tree and handles conditional choices.

See references/gdscript-implementations.md for typewriter and dialog manager implementations.

Damage Numbers

Spawn Label nodes at the damage location on a dedicated CanvasLayer (layer = 15), animate upward with a tween, then free. Use a spawner autoload for world→screen position conversion.

Damage type color reference:

Crits: larger font (28px vs 18px), "!" suffix, scale pop animation.

See references/gdscript-implementations.md for full damage number and spawner implementations.

Menus

Main Menu

VBoxContainer of Buttons inside CenterContainer. Disable Continue button if no save exists.

Pause Menu

Set get_tree().paused = true. The pause menu's process_mode must be PROCESS_MODE_WHEN_PAUSED to still receive input. Toggle visibility on pause action.

Settings Menu

Organize into tabs using TabContainer:

• Audio: HSlider per bus → AudioServer.set_bus_volume_db() with linear_to_db()
• Video: Fullscreen toggle, VSync toggle, resolution OptionButton → DisplayServer
• Controls: Key rebinding using InputMap — list actions, capture new InputEventKey, call action_erase_events + action_add_event

Screen Transitions

ColorRect with AnimationPlayer on persistent CanvasLayer (layer = 100). Autoload: change_scene(path) plays fade_out → changes scene → plays fade_in.

See references/gdscript-implementations.md for settings and transition implementations.

Multiplayer UI

Nameplates

Label on CanvasLayer that follows entity. Convert world position to screen space using camera offset. Color by relationship:

Party Frames

VBoxContainer of compact HBoxContainer rows (portrait + name + HP bar + MP bar). Update via signals from player data changes.

Trade Window

Two-panel layout. Both players must confirm before trade executes. Reset confirmation state when either side changes their offer.

Chat Input

LineEdit + OptionButton for channels. Hidden until chat_open action. Support /p and /w prefix commands for party/whisper.

Lobby Browser

VBoxContainer or ItemList of server rows. Async refresh, click-to-select, join button.

See references/gdscript-implementations.md for nameplate, trade window, and chat implementations.

Godot MCP Integration

UI Scene Scaffolding Workflows

HUD scene workflow:

1. scene_create — root: CanvasLayer (layer = 10)
2. Add Control (HUD, full rect anchor)
3. Add TextureProgressBar (HealthBar) anchored top-left: offset_left=10, offset_top=10, offset_right=210, offset_bottom=30
4. Add TextureProgressBar (ManaBar) below
5. Add HBoxContainer (BuffContainer) below bars
6. Add SubViewportContainer (Minimap) anchored top-right
7. Add SubViewport → Camera2D inside minimap container
8. scene_save

Inventory scene workflow:

1. scene_create — root: CanvasLayer (layer = 20)
2. PanelContainer centered (anchor_left=0.5, anchor_right=0.5, anchor_top=0.5, anchor_bottom=0.5)
3. MarginContainer → VBoxContainer → Label + GridContainer (columns = 8)
4. scene_save

CanvasLayer Ordering

Verification workflow: scene_create → editor_run → check editor_debug_output for layout warnings → editor_stop → adjust → repeat.

Anti-Patterns

Cross-References