Godot UI (UI developer)
Target: Godot 4.7.2.stable, macOS Apple Silicon.
Expert level here means one layout proven, by numbers and images, from a 1080x2400 phone in portrait
to a 3840x2160 monitor, in every language, with mouse, pad and screen reader. The stretch transform
scales, containers place, one Theme built in code styles, and nothing ships before a layout matrix
and a contact sheet say so. If a sibling skill named here is missing from your available skills,
load it with skill_get (Scenario MCP) or ask the user to install it
(https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas and flag
the gap.
REQUIRED BACKGROUND: scenario-godot-expert (channels, review loop, 6.3 traps).
Stance (the expert delta)
- Pick the base size for the extremes, not for 1080p. A square base (720x720) with
canvas_items + expand and Handheld Orientation sensor gives one scale for portrait and
landscape (docs, Multiple resolutions). Measured: 1.5x on a 1080x2400 phone in both orientations,
3x on 4K. A 1152x648 base gives a 0.9375x canvas on the same phone and three undersized buttons
[added, measured]. Godotneers' 1920x1080 base (1_OFJLyqlXI) suits desktop only.
- Containers place, anchors pin. Sizing is a negotiation: the minimum size is the floor, Expand
claims leftover space, Fill uses it (Godotneers 1_OFJLyqlXI 00:35:00, Karto 5Hog6a0EYa0
00:14:39). Measured in a 400 px HBox: Expand without Fill leaves the claimed space empty (sibling
pushed to x 380); Fill or a stretch ratio without Expand changes nothing; ratios are summed, 1:3
gives 96 and 290 of 386 px (Karto 00:15:45). Anchor presets are relative to the parent;
set_anchors_preset() alone keeps the old offsets (a 50x50 child stays 50x50 on FULL_RECT), so
use set_anchors_and_offsets_preset() (Karto 00:05:24, measured). A corner element also needs
its grow direction, or longer text grows off screen [added, measured 1462 px wide in a 1152 px
canvas].
- The look lives in one Theme resource built in code, with type variations instead of per-node
overrides (docs, Theme type variations). StyleBoxes are shared Resources: an override reused on
two nodes changes both (Karto 00:19:00).
- Focus is explicit. Nothing has focus at scene start, so
ui_down does nothing until
something calls grab_focus() (docs, Controller navigation; measured). Keep a menu stack that
disables covered panels and returns focus to the opener (Mostly Mad Productions ecJZipjUj6k
00:08:57).
- The current selection is the highest-contrast element on screen, body text comes first, two
or three fonts at most, and the outro is faster than the intro (Rawb Herb, GodotCon 2025,
sjmAD1ZLBcE 00:31:42, 00:21:34, 00:55:38).
- Text is keys, never literals. Named placeholders with
format(), tr_n() for plurals,
context for identical English, auto translate disabled on dynamic text (docs, Internationalizing
games). Fonts get fallbacks, not remaps.
- HUD is passive and signal-driven. Its root and wrappers ignore the mouse; values change on
signals, not in
_process (consensus of 1_OFJLyqlXI, Yuw7CK5H8eA, f90ieBOoIYQ). A new string
reshapes (200 labels: 1.1 to 1.5 ms of CPU per frame); assigning the identical string is an
early-out, so the cost is the changed text, not the assignment [added, measured]. In-place array
mutations never call a setter (0 calls after append, 1 after reassigning), so state arrays emit
their own signal (NoBSGodot Yuw7CK5H8eA 00:05:06, measured).
- Verify at device sizes headless, then look. Headless,
root.size takes any size and applies
the project stretch, so a layout matrix runs in seconds; a windowed capture then renders each
device with the notch drawn in [added, measured].
Establish first
| Input |
Changes |
Default if nobody says |
| Platforms and orientations |
base size, orientation, touch target size |
phone portrait + landscape, desktop to 4K: base 720x720, canvas_items, expand, orientation 6 (sensor) |
| Art style |
stretch mode and scale mode |
vector or high-res: canvas_items + fractional; pixel art: viewport, base 640x360, integer, Exclusive Fullscreen (docs) |
| Input devices |
focus work, rebind screen, touch sizes |
mouse, keyboard, pad, touch |
| Languages |
fonts, RTL, Text Server Data on export |
en plus one long (de), one CJK (ja), one RTL (ar) for tests |
| Accessibility bar |
screen reader, UI scale slider, contrast |
WCAG 4.5:1 body text, UI scale 0.75 to 2.0 via content_scale_factor |
| Renderer |
upscaler choice in settings |
Forward+ (Jolt kept); Compatibility forces bilinear 3D scaling |
Workflow
1. Project settings. Write the stretch keys explicitly: a hand-written project.godot gets
disabled and keep (deltas). gd_env.set_project_setting for
display/window/size/viewport_width/height, stretch/mode, stretch/aspect,
handheld/orientation, gui/theme/custom. Check that 3d/physics_engine="Jolt Physics" and the
renderer survived. GATE: gd_ui.stretch_math(window, base, ...) for each target gives the expected
logical size and scale (port matches the engine on 224 cases, origin and scale included).
2. Theme in code. ui_theme.gd build(overrides) returns a
Theme: Button states with a thick accent focus box, Label, panels, sliders, tabs, ProgressBar,
variations TitleLabel, HudLabel, HudValue, PrimaryButton, HudPanel, HealthBar, TrailBar. Save it as
.tres, set the default font to a SystemFont with CJK and Arabic fallbacks, two or three fonts at
most. Text drawn at many scales (HUD numerals at 3x) gets MSDF:
gui/theme/default_font_multichannel_signed_distance_field or the font's
multichannel_signed_distance_field, both false by default (Karto 5Hog6a0EYa0 00:20:50, measured).
Default Theme Scale is read once: a runtime set changed nothing (measured). In the editor a Theme
edit needs a scene reload to repaint (Godotneers 00:22:10) and an override is inactive until its
checkbox is ticked (Karto 00:17:25); in code only add_theme_*_override counts, and runtime Theme
edits propagate at once (measured). GATE: contrast_report() body pairs >= 4.5:1 (worst measured
4.37 is the disabled state, allowed); check_variations() finds no misspelt variation.
3. Scenes in code. Root Control full rect, a safe_area.gd
MarginContainer, then containers. Buttons 88 logical tall at a 720 base (132 px on a phone at 1.5x).
Settings rows in ScrollContainers inside a TabContainer. HUD on a CanvasLayer, root
MOUSE_FILTER_IGNORE, AspectRatioContainer for the minimap; a round minimap or portrait frame is a
clip_children mask (Clip Only on a rounded Panel), but a child with another z_index escapes it
(GDQuest W4j4tnQLcTA 00:03:47, measured), so keep masked content at z 0 or use a SubViewport.
Toggles read "On"/"Off" as text (CoffeeCrow 9H_fN4OxyIE 00:08:11). safe_area.gd recomputes on
size_changed (top margin 104 at 1.5x, 82 at 2x, measured). examples/build_g7.gd builds the whole
G7 set. GATE: ui_audit.gd audit_tree() returns no
hud_blocks_input, icon_keep_size, grows_offscreen_*, no_accessible_name,
shared_stylebox_override, unknown_variation.
4. Layout matrix headless.
gd_ui.layout_matrix(P, scene, targets, min_touch_px=..., safe_insets=..., locale=..., pseudo=True)
for 8 targets (phone portrait and landscape, 4:3 tablet, 1366x768, 1080p, 21:9, 4K, 800x600). GATE:
zero offscreen, outside_safe, small_target, text (clipped or overflowing), overlap and collapsed
issues for each scene, in en, de and pseudolocalized at 0.4 expansion.
5. Capture matrix windowed, then look.
gd_ui.capture_matrix(P, scene, targets, safe_insets=...) renders each target at its physical size
with black bars and red notch bands, and builds a contact sheet. Open the sheet. GATE:
image_checks flags none; by eye: selection visible, no clipped glyphs (CJK, Arabic), notch bands
over background only, bars and frames intact. Never capture through an embedded Window with
content_scale_*: it draws unscaled (P13, measured).
6. Focus and input. gd_ui.focus_walk(P, scene, steps) pushes ui_* actions through
push_input and records the focus owner; ui_focus.graph() lists unreachable focusables. Menu
stack: open, cancel, focus back on the opener. GATE: every focusable reachable from the default;
first key press from no focus lands on the default; covered panels unreachable.
7. Rebinding. ui_rebind.gd: accept (no echo, no Escape,
sticks over 0.5), normalize (physical keycode, device -1, axis sign), report conflicts, swap or
refuse, save as ConfigFile, reset from project settings. Show the key with
DisplayServer.keyboard_get_label_from_physical() (windowed only): on a French layout physical Q
reads "A" (measured). Add pad buttons yourself: in 4.7.2 ui_accept and ui_cancel hold keys only
(Enter, Kp Enter, Space; Escape), so add Joypad Button 0 and 1 (Mostly Mad ecJZipjUj6k 00:12:00,
measured). GATE: binding matches on keyboard and on any pad after a save and load round trip.
8. Localization. CSV with a ?plural column, gd_ui.check_csv offline, --import, then
gd_ui.register_translations. Run en, fr, de, ja, ar and pseudolocalization; expansion_ratio
defaults to 0.0, so set 0.3 to 0.4 and call reload_pseudolocalization() (measured).
--language fr is the non-persistent test. Animated text is a RichTextEffect: bbcode var plus
_process_custom_fx(char_fx), options from char_fx.env (Cashew OldDew KMqYeRae6rM 00:14:01;
measured [lift px=6] read 6.0), installed with install_effect(). GATE: no missing keys per
locale; Arabic mirrors (anchors and HBox order); plurals right in en and fr; layout matrix clean.
9. Settings and cost. ui_settings.gd autoload applies
window mode, vsync, render scale and upscaler, quality, UI scale, bus volumes, locale; saves and
reloads. GATE: save and load round trip; ui_scale 1.5 turns a 1280x720 canvas into 853x480.
Numbers
| Value |
Relative to |
Source |
Base 720x720, canvas_items, expand, orientation sensor |
phone portrait and landscape plus desktop |
docs, Multiple resolutions |
| Scale 1.5 on 1080x2400 and 2400x1080, 3.0 on 3840x2160, 1.0672 on 1366x768 |
base 720x720 |
measured [added] |
Base 720x1280 on a 2400x1080 phone: expand 2844x1280 at 0.844x (UI shrinks), keep_width 897 px side bars; keep_height on 1080x2400: 240 px bars |
why a square base beats an aspect choice |
measured [added] |
Pixel art 640x360 viewport integer; viewport at fractional 1.0672 (1366x768) resamples and blurs text |
720p to 4K |
docs, measured |
| Default Theme Scale 2.0 to 3.0 for a 4K base, 1.5 to 2.0 mobile 1080p base; read once (runtime set: no change) |
base size |
docs, measured |
| Touch target 126 px phone, 96 px tablet (48 dp at about 420 and 320 dpi) |
physical pixels |
[added] |
| Button 88 logical at base 720 |
132 px on a phone |
[added, measured] |
| WCAG 4.5:1 body, 3:1 large text |
text vs its background |
WCAG 2 [added] |
| Damage trail: one-shot timer 0.4 s, restarted per hit; heal instant |
health change |
DashNothing f90ieBOoIYQ 00:01:26 |
| Text Server Data ~4 MB |
export size, for no-space scripts |
docs |
| 200 labels: 1.1 to 1.5 ms new text every frame, 0.17 to 0.23 ms for 10 per frame, under 0.1 ms same text (as idle) |
CPU per frame, headless M5 Max |
measured [added] |
Quality gates
Measurable: test_ui_live.py U1 to U15 green (compile, stretch parity, CSV, layout matrix, capture,
focus, rebind, HUD, localization, engine facts, theme and settings, cost, embedded Window, round-2
layout and theme facts, clip mask and text effect); zero issues in the layout matrix for each scene
and locale; audit clean; contrast >= 4.5:1 on body pairs; save and load round trips. Visual: one
contact sheet per scene and locale (menu, HUD, settings ja, menu ar, settings pseudo), opened: focus
visible, glyphs complete, nothing under the notch, letterbox where expected, selection still visible
in grayscale (Rawb Herb).
Common mistakes
| Mistake |
What it looks like |
Fix |
| 1920x1080 or 1152x648 base for a phone game |
tiny buttons in portrait (scale 0.9375 at 1080x2400) |
square base 720x720 + expand |
| Stretch keys left out of an agent-written project.godot |
UI fixed size, black space on 4K |
write mode and aspect explicitly |
| Full-rect Control with default STOP filter over the game |
clicks never reach _unhandled_input (0 of 1) |
MOUSE_FILTER_IGNORE on HUD roots and wrappers |
| Corner preset without grow direction |
score text runs off the right edge |
grow_horizontal = GROW_DIRECTION_BEGIN |
No grab_focus() on open |
pad does nothing |
menu stack grabs the default on the first nav event |
TextureRect left on KEEP_SIZE in a container |
a 512 px icon makes a 64 px row 614x512; IGNORE_SIZE with no minimum collapses to width 0 |
EXPAND_FIT_WIDTH_PROPORTIONAL (64x64 measured) or ignore size + min size, Stretch Keep Aspect Centered (Godotneers 1_OFJLyqlXI 00:10:28) |
| OptionButton items as literal English |
Japanese screen shows "Windowed" |
items as keys (OPT_WINDOWED) |
| Tabs left at theme default |
tabs too small to touch |
tab styleboxes with content margins; the matrix checks the TabBar |
| Stored binding with device 0 from a synthesized event |
pad 2 or the real keyboard (device 16) do not trigger |
normalize to device -1 |
| Pseudolocalization on, expansion untouched or no reload |
no padding (default ratio 0.0) |
set expansion_ratio, TranslationServer.reload_pseudolocalization() |
| POT generation trusted for custom nodes in old tutorials |
strings missing (4.2 bug) |
fixed in 4.3 (Cashew OldDew v0tJPsNNOM8 00:08:00, not rerun); CSV keys avoid POT |
| Locale Test set in project settings |
ships in French |
clear it; use --language fr |
Hiding a container child with visible = false for an effect |
siblings jump (relayout) |
modulate.a = 0 or offset_transform_scale (MrElipteach pK2vI2-jCH4 00:02:54) |
| Expecting a focus ring after a mouse click |
ring only on the next key or pad press |
by design: gui/common/show_focus_state_on_pointer_event 1 (text inputs only) |
Handoffs
- In: state autoloads and signals (scenario-godot-architecture), input actions and values
(scenario-godot-gameplay), bus names Master, Music, SFX (scenario-godot-audio), icons, panels,
fonts (scenario-* skills; nine-patch margins set in code).
- Out: render scale and upscaler contract (scenario-godot-rendering-lighting); Text Server Data,
real-device safe area and touch (scenario-godot-performance-export); intro and outro tracks,
offset_transform motion (scenario-godot-animation); test_ui_live.py for CI
(scenario-godot-pipeline-automation).
Godot 4.7 notes
offset_transform_* (4.7) moves container children without relayout;
offset_transform_visual_only defaults to true, so clicks hit the layout rect (measured).
pivot_offset_ratio (4.7) for center pivots; grab_focus(hide_focus) (4.6).
AccessibilityServer (4.7), accessibility_name, FOCUS_ACCESSIBILITY (RichTextLabel default);
accessibility_support 0 Auto runs only with an assistive app active.
auto_translate_mode replaced auto_translate; FoldableContainer (4.5), VirtualJoystick,
PopupMenu.allow_search (4.7); [img] takes width_unit/height_unit. Upscalers: FSR2=2,
MetalFX spatial=3, temporal=4.
push_input(event, true) takes logical coordinates. Godot 3 names (rect_size,
add_color_override, margin_*, stretch 2d, process_custom_fx) are gone.
References
references/procedures.md: P1 to P15 with full code paths, live test
ids and results.
references/expert-notes.md: what each source teaches, with
timestamps.
references/critique.md: the rubric for judging a UI build and its
captures.
references/gui-paths.md: the same steps through the editor for a
computer-use agent.
references/sources.md: every source, credentials, URLs, best
timestamps.
scripts/gd_ui.py, scripts/agentkit/ui/*.gd,
scripts/agentkit/ui/examples/build_g7.gd.
1---2name: scenario-godot-ui3description: "Use when building or fixing game UI in Godot 4.7: main menu, settings screen, HUD (health bar, ammo, minimap frame), Control layout, containers, anchors, themes in code, 'UI scales wrong on phones', 'text too small on 4K', notch or safe area, stretch mode and aspect, gamepad or keyboard menu navigation, focus lost, input rebinding screen, localization (CSV, PO, tr_n plurals, Arabic RTL, CJK fonts, pseudolocalization), screen reader accessibility, UI scale slider, or clicks not reaching the game."4license: MIT5metadata:6 source: https://skillmd.com/skills/scenario-labs/scenario-godot-ui7---89# Godot UI (UI developer)1011Target: Godot 4.7.2.stable, macOS Apple Silicon.1213Expert level here means one layout proven, by numbers and images, from a 1080x2400 phone in portrait14to a 3840x2160 monitor, in every language, with mouse, pad and screen reader. The stretch transform15scales, containers place, one Theme built in code styles, and nothing ships before a layout matrix16and a contact sheet say so. If a sibling skill named here is missing from your available skills,17load it with `skill_get` (Scenario MCP) or ask the user to install it18(https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas and flag19the gap.2021**REQUIRED BACKGROUND:** scenario-godot-expert (channels, review loop, 6.3 traps).2223## Stance (the expert delta)24251. **Pick the base size for the extremes, not for 1080p.** A square base (720x720) with26 `canvas_items` + `expand` and Handheld Orientation `sensor` gives one scale for portrait and27 landscape (docs, Multiple resolutions). Measured: 1.5x on a 1080x2400 phone in both orientations,28 3x on 4K. A 1152x648 base gives a 0.9375x canvas on the same phone and three undersized buttons29 [added, measured]. Godotneers' 1920x1080 base (1_OFJLyqlXI) suits desktop only.302. **Containers place, anchors pin.** Sizing is a negotiation: the minimum size is the floor, Expand31 claims leftover space, Fill uses it (Godotneers 1_OFJLyqlXI 00:35:00, Karto 5Hog6a0EYa032 00:14:39). Measured in a 400 px HBox: Expand without Fill leaves the claimed space empty (sibling33 pushed to x 380); Fill or a stretch ratio without Expand changes nothing; ratios are summed, 1:334 gives 96 and 290 of 386 px (Karto 00:15:45). Anchor presets are relative to the parent;35 `set_anchors_preset()` alone keeps the old offsets (a 50x50 child stays 50x50 on FULL_RECT), so36 use `set_anchors_and_offsets_preset()` (Karto 00:05:24, measured). A corner element also needs37 its grow direction, or longer text grows off screen [added, measured 1462 px wide in a 1152 px38 canvas].393. **The look lives in one Theme resource built in code,** with type variations instead of per-node40 overrides (docs, Theme type variations). StyleBoxes are shared Resources: an override reused on41 two nodes changes both (Karto 00:19:00).424. **Focus is explicit.** Nothing has focus at scene start, so `ui_down` does nothing until43 something calls `grab_focus()` (docs, Controller navigation; measured). Keep a menu stack that44 disables covered panels and returns focus to the opener (Mostly Mad Productions ecJZipjUj6k45 00:08:57).465. **The current selection is the highest-contrast element on screen,** body text comes first, two47 or three fonts at most, and the outro is faster than the intro (Rawb Herb, GodotCon 2025,48 sjmAD1ZLBcE 00:31:42, 00:21:34, 00:55:38).496. **Text is keys, never literals.** Named placeholders with `format()`, `tr_n()` for plurals,50 context for identical English, auto translate disabled on dynamic text (docs, Internationalizing51 games). Fonts get fallbacks, not remaps.527. **HUD is passive and signal-driven.** Its root and wrappers ignore the mouse; values change on53 signals, not in `_process` (consensus of 1_OFJLyqlXI, Yuw7CK5H8eA, f90ieBOoIYQ). A new string54 reshapes (200 labels: 1.1 to 1.5 ms of CPU per frame); assigning the identical string is an55 early-out, so the cost is the changed text, not the assignment [added, measured]. In-place array56 mutations never call a setter (0 calls after `append`, 1 after reassigning), so state arrays emit57 their own signal (NoBSGodot Yuw7CK5H8eA 00:05:06, measured).588. **Verify at device sizes headless, then look.** Headless, `root.size` takes any size and applies59 the project stretch, so a layout matrix runs in seconds; a windowed capture then renders each60 device with the notch drawn in [added, measured].6162## Establish first6364| Input | Changes | Default if nobody says |65| -------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |66| Platforms and orientations | base size, orientation, touch target size | phone portrait + landscape, desktop to 4K: base 720x720, `canvas_items`, `expand`, orientation 6 (sensor) |67| Art style | stretch mode and scale mode | vector or high-res: `canvas_items` + fractional; pixel art: `viewport`, base 640x360, integer, Exclusive Fullscreen (docs) |68| Input devices | focus work, rebind screen, touch sizes | mouse, keyboard, pad, touch |69| Languages | fonts, RTL, Text Server Data on export | en plus one long (de), one CJK (ja), one RTL (ar) for tests |70| Accessibility bar | screen reader, UI scale slider, contrast | WCAG 4.5:1 body text, UI scale 0.75 to 2.0 via `content_scale_factor` |71| Renderer | upscaler choice in settings | Forward+ (Jolt kept); Compatibility forces bilinear 3D scaling |7273## Workflow7475**1. Project settings.** Write the stretch keys explicitly: a hand-written project.godot gets76`disabled` and `keep` (deltas). `gd_env.set_project_setting` for77`display/window/size/viewport_width/height`, `stretch/mode`, `stretch/aspect`,78`handheld/orientation`, `gui/theme/custom`. Check that `3d/physics_engine="Jolt Physics"` and the79renderer survived. GATE: `gd_ui.stretch_math(window, base, ...)` for each target gives the expected80logical size and scale (port matches the engine on 224 cases, origin and scale included).8182**2. Theme in code.** [`ui_theme.gd`](scripts/agentkit/ui/ui_theme.gd) `build(overrides)` returns a83Theme: Button states with a thick accent focus box, Label, panels, sliders, tabs, ProgressBar,84variations TitleLabel, HudLabel, HudValue, PrimaryButton, HudPanel, HealthBar, TrailBar. Save it as85`.tres`, set the default font to a SystemFont with CJK and Arabic fallbacks, two or three fonts at86most. Text drawn at many scales (HUD numerals at 3x) gets MSDF:87`gui/theme/default_font_multichannel_signed_distance_field` or the font's88`multichannel_signed_distance_field`, both false by default (Karto 5Hog6a0EYa0 00:20:50, measured).89Default Theme Scale is read once: a runtime set changed nothing (measured). In the editor a Theme90edit needs a scene reload to repaint (Godotneers 00:22:10) and an override is inactive until its91checkbox is ticked (Karto 00:17:25); in code only `add_theme_*_override` counts, and runtime Theme92edits propagate at once (measured). GATE: `contrast_report()` body pairs >= 4.5:1 (worst measured934.37 is the disabled state, allowed); `check_variations()` finds no misspelt variation.9495**3. Scenes in code.** Root Control full rect, a [`safe_area.gd`](scripts/agentkit/ui/safe_area.gd)96MarginContainer, then containers. Buttons 88 logical tall at a 720 base (132 px on a phone at 1.5x).97Settings rows in ScrollContainers inside a TabContainer. HUD on a CanvasLayer, root98`MOUSE_FILTER_IGNORE`, AspectRatioContainer for the minimap; a round minimap or portrait frame is a99`clip_children` mask (Clip Only on a rounded Panel), but a child with another `z_index` escapes it100(GDQuest W4j4tnQLcTA 00:03:47, measured), so keep masked content at z 0 or use a SubViewport.101Toggles read "On"/"Off" as text (CoffeeCrow 9H_fN4OxyIE 00:08:11). `safe_area.gd` recomputes on102`size_changed` (top margin 104 at 1.5x, 82 at 2x, measured). `examples/build_g7.gd` builds the whole103G7 set. GATE: [`ui_audit.gd`](scripts/agentkit/ui/ui_audit.gd) `audit_tree()` returns no104`hud_blocks_input`, `icon_keep_size`, `grows_offscreen_*`, `no_accessible_name`,105`shared_stylebox_override`, `unknown_variation`.106107**4. Layout matrix headless.**108`gd_ui.layout_matrix(P, scene, targets, min_touch_px=..., safe_insets=..., locale=..., pseudo=True)`109for 8 targets (phone portrait and landscape, 4:3 tablet, 1366x768, 1080p, 21:9, 4K, 800x600). GATE:110zero offscreen, outside_safe, small_target, text (clipped or overflowing), overlap and collapsed111issues for each scene, in en, de and pseudolocalized at 0.4 expansion.112113**5. Capture matrix windowed, then look.**114`gd_ui.capture_matrix(P, scene, targets, safe_insets=...)` renders each target at its physical size115with black bars and red notch bands, and builds a contact sheet. Open the sheet. GATE:116`image_checks` flags none; by eye: selection visible, no clipped glyphs (CJK, Arabic), notch bands117over background only, bars and frames intact. Never capture through an embedded Window with118`content_scale_*`: it draws unscaled (P13, measured).119120**6. Focus and input.** `gd_ui.focus_walk(P, scene, steps)` pushes `ui_*` actions through121`push_input` and records the focus owner; `ui_focus.graph()` lists unreachable focusables. Menu122stack: open, cancel, focus back on the opener. GATE: every focusable reachable from the default;123first key press from no focus lands on the default; covered panels unreachable.124125**7. Rebinding.** [`ui_rebind.gd`](scripts/agentkit/ui/ui_rebind.gd): accept (no echo, no Escape,126sticks over 0.5), normalize (physical keycode, device -1, axis sign), report conflicts, swap or127refuse, save as ConfigFile, reset from project settings. Show the key with128`DisplayServer.keyboard_get_label_from_physical()` (windowed only): on a French layout physical Q129reads "A" (measured). Add pad buttons yourself: in 4.7.2 `ui_accept` and `ui_cancel` hold keys only130(Enter, Kp Enter, Space; Escape), so add Joypad Button 0 and 1 (Mostly Mad ecJZipjUj6k 00:12:00,131measured). GATE: binding matches on keyboard and on any pad after a save and load round trip.132133**8. Localization.** CSV with a `?plural` column, `gd_ui.check_csv` offline, `--import`, then134`gd_ui.register_translations`. Run en, fr, de, ja, ar and pseudolocalization; `expansion_ratio`135defaults to 0.0, so set 0.3 to 0.4 and call `reload_pseudolocalization()` (measured).136`--language fr` is the non-persistent test. Animated text is a RichTextEffect: `bbcode` var plus137`_process_custom_fx(char_fx)`, options from `char_fx.env` (Cashew OldDew KMqYeRae6rM 00:14:01;138measured `[lift px=6]` read 6.0), installed with `install_effect()`. GATE: no missing keys per139locale; Arabic mirrors (anchors and HBox order); plurals right in en and fr; layout matrix clean.140141**9. Settings and cost.** [`ui_settings.gd`](scripts/agentkit/ui/ui_settings.gd) autoload applies142window mode, vsync, render scale and upscaler, quality, UI scale, bus volumes, locale; saves and143reloads. GATE: save and load round trip; `ui_scale` 1.5 turns a 1280x720 canvas into 853x480.144145## Numbers146147| Value | Relative to | Source |148| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------- |149| Base 720x720, `canvas_items`, `expand`, orientation sensor | phone portrait and landscape plus desktop | docs, Multiple resolutions |150| Scale 1.5 on 1080x2400 and 2400x1080, 3.0 on 3840x2160, 1.0672 on 1366x768 | base 720x720 | measured [added] |151| Base 720x1280 on a 2400x1080 phone: `expand` 2844x1280 at 0.844x (UI shrinks), `keep_width` 897 px side bars; `keep_height` on 1080x2400: 240 px bars | why a square base beats an aspect choice | measured [added] |152| Pixel art 640x360 `viewport` integer; `viewport` at fractional 1.0672 (1366x768) resamples and blurs text | 720p to 4K | docs, measured |153| Default Theme Scale 2.0 to 3.0 for a 4K base, 1.5 to 2.0 mobile 1080p base; read once (runtime set: no change) | base size | docs, measured |154| Touch target 126 px phone, 96 px tablet (48 dp at about 420 and 320 dpi) | physical pixels | [added] |155| Button 88 logical at base 720 | 132 px on a phone | [added, measured] |156| WCAG 4.5:1 body, 3:1 large text | text vs its background | WCAG 2 [added] |157| Damage trail: one-shot timer 0.4 s, restarted per hit; heal instant | health change | DashNothing f90ieBOoIYQ 00:01:26 |158| Text Server Data ~4 MB | export size, for no-space scripts | docs |159| 200 labels: 1.1 to 1.5 ms new text every frame, 0.17 to 0.23 ms for 10 per frame, under 0.1 ms same text (as idle) | CPU per frame, headless M5 Max | measured [added] |160161## Quality gates162163Measurable: `test_ui_live.py` U1 to U15 green (compile, stretch parity, CSV, layout matrix, capture,164focus, rebind, HUD, localization, engine facts, theme and settings, cost, embedded Window, round-2165layout and theme facts, clip mask and text effect); zero issues in the layout matrix for each scene166and locale; audit clean; contrast >= 4.5:1 on body pairs; save and load round trips. Visual: one167contact sheet per scene and locale (menu, HUD, settings ja, menu ar, settings pseudo), opened: focus168visible, glyphs complete, nothing under the notch, letterbox where expected, selection still visible169in grayscale (Rawb Herb).170171## Common mistakes172173| Mistake | What it looks like | Fix |174| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |175| 1920x1080 or 1152x648 base for a phone game | tiny buttons in portrait (scale 0.9375 at 1080x2400) | square base 720x720 + expand |176| Stretch keys left out of an agent-written project.godot | UI fixed size, black space on 4K | write mode and aspect explicitly |177| Full-rect Control with default STOP filter over the game | clicks never reach `_unhandled_input` (0 of 1) | `MOUSE_FILTER_IGNORE` on HUD roots and wrappers |178| Corner preset without grow direction | score text runs off the right edge | `grow_horizontal = GROW_DIRECTION_BEGIN` |179| No `grab_focus()` on open | pad does nothing | menu stack grabs the default on the first nav event |180| TextureRect left on `KEEP_SIZE` in a container | a 512 px icon makes a 64 px row 614x512; `IGNORE_SIZE` with no minimum collapses to width 0 | `EXPAND_FIT_WIDTH_PROPORTIONAL` (64x64 measured) or ignore size + min size, Stretch Keep Aspect Centered (Godotneers 1_OFJLyqlXI 00:10:28) |181| OptionButton items as literal English | Japanese screen shows "Windowed" | items as keys (`OPT_WINDOWED`) |182| Tabs left at theme default | tabs too small to touch | tab styleboxes with content margins; the matrix checks the TabBar |183| Stored binding with device 0 from a synthesized event | pad 2 or the real keyboard (device 16) do not trigger | normalize to device -1 |184| Pseudolocalization on, expansion untouched or no reload | no padding (default ratio 0.0) | set `expansion_ratio`, `TranslationServer.reload_pseudolocalization()` |185| POT generation trusted for custom nodes in old tutorials | strings missing (4.2 bug) | fixed in 4.3 (Cashew OldDew v0tJPsNNOM8 00:08:00, not rerun); CSV keys avoid POT |186| Locale Test set in project settings | ships in French | clear it; use `--language fr` |187| Hiding a container child with `visible = false` for an effect | siblings jump (relayout) | `modulate.a = 0` or `offset_transform_scale` (MrElipteach pK2vI2-jCH4 00:02:54) |188| Expecting a focus ring after a mouse click | ring only on the next key or pad press | by design: `gui/common/show_focus_state_on_pointer_event` 1 (text inputs only) |189190## Handoffs191192- In: state autoloads and signals (scenario-godot-architecture), input actions and values193 (scenario-godot-gameplay), bus names Master, Music, SFX (scenario-godot-audio), icons, panels,194 fonts (scenario-* skills; nine-patch margins set in code).195- Out: render scale and upscaler contract (scenario-godot-rendering-lighting); Text Server Data,196 real-device safe area and touch (scenario-godot-performance-export); intro and outro tracks,197 `offset_transform` motion (scenario-godot-animation); `test_ui_live.py` for CI198 (scenario-godot-pipeline-automation).199200## Godot 4.7 notes201202- `offset_transform_*` (4.7) moves container children without relayout;203 `offset_transform_visual_only` defaults to true, so clicks hit the layout rect (measured).204 `pivot_offset_ratio` (4.7) for center pivots; `grab_focus(hide_focus)` (4.6).205- `AccessibilityServer` (4.7), `accessibility_name`, `FOCUS_ACCESSIBILITY` (RichTextLabel default);206 `accessibility_support` 0 Auto runs only with an assistive app active.207- `auto_translate_mode` replaced `auto_translate`; `FoldableContainer` (4.5), `VirtualJoystick`,208 `PopupMenu.allow_search` (4.7); `[img]` takes `width_unit`/`height_unit`. Upscalers: FSR2=2,209 MetalFX spatial=3, temporal=4.210- `push_input(event, true)` takes logical coordinates. Godot 3 names (`rect_size`,211 `add_color_override`, `margin_*`, stretch `2d`, `process_custom_fx`) are gone.212213## References214215- [`references/procedures.md`](references/procedures.md): P1 to P15 with full code paths, live test216 ids and results.217- [`references/expert-notes.md`](references/expert-notes.md): what each source teaches, with218 timestamps.219- [`references/critique.md`](references/critique.md): the rubric for judging a UI build and its220 captures.221- [`references/gui-paths.md`](references/gui-paths.md): the same steps through the editor for a222 computer-use agent.223- [`references/sources.md`](references/sources.md): every source, credentials, URLs, best224 timestamps.225- [`scripts/gd_ui.py`](scripts/gd_ui.py), [`scripts/agentkit/ui/*.gd`](scripts/agentkit/ui/),226 [`scripts/agentkit/ui/examples/build_g7.gd`](scripts/agentkit/ui/examples/build_g7.gd).