---
name: godot-ui
description: Use when building user interfaces — Control nodes, themes, anchors, containers, and layout patterns
title: godot-ui
canonical_url: https://skilld.dev/gh/jame581/godotprompter/godot-ui
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/anchors-in-code.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/anchors-in-code.md), [references/focus-and-navigation.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/focus-and-navigation.md), [references/foldable-container.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/foldable-container.md), [references/signals.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/signals.md), [references/theme-system.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/theme-system.md), [references/ui-patterns.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/ui-patterns.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/godot-ui`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/godot-ui`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/godot-ui) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/godot-ui`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/godot-ui --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/godot-ui --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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`, `custom_minimum_size`, and a computed minimum (`get_combined_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 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; lookups check each ancestor `Control`/`Window` that has one, nearest first, and stop at the first parent that is neither (e.g. a `CanvasLayer` or `Node2D`)
- `focus_mode` — whether the node can receive keyboard/gamepad focus

Place UI nodes inside a `CanvasLayer` so they render on top of the 3D/2D world, unaffected by `Camera2D` transforms. Controls on the scene root's built-in canvas (layer 0) move with a `Camera2D`, because the camera sets that canvas's transform.

> ⚠️ **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](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.7.html).

---

## 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_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](https://github.com/godotengine/godot/pull/118623).

> **Godot 4.8+:** `TabBar` / `TabContainer.tab_sizing` (`TAB_SIZING_*`), `BoxContainer.reverse_sort`, `BaseButton.press()` (no visual-state change, no focus grab) and `SpinBox.format` (deprecates `prefix` / `suffix`).

---

## 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](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/anchors-in-code.md)

---

## 4. Theme System

A `Theme` resource centralizes fonts, colors, and `StyleBox`es. 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`, `corner_radius_*`, `border_width_*`); `StyleBoxTexture` for textures.

> See [references/theme-system.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/theme-system.md) for the full Theme resource creation walk-through, StyleBoxFlat properties, font overrides, theme inheritance rules, and per-node `theme_override_*` methods.

> **Godot 4.7+:** `GradientTexture2D`'s `Fill` enum gains `FILL_CONIC` — colors interpolated in a cone (angular) pattern; radial progress/cooldown indicators without a shader (C#: `FillEnum.Conic`).

> **Godot 4.8+:** Themes carry sounds: `Theme.set_sound()` items such as `BaseButton`'s `pressed_sound` / `hover_sound` replace per-button `AudioStreamPlayer` wiring and play on the `audio/buses/gui_theme_bus` bus. Recipe: [references/theme-system.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/theme-system.md#theme-sounds-godot-48).

---

## 5. Focus & Navigation

Focus modes (`FOCUS_NONE`, `FOCUS_CLICK`, `FOCUS_ALL`) gate keyboard/gamepad navigation. Wire chains with `focus_neighbor_top` / `_bottom` / `_left` / `_right`, or rely on automatic spatial detection. Call `grab_focus()` on the first interactive element when a menu opens.

> **Changed in Godot 4.8:** `gui/common/auto_focus_strategy` picks how automatic neighbors are inferred: `Legacy` (class default, the 4.7 behavior) or `Balloon` (closest and most aligned Control in the input direction). New 4.8 projects get `Balloon`, so automatic navigation can differ from an upgraded project; set neighbors explicitly where it matters.

> See [references/focus-and-navigation.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/focus-and-navigation.md) for focus mode details, `focus_neighbor` chain examples, gamepad/keyboard input handling, and grab_focus patterns.

---

## 6. Common UI Patterns

Three canonical scenes: a **main menu** (centered VBoxContainer with title + button list), a **settings screen with tabs** (`TabContainer` + child panels per category), and a **pause menu overlay** (full-rect `ColorRect` background + centered options panel, paused via `get_tree().paused = true`).

> See [references/ui-patterns.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/ui-patterns.md) for the full scene-tree fragments and GDScript wiring for each pattern.

> **Godot 4.8+:** `Label` / `RichTextLabel.resize_font_to_fit = true` picks the largest size between `minimum_font_size` and `maximum_font_size` that does not truncate (`get_rendered_font_size()` reads it), so no hand-rolled shrink loops.

> **Godot 4.7+:** `offset_transform_*` — visual-only UI-juice transform (shake/pulse) that never re-triggers container layout; `_get_cursor_shape(at_position)` — per-position cursor shapes; `PopupMenu` search bar (`search_bar_enabled`, fuzzy by default) plus `set_item_index()` for reordering; `TextureRect` `STRETCH_TILE` now tiles `AtlasTexture`s (only non-zero `margin` unsupported). Code: [references/ui-patterns.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/ui-patterns.md#godot-47-additions).

> ⚠️ **Changed in Godot 4.7:** `RichTextLabel.add_image()` / `update_image()` sizing was reworked — `width`/`height` are now `float`; `width_in_percent`/`height_in_percent` bools become `width_unit`/`height_unit`, taking the new `ImageUnit` enum (`IMAGE_UNIT_PIXEL`, `IMAGE_UNIT_PERCENT`, `IMAGE_UNIT_EM` — em scales with font size). `ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT` is renamed `UPDATE_WIDTH_UNIT`, breaking GDScript using the old name. See the [4.7 migration guide](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.7.html).

---

## 7. Signals

`Button.pressed` for clicks, `Control.gui_input` for raw events on a node, `Control.mouse_entered` / `mouse_exited` for hover. Connect in `_ready()` or via the Inspector's Node panel.

> See [references/signals.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/signals.md) for the complete signal catalog and signal-driven UI update patterns.

---

## 8. FoldableContainer (Godot 4.5+)

`FoldableContainer` is a built-in accordion `Container` added in Godot 4.5 — a toggle header plus collapsible children, replacing the old boilerplate of wiring a `Button` to show/hide a `VBoxContainer`. Set `title`, set `folded` for the initial state, add children normally, and listen to `folding_changed(is_folded)`.

Full GDScript + C# construction, the key-properties table, and the toggle signal: [references/foldable-container.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/godot-ui/references/foldable-container.md)

---

## 9. Stacked Label Effects (Godot 4.5+)

Godot 4.5 lets a `Label` layer several outlines and shadows through its `LabelSettings` resource — e.g. two outlines at different widths/colors plus a soft drop shadow. The stack lives on `LabelSettings` (configured per index), not on theme overrides, and `RichTextLabel` has no equivalent. Previously, multiple outline layers required duplicating and manually layering Label nodes.

```gdscript
# Stacked effects live on LabelSettings and are configured per index.
func apply_stacked_outlines(label: Label) -> void:
    var settings := LabelSettings.new()
    settings.outline_size = 4                  # base (inner) outline
    settings.outline_color = Color.BLACK

    settings.add_stacked_outline()             # stacked outline 0, drawn outside the base one
    settings.set_stacked_outline_size(0, 8)
    settings.set_stacked_outline_color(0, Color.GOLD)

    settings.add_stacked_shadow()              # stacked shadow 0
    settings.set_stacked_shadow_offset(0, Vector2(3, 3))
    settings.set_stacked_shadow_color(0, Color(0.0, 0.0, 0.0, 0.5))
    settings.set_stacked_shadow_outline_size(0, 2)

    label.label_settings = settings            # takes priority over theme properties
```

```csharp
public void ApplyStackedOutlines(Label label)
{
    var settings = new LabelSettings { OutlineSize = 4, OutlineColor = Colors.Black };

    settings.AddStackedOutline();
    settings.SetStackedOutlineSize(0, 8);
    settings.SetStackedOutlineColor(0, Colors.Gold);

    settings.AddStackedShadow();
    settings.SetStackedShadowOffset(0, new Vector2(3, 3));
    settings.SetStackedShadowColor(0, new Color(0f, 0f, 0f, 0.5f));
    settings.SetStackedShadowOutlineSize(0, 2);

    label.LabelSettings = settings;
}
```

`RichTextLabel` cannot stack effects; it takes one outline per text run through BBCode: `[outline_size=4][outline_color=#000000]Level Up![/outline_color][/outline_size]`.

> **Editor workflow:** Create a `LabelSettings` resource in the Label's **Label Settings** property and add entries to its stacked outline and stacked shadow lists. The per-index calls above cover dynamic scenarios.

---

## 10. Checklist

- [ ] Root UI `Control` has anchor preset **Full Rect** (or appropriate preset for the layout)
- [ ] All interactive widgets (`Button`, `LineEdit`, `Slider`) have `focus_mode = FOCUS_ALL`
- [ ] Decorative nodes (`Label`, `TextureRect`) have `focus_mode = FOCUS_NONE`
- [ ] Focus neighbours wired for non-linear layouts so gamepad navigation wraps correctly
- [ ] `grab_focus()` called on the first interactive widget in `_ready()` for each screen
- [ ] Pause menu root `Control` has `process_mode = PROCESS_MODE_ALWAYS`
- [ ] One `Theme` resource assigned at the screen root — not duplicated on every child
- [ ] `StyleBoxFlat` used instead of image assets for simple solid-colour panels
- [ ] `add_theme_*_override()` used for per-node overrides rather than assigning a whole new `Theme`
- [ ] Containers (`VBoxContainer`, `HBoxContainer`, etc.) used for layout instead of manual `position` values
- [ ] `custom_minimum_size` set on widgets that must not collapse to zero
- [ ] Slider and volume code uses `linear_to_db` / `db_to_linear` — not raw linear values mapped to audio bus
- [ ] Signals connected in `_ready()` (or via the editor); no polling of UI state in `_process`
- [ ] Tab order in `TabContainer` matches logical reading / navigation order
- [ ] Accordion-style collapsible panels use `FoldableContainer` instead of manual Button + VBoxContainer wiring (Godot 4.5+)
- [ ] Multiple outline/shadow layers on a `Label` use `LabelSettings` stacked outlines/shadows instead of duplicated nodes (Godot 4.5+)
