使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-ui-control开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
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.