User interface
uiBuild game HUDs, menus, dialogs, and inventories from Godot Control nodes. Create themes and inspect layout issues.
Instructions
Build game UIs (HUDs, menus, dialogs, inventories) from Control nodes. 'build' creates a whole UI tree in one undoable call with anchor presets, size flags, text and theme overrides; 'menu_template' makes a ready main menu; 'theme' creates project-wide Theme resources with StyleBoxFlat styles; 'inspect' explains why a layout looks wrong. Put in-game HUDs under a CanvasLayer so they don't move with the camera.
Actions:
build: {spec: {type, name?, layout?, props?, text?, theme_overrides?, children: [...]} | [specs], parent?='.', scene?} build a UI subtree. layout = anchor preset: full_rect|center|top_left|top_right|bottom_left|bottom_right|top_wide|bottom_wide|left_wide|right_wide|center_top|center_bottom|center_left|center_right|hcenter_wide|vcenter_wide (+ layout_margin, resize: minsize|keep_size); only for nodes NOT inside a Container. Shortcuts per node: text, min_size [w,h], size_flags 'expand_fill'|'shrink_center' (one value = both axes)|{h,v}|[h,v], align/valign (left|center|right, begin|end for boxes), font_size, font_color, color (ColorRect color, Panel background, else text color), separation, margin (MarginContainer: n or [l,t,r,b]), panel/stylebox (StyleBox spec), texture, icon, placeholder, tooltip, unique (%Name access), groups, script, theme (res://theme.tres). Any other key is set as a property (value, max_value, columns, autowrap_mode: 'word_smart'... enum names are matched loosely) or a theme item. theme_overrides: {font_size, font_color, outline_size, separation, colors:{}, constants:{}, font_sizes:{}, fonts:{}, styles:{panel|normal|hover|pressed|fill|background: {bg_color, corner_radius, border_width, border_color, content_margin, shadow_size...}}}. Children given as plain strings become Labels. Returns every created node path (buttons flagged with their 'pressed' signal) and layout warnings. A zero-size Control scene root is stretched to full_rect automatically.
menu_template: {title?, subtitle?, buttons?=['Play','Options','Quit'], parent?='.', name?='MainMenu', background?: color | res://image, button_size?=[260,56], font_size?=24, title_size?=56, title_color?, spacing?=16, button_style?: {bg_color, corner_radius, ...} (hover/pressed derived) or {normal, hover, pressed}, theme?} centered main menu: full-rect Control > Background > CenterContainer > VBox(Title, Subtitle, Buttons); in an empty scene whose root is a plain Control (no name/theme given) it is built directly into the root. Buttons get unique names (%PlayButton), shared StyleBoxes and wrap-around focus neighbors. Returns {buttons: {label: path}} to connect 'pressed' signals.
layout: {path | paths, preset?, margin?=0, resize?: minsize|keep_width|keep_height|keep_size, size_flags?: 'expand_fill' (both axes) | {h, v} | [h, v], min_size?: [w,h]} apply an anchor preset like the editor's layout toolbar (undoable). Presets don't apply inside Containers: use size_flags/min_size there.
theme_override: {path | paths, overrides: {font_size: 32, font_color: '#ffd166', outline_size: 4, font_outline_color: 'black', separation: 8, styles: {panel: {bg_color: '#1d2330', corner_radius: 12}}, fonts: {font: 'res://f.ttf'}}} set per-node theme overrides; a null value removes one. Flat keys are matched to the node's theme items; unknown item names are rejected with the valid list.
theme: {path: res://ui/theme.tres, props: {default_font_size?, default_font?: res://font.ttf, colors?: {Button: {font_color: '#fff', font_hover_color: ...}}, constants?: {VBoxContainer: {separation: 12}}, font_sizes?: {Label: {font_size: 20}}, fonts?, icons?, styles?: {Button: {normal: {bg_color, corner_radius, content_margin: [16,8]}, hover: {bg_color}, pressed: {...}, focus: 'empty'}, Panel: {panel: {...}}}, type_variations?: {TitleLabel: 'Label'}}, replace?, assign_to?: node path | 'project'} create or extend a Theme. Type names must be Control classes or declared in type_variations first; item names are checked against what the class uses. Style states other than 'normal' inherit the normal dict, so hover only needs what changes. assign_to 'project' makes it the game-wide default (gui/theme/custom); a node path assigns it to that Control and its children. Use theme_type_variation on nodes to use a variation.
font: {path: res://fonts/x.ttf|.otf|.woff2, size?, assign_to?: node path | res://theme.tres | 'project', variation?: {embolden, slant, spacing, spacing_top, baseline_offset, opentype}, save_as?: res://fonts/bold.tres} load a font (imported as FontFile; a file just copied into the project is imported first), optionally as a FontVariation (saved with save_as), and assign it as a node override (+font_size), a theme's default_font or the project default font.
focus: {chain: [paths], axis?='vertical'|'horizontal', wrap?=true, mode?: all|click|none} link controls for keyboard/gamepad navigation in order; or {path, neighbors: {left, right, top, bottom, next, previous: path}, mode?} set individual neighbors. Call grab_focus() on the first one in _ready().
inspect: {path} layout debugging: rect, global rect, anchors/offsets, detected preset, size flags, min size, what positions it (container vs anchors), parent size, overrides, children rects and warnings (zero-size parents, overlays blocking clicks, collapsed wrapped labels...).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| axis | No | focus chain direction: vertical (default) or horizontal. | |
| mode | No | focus mode: all, click or none. | |
| name | No | Root node name for menu_template. | |
| path | No | Control node path (or res:// path for theme/font). | |
| size | No | Font size to apply with assign_to. | |
| spec | No | UI tree spec {type, name?, layout?, text?, props?, theme_overrides?, children?} or an array of them. | |
| wrap | No | focus chain wraps from last to first (default true). | |
| chain | No | Control paths to link for focus navigation, in order. | |
| paths | No | Several node paths. | |
| props | No | Theme contents for 'theme' (default_font_size, colors, styles, ...). | |
| scene | No | res:// scene to operate on; opened in the editor if needed. Defaults to the currently edited scene. | |
| theme | No | res:// Theme to apply to the built menu. | |
| title | No | menu_template title (default: project name). | |
| action | Yes | What to do. See the tool description for each action's parameters. | |
| margin | No | Margin in pixels for the anchor preset. | |
| parent | No | Parent node path for build/menu_template (default '.'). | |
| preset | No | Anchor preset name, e.g. full_rect, center, bottom_wide. | |
| resize | No | Preset resize mode: minsize (default), keep_width, keep_height, keep_size. | |
| buttons | No | menu_template button labels. | |
| replace | No | theme: start from an empty Theme instead of editing the existing file. | |
| save_as | No | res:// .tres path to save a FontVariation. | |
| spacing | No | menu_template space between buttons (default 16). | |
| min_size | No | [width, height] custom minimum size. | |
| subtitle | No | menu_template subtitle. | |
| assign_to | No | Node path, 'project', or res://theme.tres (font) to assign the theme/font to. | |
| font_size | No | menu_template button font size (default 24). | |
| neighbors | No | {left, right, top, bottom, next, previous}: node paths. | |
| overrides | No | Theme overrides {item: value} or grouped {colors, constants, font_sizes, fonts, styles, icons}. | |
| title_gap | No | menu_template space between title and buttons (default 24). | |
| variation | No | FontVariation settings: embolden, slant, spacing, ... | |
| background | No | menu_template background color '#101522' or res:// image. | |
| size_flags | No | 'expand_fill', 'shrink_center', ['expand','fill'] or {h, v}. | |
| title_size | No | menu_template title font size (default 56). | |
| button_size | No | menu_template button [width, height] (default [260, 56]). | |
| title_color | No | menu_template title color, e.g. '#ffd166'. | |
| button_style | No | menu_template button StyleBox spec. |