Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

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-ui

About 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.

FeatureNode2DControl
Position modelWorld-space position (pixels from parent)Anchor + offset relative to parent rect
SizeNo intrinsic sizeHas size, minimum_size, custom_minimum_size
ThemeNoneInherits and overrides Theme resources
FocusNot applicableBuilt-in focus system (focus_mode, grab_focus())
Mouse eventsManual via _inputgui_input, mouse_entered, mouse_exited
Layout helpersNoneContainer 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 rect
  • offset_left, offset_top, offset_right, offset_bottom — pixel offsets applied after the anchor resolves
  • size_flags_horizontal, size_flags_vertical — how the node participates in Container layout
  • theme — a Theme resource; if null, walks up the tree to the nearest ancestor with one
  • focus_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_live changed type from DisplayServer.AccessibilityLiveMode to AccessibilityServer.AccessibilityLiveMode (LIVE_OFF = 0 default, LIVE_POLITE, LIVE_ASSERTIVE) — accessibility enums/APIs moved to the new AccessibilityServer singleton. GDScript-compatible; breaks C# binary/source compatibility (rebuild against the new enum). See the 4.7 migration guide.


2. Common Container Nodes

ContainerPurposeWhen to Use
VBoxContainerStacks children verticallyLists, option rows, vertical menus
HBoxContainerStacks children horizontallyToolbars, stat rows, horizontal nav
GridContainerArranges children in a fixed-column gridInventory grids, key-binding tables
MarginContainerAdds padding around a single childWrapping any node to give it breathing room
PanelContainerDraws a StyleBox background, then lays out childrenCard UI, dialog boxes, HUD panels
ScrollContainerMakes its single child scrollable; clips overflowLong lists, logs, scrollable settings
TabContainerStacks children as named tabs; shows one at a timeSettings screens, multi-section panels

Sizing tips:

  • Set size_flags_horizontal = SIZE_EXPAND_FILL on children that should fill available space.
  • Use custom_minimum_size to prevent a child from collapsing to zero.
  • MarginContainer reads margin from the theme property margin_*; override at runtime with add_theme_constant_override("margin_left", 16).

Godot 4.7+: custom_maximum_size (Vector2(-1, -1)) caps size per axis, prioritized over custom_minimum_size; propagate_maximum_size (default false) 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_front is 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:

PresetAnchor valuesUse case
Full RectL=0, T=0, R=1, B=1Overlay / fill parent — most common for root UI
CenterL=0.5, T=0.5, R=0.5, B=0.5Fixed-size widget centred in parent
Top LeftL=0, T=0, R=0, B=0Fixed-size widget pinned to top-left corner
Top RightL=1, T=0, R=1, B=0Fixed-size widget pinned to top-right corner
Bottom CenterL=0.5, T=1, R=0.5, B=1HUD 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

Read the complete source ↗