gohud

Imported from thruthesky/gohud (skills/gohud/SKILL.md). Install upstream with npx skills add thruthesky/gohud --skill gohud. Copyright stays with the author (MIT).

gohud — game UI for Godot 4.6+

gohud is a pure-GDScript HUD & UI kit. Every class is global once the folder sits at res://addons/gohud/; widgets are made with .new() + add_child() and styled by one theme, one skin and one icon set. This skill carries the whole API (references/), runnable screen templates (assets/templates/) and a preview launcher (scripts/gohud_preview.py).

Arguments given: $ARGUMENTS

1. Route the request

Reply in the language the user writes in; keep code identifiers as they are.

2. Workflow for building UI

1. Check the project. test -f project.godot, test -f addons/gohud/plugin.cfg, godot --version (needs 4.6+). Note the gohud version (version= in plugin.cfg) — rules 4, 5 and 7 differ for 1.0.3 and older. Missing add-on → install it (references/setup.md §1), then godot --headless --path . --import.
2. Pick the look first. GoUi.use_preset(GoThemePresets.SCIFI_DARK) (or the project setting) before any widget is built. Nodes keep the theme they were built with; switching later means rebuilding the screen.
3. Choose the widget for the job — table in references/surfaces.md §7: blocking question → GoDialogs, list over the game → GoSheet, side panel on a wide screen → GoDrawer, window → GoSurface, full-screen menu/login/settings → root Control + GoForm, message with an Undo button → GoSnackbar, fixed notice panel the HUD owns → GoNotice, optional question → GoPromptCard, info card next to a slot → GoPopover, HUD pieces → GoHudAnchor. Lists and forms: sortable/selectable rows → GoTable, pages → GoPagination, searchable picker → GoCombobox, a field that can show an error → GoField, input welded to a button → GoInputGroup. Waiting → GoSpinner (GoSpinner.busy(button, true) also blocks the double press). A list the player scans (quests, mail, a shop) → rule 15 in §3 and the recipe in references/recipes.md §16.
4. Start from a template when one fits (§5): copy it into the project (e.g. res://ui/), rename, adjust, wire its signals. Otherwise compose with GoStyle factories (references/style.md).
5. Follow the rules in §3. Look up exact signatures in the references before using a member you are not sure of — do not guess APIs.
6. Verify without a window: python3 ${CLAUDE_SKILL_DIR}/scripts/gohud_preview.py res://ui/my_screen.tscn --check (or godot --headless --path . --quit-after 120 res://ui/my_screen.tscn and scan for SCRIPT ERROR, Parse Error, ERROR: Failed). Open a visible window only when the user asks to see it (§6).

3. Rules that prevent the real bugs

1. Sizes and colours come from tokens, never literals: GoUi.metric(GoTheme.GAP), GoUi.color(GoTheme.MUTED), GoStyle.* factories. Literals break when the preset, breakpoint or touch size changes.
2. Text vs keys. GoStyle.label()/button() show text as written; label_key()/button_key() hold translation keys. list_button(), foldable(), section(), toggle(), checkbox() translate by default — pass translate = false for literal strings.
3. Surfaces go in a CanvasLayer, and the owner closes them. GoSurface only emits close_requested. Layers: HUD 5 · GoSheet 10 · your popups 50 · GoDialogs 100.
4. Per-page sheet buttons go through sheet.add_footer(button) — the next open() removes them. open() only hides footer(), so children added with footer().add_child() stay (right for a sheet-wide snackbar, wrong for a Close button re-added on every open). gohud 1.0.3 and older have no add_footer(): remove your footer children first.
5. Assemble GoForm → GoScroll → column before the form enters the tree. _ready runs inside add_child; a scroll added later is never found (no keyboard follow), and %BackButton (Android Back routing) is looked up once there. In code: name the button BackButton, add it, set back.owner = form and back.unique_name_in_owner = true, then add_child(form). gohud 1.0.3 and older clear that owner when the scroll moves — there, own the whole branch from a holder (owner = holder on every descendant; the templates do this, and it works on every version).
6. HUD root: mouse_filter = MOUSE_FILTER_IGNORE. Transient anchors (toasts, prompts, joystick) use reserve_space = false; toasts at TOP_CENTER use avoid_peers = true. Put a GoStyle.floating() panel behind HUD text that floats over content.
7. await dialogs. {placeholders} in the title and body are filled only from args (gohud 1.0.3 and older format only the body — build the title string yourself there). Irreversible confirms use destructive = true (last argument).
8. Bars use fill tokens (GoTheme.DANGER_FILL, INFO_FILL, WARNING_FILL, SUCCESS_FILL); text colours look dull as fills on light themes.
9. Touch: icon-only buttons get a tooltip (GoStyle.icon_button(icon, action, -1, &"Menu")) — it is also the accessible name. Side-by-side GoIconButtons / GoSlots need touch_peers.
10. Config: after changing a plain GoConfig field in code call GoUi.refresh(); theme/icons refresh themselves. use_preset() clears explicit theme/skin/icons — set overrides after it.
11. Gameplay input pauses while a window is open: if GoSurface.is_any_open(): return.
12. Widgets that draw text inside a non-container parent must not wrap. A Label with autowrap laid out at zero width freezes its minimum height at 1 dp and the text disappears while the panel still paints — this is why table cells, key caps and code cells set AUTOWRAP_OFF. When you place a child by anchors, set offset_*, not position: Control.position is parent-space and ignores the anchors.
13. Containers are 80% opaque; things you press are not. Panels (GoSurface/GoSheet/GoDialogs/cards/ HUD panels/alerts/snackbars) fade their face only — never use modulate.a for this, it fades the text too. Five layers decide the value, most specific first: the alpha argument or field at that call → GoConfig.container_alpha_overrides[GoTheme.BOX_*] → metric_overrides[<kind>_alpha] → GoConfig.container_alpha → theme GoHud/constants/<kind>_alpha. 🔑 Every one of them is a ratio 0.0–1.0 (negative = not set), including @export fields such as dialogs.alpha and drawer.alpha — same units everywhere, so there is nothing to memorise per widget. 🛑 The two exceptions are the theme's constants and metric_overrides, which are percent integers (80) because a Theme constant cannot hold a float. Call GoUi.refresh() after changing it from code. Read the resolved value with GoUi.surface_alpha(variant); apply it to a panel gohud did not build with GoStyle.fade_panel(node) (after add_child). A GoSkin subclass overriding surface_box/floating_box/alert_box must carry the alpha parameter or the script will not parse. 🔑 Drag it before you argue about the number: the opacity lab (examples/gallery/opacity_lab.gd) is hosted by the gallery, the guided tour (chapter 16), the home screen and the medieval example — it shows the four ways to set the value on one screen, over a pattern, because a value check cannot tell you whether the text is still readable. Details: references/theming.md §4.
14. Never hand-edit gohud's generated themes; recolour through color_overrides, a Theme copy in your project, a project-local GoThemePreset, or the JSON theme tools (references/theming.md).
15. Lists must scan — a list the player reads (quests, mail, a shop, a roster) is judged by numbers, not taste. ① Space outside a row > space inside it ≥ space between its lines: rows at least GAP_SMALL (8) apart (GAP 12 when there is room), a two-line row padded 8 above and below and 12 at the sides, its two lines GAP_TINY (4) apart — list_button() already pads its row this way. A cramped panel that used 4 for all three ran its rows together. ② The heading must be a size above the row titles. Rows are ROLE_BODY (16) with a ROLE_CAPTION (13) second line in MUTED; the heading the player reads first is ROLE_SUBTITLE (22). A GoSurface or GoSheet short of height (or compact) drops its own title to body, so a list under it becomes one size — put that heading in the body instead. ③ Say a thing once: no header line repeating the first row. ④ Warning colours and warning icons only on rows where something is wrong; a level gate is a LOCK and MUTED text (never modulate.a — rule 13). A badge that repeats on every row carries nothing — drop it; an icon that states each row's own state (a lock, a check) may repeat. ⑤ A value at a row's end (0 / 1, a price) is a label with SIZE_SHRINK_END — GoStyle.label() expands by default and would split the width with the title. list_button() has no text slot at the end: build that row yourself and keep its padding and GoStyle.fit_content_height(). ⑥ Your spacing does not survive everywhere: GoStyle.form() (every GoForm) sets each box's separation to GAP unless it carries set_meta(&"go_own_spacing", true), and a wrap_row() forces everything inside it — all the way down — to natural width with wrapping off, so never put a card or a row with an expanding title in one. See it before you build it: the gallery's List rows section opens a lab (examples/gallery/list_lab.gd) with a cramped quest panel next to the same panel built by this rule, each measured from its own nodes. Recipe: references/recipes.md §16.

More traps with their causes: references/pitfalls.md.

4. Minimal screen

extends Control

var dialogs: GoDialogs

func _ready() -> void:
	GoUi.use_preset(GoThemePresets.DEFAULT_DARK)
	set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
	theme = GoUi.theme()
	RenderingServer.set_default_clear_color(GoUi.color(GoTheme.BACKGROUND))
	var form := GoForm.new()
	var scroll := GoScroll.new()
	var column := GoStyle.column()
	form.add_child(scroll)
	scroll.add_child(column)
	column.add_child(GoStyle.label("Hello gohud", GoTheme.ROLE_TITLE))
	column.add_child(GoStyle.button("Open dialog", _on_open, GoStyle.Tone.PRIMARY))
	add_child(form)
	dialogs = GoDialogs.new()
	add_child(dialogs)

func _on_open() -> void:
	if await dialogs.confirm("Delete save", "This cannot be undone.", "Delete", "", "", {}, true):
		print("deleted")

5. Templates — assets/templates/

Each is a complete, headless-tested script with no scene file. Copy, then connect signals.

Wiring them together and more screens (login, shop, quest log, character sheet, dropdown menus, tutorial tour): references/recipes.md.

6. Preview — /gohud preview (plugin: /gohud:preview)

Run from the user's project folder so their addons/gohud is used (otherwise the bundled copy or a clone):

python3 ${CLAUDE_SKILL_DIR}/scripts/gohud_preview.py <arguments>      # Windows: python

If ${CLAUDE_SKILL_DIR} is not expanded, use the first existing path of ${CLAUDE_PLUGIN_ROOT}/skills/gohud/scripts/gohud_preview.py, ~/.claude/skills/gohud/scripts/gohud_preview.py, .claude/skills/gohud/scripts/gohud_preview.py.

gohud's examples run in a sandbox project under the user cache, so the user's project is not modified. The script detaches and prints the process id and log path. Exit 2 = Godot 4.6+ not found or bad arguments; exit 1 = import or launch error (it prints the error lines). A visible window is what /gohud preview is for; for your own checks use --check.

7. References — read the one you need

Web (same content, with screenshots): overview https://thruthesky.github.io/gohud/ · install https://thruthesky.github.io/gohud/install.html · AI skill https://thruthesky.github.io/gohud/ai.html · widgets https://thruthesky.github.io/gohud/widgets.html · theming https://thruthesky.github.io/gohud/theming.html