gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-ui-control
godot-ui-control
VerifiedGodot 4.7 Control-node API for menus and HUDs: anchors, Containers, Theme and StyleBox, focus neighbours and stretch settings, with a headless layout check. Use when Godot UI overlaps or drifts on resize, buttons ignore the gamepad, or an invisible panel swallows clicks. Not for engine-neutral UI rules (`game-ui-ux`; load both) or rebinding (`input-systems`).
Godot UI / Control nodes (4.x)
Lay out responsive UI with Control anchors and Container nodes, style it with a
Theme, make it navigable by keyboard and gamepad, and prove the layout holds at more
than one screen size. Targets Godot 4.7 (see Version notes). Design rules (what a good
HUD or menu needs) live in game-ui-ux; load both for engine UI work.
When to use
- HUDs, menus, inventories, dialog boxes or settings screens built from
Controlnodes; UI that must adapt to window size; theming; focus navigation for controller/keyboard.
When not to use: in-world Node2D/sprites → godot-nodes-scenes; UI tweens →
godot-animation; rebinding → input-systems; card hands and VN text boxes →
card-game / visual-novel.
Core workflow
-
Read the stretch settings first.
project.godot[display]holdswindow/size/viewport_width/viewport_height(base size, default 1152x648),window/stretch/mode(canvas_itemsis the usual choice for UI-heavy games) andwindow/stretch/aspect(expandlets UI use extra width or height). Layout bugs on other screens usually start here. -
Use
Controlnodes for UI, notNode2D, and put HUDs under aCanvasLayerso the game camera does not move them. -
Anchor top-level panels; let Containers place their children. Outside containers, set anchors with presets (
set_anchors_and_offsets_preset()). Inside aVBoxContainer,HBoxContainer,GridContainerorMarginContainer, the container owns position and size; steer it withsize_flags_*. In a.tscn, a Full Rect panel reads:[node name="PauseMenu" type="Control"] anchors_preset = 15 anchor_right = 1.0 anchor_bottom = 1.0 grow_horizontal = 2 grow_vertical = 2Keep whatever
layout_modeline Godot wrote; it records whether anchors or a parent container drive the node. -
Style with one
Theme. Set a project-wide theme withgui/theme/custom="res://ui/theme.tres"inproject.godot, or assignthemeon the top Control; children inherit it. Use per-nodeadd_theme_*_overrideonly for exceptions. -
Wire focus. Give the first button focus when a menu opens (
grab_focus()), keepfocus_mode = FOCUS_ALLon anything a gamepad must reach, and setfocus_neighbor_*only where the automatic geometry guess is wrong. -
Connect signals (
pressed,toggled,text_submitted,value_changed). -
Check before you finish.
- Run the layout test (Pattern 4) headless:
godot --headless --path . --script res://tests/test_ui_layout.gdand read the exit code. It flags controls pushed off-screen and menus with nothing focused, at each size. - Run the
godot-nodes-scenesskill'sscripts/check_godot_project.py <project-dir>if you edited.tscn/.tresfiles (themes, StyleBoxes, fonts). - For a picture, on a machine with a GPU (not
--headless), capture frames and look at them:godot --path . --resolution 2560x1080 --write-movie $OUT/menu.png --quit-after 3 --scene res://ui/main_menu.tscnwrites numbered PNGs next to that path. Repeat at 1280x720. - With no Godot binary (
godot,godot4or$GODOT_BIN), ask the user to run these and paste the output or screenshots. Ask the user to try the menu with a gamepad and report any button that cannot be reached.
- Run the layout test (Pattern 4) headless:
Patterns
1. Full Rect from code (anchors and offsets)
extends Control
func _ready() -> void:
# Setting only anchors (or `anchors_preset`) keeps the old offsets, so the rect
# would not snap to the preset. This moves anchors AND resets offsets.
set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
2. A menu from containers, with initial focus
extends VBoxContainer # children stack vertically, auto-sized
func _ready() -> void:
for child in get_children():
if child is Button:
child.pressed.connect(_on_button_pressed.bind(child.name))
# Give the first button focus so a gamepad can navigate immediately.
if get_child_count() > 0:
(get_child(0) as Control).grab_focus()
func _on_button_pressed(which: StringName) -> void:
match which:
"PlayButton": get_tree().change_scene_to_file("res://game.tscn")
"QuitButton": get_tree().quit()
3. One child takes the leftover space
func _ready() -> void:
$Label.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
$Spacer.size_flags_horizontal = Control.SIZE_EXPAND_FILL # grows to fill
4. Headless layout test at several sizes
# res://tests/test_ui_layout.gd
extends SceneTree
# The sizes the UI really gets. With stretch mode canvas_items and aspect "expand",
# a 2560x1080 window on a 1152x648 base gives the UI 1536x648, not 2560x1080.
const SIZES: Array[Vector2i] = [Vector2i(1152, 648), Vector2i(1536, 648), Vector2i(1152, 864)]
func _initialize() -> void:
var failed := 0
for size in SIZES:
var vp := SubViewport.new()
vp.size = size
root.add_child(vp)
var ui: Control = load("res://ui/main_menu.tscn").instantiate()
vp.add_child(ui)
await process_frame
await process_frame # containers re-sort a frame later
var screen := Rect2(Vector2.ZERO, Vector2(size))
for node in ui.find_children("*", "Control", true, false):
var c := node as Control
if c.is_visible_in_tree() and not screen.encloses(c.get_global_rect()):
failed += 1
push_error("%s off-screen at %s: %s" % [ui.get_path_to(c), size, c.get_global_rect()])
if vp.gui_get_focus_owner() == null:
failed += 1
push_error("nothing has focus at %s, so a gamepad cannot navigate" % size)
vp.free()
print("Results: %d failed" % failed)
quit(1 if failed > 0 else 0)
Children of a ScrollContainer are meant to extend past it; skip them (or check only the
container) when the menu scrolls.
Gotchas
- Mixing manual position with Containers. A container child cannot keep its own
position or anchors; the container overwrites them on every sort. To nudge, rotate or
scale one (a hover pop), set
offset_transform_enabled = trueand useoffset_transform_position/_rotation/_scale, which the container leaves alone. - Anchors vs offsets. Anchors are fractions of the parent; offsets are pixels from the anchored point. Positioning with anchors at 0 makes UI ignore window size.
- UI under a
Node2Ddoesn't theme, anchor or take focus correctly. Keep UI in aControlsubtree, under aCanvasLayerfor HUDs. - Gamepad does nothing → nothing has focus. Call
grab_focus()when the screen opens; plainControls default toFOCUS_NONE,FOCUS_CLICKis mouse-only, andgrab_focus()on aFOCUS_NONEcontrol only prints a warning. - Invisible full-rect panel swallows clicks → its
mouse_filterisSTOP. SetMOUSE_FILTER_IGNOREon decorative panels and HUD roots. - Looks right in the editor, cramped or off-screen on ultrawide or 4:3 → stretch
aspectiskeep(black bars) or the panel is anchored to a corner instead of the edge it should follow. Test the sizes the UI actually gets (Pattern 4). - Theme vs override. Per-node
add_theme_*_overridecalls beat the inheritedTheme; many of them defeat central theming and make restyling slow. rect_*properties are renamed. Godot 3'srect_size/rect_position/rect_min_sizeare nowsize/position/custom_minimum_size.
References
- Read
references/layout-and-theming.mdwhen you need the anchor/offset maths, every Container type, size-flag values, building a Theme and StyleBox in code, focus neighbour wiring, offset transforms, the built-inVirtualJoystick, or common Control signals.
Related skills
game-ui-uxfor engine-neutral rules: scaling, safe areas, focus flow, screen stack.godot-animationfor Tween-based UI transitions.godot-signals-groupsfor wiring UI events to game logic.input-systemsfor rebindable input and multi-device focus.card-game/visual-novelfor UI-heavy genre templates.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
Control.offset_transform_*and theVirtualJoysticknode are new in 4.7.- Default base size is 1152x648 and default stretch mode is
disabled, aspectkeep. --write-moviewith a.pngpath writes an image sequence;--resolutionrequests the window size.
Sources: Control @ 4.7.2-stable, ProjectSettings @ 4.7.2-stable, main.cpp @ 4.7.2-stable, Multiple resolutions, Godot 4.7 release.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |