Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-ui-control

godot-ui-control

Verified

Godot 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 Control nodes; 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

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

  2. Use Control nodes for UI, not Node2D, and put HUDs under a CanvasLayer so the game camera does not move them.

  3. 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 = 2
    

    Keep whatever layout_mode line Godot wrote; it records whether anchors or a parent container drive the node.

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

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

  6. Connect signals (pressed, toggled, text_submitted, value_changed).

  7. 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-scenes skill's scripts/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, godot4 or $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 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 = 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_filter is STOP. 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_*_override calls beat the inherited Theme; many of them defeat central theming and make restyling slow.
  • rect_* properties are renamed. Godot 3's rect_size/rect_position/rect_min_size are now size/position/custom_minimum_size.

References

  • Read references/layout-and-theming.md when 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-ux for engine-neutral rules: scaling, safe areas, focus flow, screen stack.
  • godot-animation for Tween-based UI transitions.
  • godot-signals-groups for wiring UI events to game logic.
  • input-systems for rebindable input and multi-device focus.
  • card-game / visual-novel for 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 the VirtualJoystick node are new in 4.7.
  • Default base size is 1152x648 and default stretch mode is disabled, aspect keep.
  • --write-movie with a .png path writes an image sequence; --resolution requests 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.

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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall