How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-ui-controlBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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]holds
window/size/viewport_width/viewport_height (base size, default 1152x648), window/stretch/mode (canvas_items is the usual choice for UI-heavy games) and window/stretch/aspect (expand lets UI use extra width or height). Layout bugs on other screens usually start here.
- Use `Control` nodes for UI, not
Node2D, 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 a VBoxContainer, HBoxContainer, GridContainer or MarginContainer, the container owns position and size; steer it with size_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_mode line Godot wrote; it records whether anchors or a parent container drive the node.
- Style with one `Theme`. Set a project-wide theme with
gui/theme/custom="res://ui/theme.tres"
in project.godot, or assign theme on the top Control; children inherit it. Use per-node add_theme_*_override only for exceptions.
- Wire focus. Give the first button focus when a menu opens (
grab_focus()), keep
focus_mode = FOCUS_ALL on anything a gamepad must reach, and set focus_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.gd and 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/.tres files (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.tscn writes 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.
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 fill4. 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 = true and use offset_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 `Node2D` doesn't theme, anchor or take focus correctly. Keep UI in a
Control subtree, under a CanvasLayer for HUDs.
- Gamepad does nothing → nothing has focus. Call
grab_focus()when the screen opens;
plain Controls default to FOCUS_NONE, FOCUS_CLICK is mouse-only, and grab_focus() on a FOCUS_NONE control only prints a warning.
- Invisible full-rect panel swallows clicks → its
mouse_filterisSTOP. Set
MOUSE_FILTER_IGNORE on decorative panels and HUD roots.
- Looks right in the editor, cramped or off-screen on ultrawide or 4:3 → stretch
aspect is keep (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'srectsize`/`rectposition/rectminsize`
are now size/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-in VirtualJoystick, 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.