godot-ui
Use when building user interfaces — Control nodes, themes, anchors, containers, and layout patterns
jame581 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add jame581/GodotPrompter --skill godot-uiAbout this skill
name: godot-ui description: Use when building user interfaces — Control nodes, themes, anchors, containers, and layout patterns
Godot UI — Control Nodes, Themes & Layout
All examples target Godot 4.3+ with no deprecated APIs; GDScript first, then C#.
Related skills: responsive-ui for multi-resolution scaling, hud-system for in-game HUD patterns, dialogue-system for dialogue UI presentation, tween-animation for UI transition and animation effects.
1. Control Node Hierarchy
How Control Differs from Node2D
Control is the base class for all UI nodes — it lives in a separate scene-tree branch from Node2D/Node3D with a fundamentally different layout model.
| Feature | Node2D | Control |
|---|---|---|
| Position model | World-space position (pixels from parent) | Anchor + offset relative to parent rect |
| Size | No intrinsic size | Has size, minimum_size, custom_minimum_size |
| Theme | None | Inherits and overrides Theme resources |
| Focus | Not applicable | Built-in focus system (focus_mode, grab_focus()) |
| Mouse events | Manual via _input | gui_input, mouse_entered, mouse_exited |
| Layout helpers | None | Container subclasses auto-arrange children |
Control as Base Class
Every UI widget (Button, Label, LineEdit, etc.) extends Control. Key properties defined on Control itself:
anchor_left,anchor_top,anchor_right,anchor_bottom— fractional values (0.0–1.0) relative to the parent rectoffset_left,offset_top,offset_right,offset_bottom— pixel offsets applied after the anchor resolvessize_flags_horizontal,size_flags_vertical— how the node participates inContainerlayouttheme— aThemeresource; ifnull, walks up the tree to the nearest ancestor with onefocus_mode— whether the node can receive keyboard/gamepad focus
Place UI nodes inside a CanvasLayer (or directly under the scene root's built-in canvas) so they render on top of the 3D/2D world, unaffected by Camera transforms.
⚠️ Changed in Godot 4.7:
Control.accessibility_livechanged type fromDisplayServer.AccessibilityLiveModetoAccessibilityServer.AccessibilityLiveMode(LIVE_OFF = 0default,LIVE_POLITE,LIVE_ASSERTIVE) — accessibility enums/APIs moved to the newAccessibilityServersingleton. GDScript-compatible; breaks C# binary/source compatibility (rebuild against the new enum). See the 4.7 migration guide.
2. Common Container Nodes
| Container | Purpose | When to Use |
|---|---|---|
VBoxContainer | Stacks children vertically | Lists, option rows, vertical menus |
HBoxContainer | Stacks children horizontally | Toolbars, stat rows, horizontal nav |
GridContainer | Arranges children in a fixed-column grid | Inventory grids, key-binding tables |
MarginContainer | Adds padding around a single child | Wrapping any node to give it breathing room |
PanelContainer | Draws a StyleBox background, then lays out children | Card UI, dialog boxes, HUD panels |
ScrollContainer | Makes its single child scrollable; clips overflow | Long lists, logs, scrollable settings |
TabContainer | Stacks children as named tabs; shows one at a time | Settings screens, multi-section panels |
Sizing tips:
- Set
size_flags_horizontal = SIZE_EXPAND_FILLon children that should fill available space. - Use
custom_minimum_sizeto prevent a child from collapsing to zero. MarginContainerreads margin from the theme propertymargin_*; override at runtime withadd_theme_constant_override("margin_left", 16).
Godot 4.7+:
custom_maximum_size(Vector2(-1, -1)) caps size per axis, prioritized overcustom_minimum_size;propagate_maximum_size(defaultfalse) makes a parent's maximum constrain its Control children;_get_maximum_size()computes maximums from code.
⚠️ Changed in Godot 4.7:
TabContainer.all_tabs_in_frontis deprecated — it does nothing now, since tabs are always in front. Remove code that sets it. See GH-118623.
3. Anchors & Margins
How Anchor Presets Work
An anchor is a point on the parent rect expressed as a fraction (0 = top/left edge, 1 = bottom/right edge). Godot resolves the final pixel position of each edge as:
final_left = parent_width * anchor_left + offset_left
final_top = parent_height * anchor_top + offset_top
final_right = parent_width * anchor_right + offset_right
final_bottom = parent_height * anchor_bottom + offset_bottom
The editor exposes built-in presets:
| Preset | Anchor values | Use case |
|---|---|---|
| Full Rect | L=0, T=0, R=1, B=1 | Overlay / fill parent — most common for root UI |
| Center | L=0.5, T=0.5, R=0.5, B=0.5 | Fixed-size widget centred in parent |
| Top Left | L=0, T=0, R=0, B=0 | Fixed-size widget pinned to top-left corner |
| Top Right | L=1, T=0, R=1, B=0 | Fixed-size widget pinned to top-right corner |
| Bottom Center | L=0.5, T=1, R=0.5, B=1 | HUD element anchored to bottom centre |
Setting Anchors in Code
Anchors resolve as parent_size * anchor + offset per edge, so setting them by hand means setting eight properties. set_anchors_and_offsets_preset(Control.PRESET_*) does it in one call — use that, then adjust offset_* for margins (negative on right/bottom).
The anchor-vs-offset rule (keep offsets at 0 and let anchors do the work) plus full GDScript + C# examples — full-rect fill, top-right HUD with 16 px margins, and a custom half-screen side panel: references/anchors-in-code.md
4. Theme System
A Theme resource centralizes fonts, colors, and StyleBoxes. Apply at the root and let inheritance do the work; use theme_override_* only for one-off tweaks. StyleBoxFlat covers most flat-design needs (bg_color, border_color