Popups and dialogs

Pick the right popup

A popup interrupts. Before choosing one, answer a single question: must the player answer before the game goes on? If yes, block. If no, never block — a card that stops the game for news the player did not ask for is the fastest way to make them close your game.

1. A question with an answer — buy, delete, leave, overwrite → GoDialogs.confirm(). Something to acknowledge → alert(). One of a few options → choose().
2. A screen of its own — settings, a character sheet, a shop item → GoSurface in the middle of the screen.
3. A long list or a management page — the bag, mail, friends → GoSheet from the bottom on a phone, GoDrawer from the side on a wide screen.
4. Something about the thing just pressed — an item's stats, its actions → GoPopover or GoContextMenu beside it.
5. News the game can carry on through — saved, dropped, invited → GoSnackbar, GoNotice or GoPromptCard. These never take the screen.
6. Teaching the controls → GoCoachMark. Cheats while you build → GoConsole.

Every popup at a glance

Which layer each one opens on, and why in that order, is under Layers, Back and input.

Every picture on this page is the same little game — health and mana top left, coins top right, a joystick and three quick slots at the bottom — in default_dark, with one popup open over it. The same popup in all fourteen looks →

Anatomy of a popup

Almost every blocking popup in gohud — dialogs, sheets, popovers, the combobox list and your own windows — is one node, GoSurface. Learn its parts once and you know all of them.

Dialogs you await

GoDialogs asks and waits. One node, three questions — and the answer comes back on the same line, so the code reads in the order the player experiences it.

var dialogs := GoDialogs.new()
add_child(dialogs)

if await dialogs.confirm("Buy the starter pack?", "300 gems for a sword, a shield and 10 potions.",
        "Buy", "Not now"):
    buy_starter_pack()

The three questions

confirm(title, body, ok_text := "", cancel_text := "", extra := "",
        args := {}, destructive := false) -> bool
alert(title, body, ok_text := "", extra := "", args := {})      # await it to wait
choose(title, options: Array, cancel_text := "", translate := false) -> int
confirm_key(…) · alert_key(…)                                 # translation keys

Empty button labels fall back to the kit's own words (confirm, cancel in GoConfig.text_keys). extra is added to the body on a new line. args fills {placeholders} in the title and the body: confirm("Buy {item}?", "It costs {price} gold.", "Buy", "", "", {"item": name, "price": 300}).

Every way out has an answer

So code after await always runs — no answer is ever left hanging, even when the scene changes under the dialog.

Destructive actions

Pass destructive = true for something that cannot be undone. The OK button becomes the filled Tone.DANGER_SOLID button — white on red in every look, where a tinted danger label would have to darken to near-black on a light theme to stay legible. The tone is reset on every call, because the window is reused.

if await dialogs.confirm("Delete this save?", "Slot 2 — Aria, level 12. This cannot be undone.",
        "Delete", "Keep it", "", {}, true):
    delete_save(2)

Button layout

action_gap is the space between the buttons, body_gap the space above them — make it wider than the button gap so the question and the choice read as two parts. For one dialog only, call set_next_action_layout() before opening it. An alert's single button always takes the full width.

One at a time

A second confirm() while one is open returns false at once — a dialog never stacks on a dialog by accident. Turn on queue_when_busy and it waits its turn instead; alert() always waits. queue_limit (8) caps the line, and on overflow the oldest request is answered false. pending() counts the waiting requests and clear_pending() answers them all false. choose() never queues: it returns -1 when a dialog is already open.

Phone and desktop

choose() opens as a sheet from the bottom on Android and iOS — where the thumb is — and as a card in the middle on a desktop. A confirm is capped at max_width (420dp) and centred. Set layer_index, max_width and the other exports before add_child; they are applied when the node enters the tree.

var picked := await dialogs.choose("Sort the bag by", [
    {"text": "Newest first", "icon": GoIconSet.CLOCK},
    {"text": "Rarity", "icon": GoIconSet.STAR},
    {"text": "Drop everything", "icon": GoIconSet.TRASH, "danger": true}])
if picked >= 0:
    sort_bag(picked)

GoSurface — a window of your own

When a popup is more than a question — settings, a character sheet, an item to buy — build it on GoSurface. The safe area, the keyboard, pinned rows, scrolling, Back, focus and resizing are done.

var layer := CanvasLayer.new()
layer.layer = 50
add_child(layer)

var window := GoSurface.new()
window.set_title("Settings")
window.close_requested.connect(layer.queue_free)
window.body.add_child(GoStyle.toggle("Music", false))
window.body.add_child(GoStyle.slider(0.0, 1.0, 0.05))
var row := GoStyle.row()
row.add_child(GoStyle.button("Cancel", window.request_close))
row.add_child(GoStyle.button("Save", save_and_close, GoStyle.Tone.PRIMARY))
window.footer.add_child(row)
window.footer.visible = true
layer.add_child(window)

Three placements

ANCHOR needs anchor_control. The card goes to the right of it if anchor_min_width fits, otherwise to the wider side, otherwise inside the screen, and opens upward when there is more room above. It follows a moving anchor every frame. anchor_width (320) and anchor_max_height (520) size it.

How big it gets

A ratio above the cap is cut back, with one warning in a debug build. The keyboard pushes the card up and scrolls the focused field into view; the safe area keeps it off the notch and the gesture bar on Android and iOS.

Properties

Signals and calls

Sheets and drawers

A list that needs room comes up from the bottom on a phone held upright — where the thumb is — and in from the side on a tablet or a desktop, where a sheet would cover the game.

GoSheet — pages from the bottom

var sheet := GoSheet.new()
add_child(sheet)

func show_bag(items: Array) -> void:
    sheet.open("Bag")
    var search := GoStyle.line_edit("Search the bag…")
    search.text_changed.connect(filter_bag)
    sheet.toolbar().add_child(search)
    sheet.toolbar().visible = true
    for item in items:
        sheet.body.add_child(GoStyle.list_button(GoIconSet.BOX, item.name, show_item.bind(item),
            Color.TRANSPARENT, item.description, false, GoIconSet.CHEVRON_RIGHT))
    sheet.add_footer(GoStyle.button("Close", sheet.close, GoStyle.Tone.PRIMARY))

• It is a CanvasLayer (layer 10) holding a BOTTOM, resizable GoSurface — so it sits above the HUD, and the player can drag it taller.
• open(title) starts a fresh page: it clears the body, the toolbar and the back button and frees what add_footer() added. Call it again to show another page in the same sheet; set_back() shows a back button for the way home. open_key() takes a translation key.
• close() hides it — it is not freed, so the next open() is instant. closed and page_changed tell you when.
• height_ratio (0.6) is the height it opens at; max_height_ratio lifts the cap; dismissable (true) closes it on a scrim tap.

GoDrawer — from the side

var drawer := GoDrawer.new()
drawer.side = GoDrawer.Side.LEFT
drawer.follow_text_direction = true      # the start side: left, or right in Arabic
add_child(drawer)
drawer.body.add_child(GoNavBar.drawer_list([{"icon": GoIconSet.HOME, "text": "Town"},
    {"icon": GoIconSet.MAP, "text": "World map"}], 0, go_to))
drawer.open("Menu")

• Layer 80. 42% of the screen wide (width_ratio), between min_width (320dp) and max_width (420dp) — on a phone it covers most of the screen, which is why a sheet is the better choice there.
• The panel reaches the screen edge; only its content steps in from the safe area, so a rounded corner never clips the first row.
• LEFT means screen-left even in Arabic. Turn on follow_text_direction when "the start side" is the point; effective_side() tells you where it went.
• open(title) keeps the body — fill it once. set_title("") hides the header. motion_seconds (0.2) slides it; reduce_motion makes it instant.

Cards and menus beside a control

What the player just pressed deserves an answer right next to the finger, not in the middle of the screen.

GoPopover — a card on the thing pressed

slot.pressed.connect(func() -> void:
    var card := GoStyle.item_card({"icon": GoIconSet.POTION, "title": "Health potion",
        "subtitle": "Heals 50 HP · 12 left"}, false)
    GoPopover.open(slot, card, {"width": 280}))

An ANCHOR surface with the layer, the anchor and the teardown already wired — the ten lines every game writes again and again. One at a time: opening a second closes the first, because stacked cards bury the screen and nobody can tell which belongs to which slot. The scrim is transparent — a card opened to compare gear must not darken the gear — but it still catches the first outside tap, which closes the card and goes no further.

GoPopover.close() and GoPopover.is_open() are static. open() returns the surface — or null when the anchor is not in the tree, so check before you await shown.close_requested.

GoContextMenu — long-press and right-click

var menu := [
    {"text": "Use", "icon": GoIconSet.POTION, "action": use},
    {"separator": true},
    {"text": "Drop", "icon": GoIconSet.TRASH, "action": drop, "danger": true}]
GoContextMenu.attach(slot, menu)

var more := GoStyle.icon_button(GoIconSet.MORE, Callable(), -1, &"more")
more.pressed.connect(func() -> void: GoContextMenu.open_at(more, menu))

• A right-click opens it at once. A finger held for half a second (HOLD_SECONDS) opens it; moving more than 12dp cancels — so scrolling a list never pops a menu.
• An item is {text, action, icon, disabled, checked, separator, danger, translate}. Pass a Callable instead of the array when the entries depend on what was pressed; it is called each time the menu opens.
• danger puts "⚠ " before the text — the engine's menu can colour only all of its items at once.
• It is the engine's PopupMenu, dressed by GoStyle.style_popup(). It does not count as an open surface.

Dropdowns, selects and the split button

var sort := GoStyle.dropdown("Sort", ["Highest score", "Most wins", {"text": "Friends only", "disabled": true}],
    func(index: int) -> void: sort_board(index))
var quality := GoStyle.select(["Low", "Medium", "High", "Ultra"], "Quality")
quality.item_selected.connect(func(index: int) -> void: settings.quality = index)
var send := GoSplitButton.make("Send", send_now, ["Send later", "Save as draft"])

All three open the engine's popup menu: dropdown() is a MenuButton that runs an action, select() an OptionButton that keeps a value, GoSplitButton a main action plus a menu on its arrow (chosen(index)). Menus stay fully opaque on purpose — a menu shown in its own OS window turns translucent pixels black.

GoCombobox — a list that searches

var friend := GoCombobox.make(friend_names, -1, "Find a friend")
friend.picked.connect(func(index: int) -> void: invite(friend_names[index]))

Pressed, it opens an anchored list on layer 96 with a transparent scrim. From search_threshold (8) entries a search field appears and takes the focus; it matches anywhere in the text or the hint, ignoring case, and an empty result says so. list_width (0 = the button's width, at least 180dp) sizes the list.

Popups that never stop the game

News the player can read while playing. None of these has a scrim; a tap anywhere but the card itself goes to the game.

GoSnackbar — a message with an Undo

var snack := GoSnackbar.new()
add_child(snack)

if await snack.post({"text": "Dropped {name}", "args": {"name": item.name}, "icon": GoIconSet.TRASH,
        "actions": ["Undo"], "seconds": 5.0}) == 0:
    restore(item)

post() returns the index of the button pressed, or -1 when it timed out or was dismissed. Posts queue (queue_limit 4, the oldest dropped with -1), and the same text posted again while it shows only refills its timer. It sits at the bottom (or the top, placement), above the safe area and the keyboard, on layer 90 — readable over a drawer. With tap_to_dismiss (on) a tap on a card without buttons closes it; a tap off the card always reaches the game. show_text() and show_key() are the one-line forms.

GoNotice — a line on the HUD

var notice := GoNotice.new()
hud_corner.add_child(notice)
notice.show_text("Game saved", GoTheme.SUCCESS)
notice.custom_minimum_size.x = notice.preferred_width(340)

A plain panel you place yourself — in a GoHudAnchor, in a corner, anywhere. It takes neither input nor focus, so pressing through it reaches the button underneath, and a new message replaces the old one. Give it a width: preferred_width(limit) returns the natural width of short text and wraps long text within limit. set_content() shows any control instead of text.

GoPromptCard — a question that can wait

var spot := GoHudAnchor.new()
spot.spot = GoHudAnchor.Spot.TOP_CENTER
spot.reserve_space = false
spot.avoid_peers = true            # step below the health bars instead of covering them
hud.add_child(spot)

var invite := GoPromptCard.new()
spot.add_child(invite)
invite.set_icon(GoIconSet.USERS, Color.TRANSPARENT, true)
invite.set_title("Party invite from Ann")
invite.set_subtitle("Dragon's Lair · 3 / 4 members")
invite.set_actions([{"text": "Accept", "action": accept, "primary": true},
    {"text": "Decline", "action": invite.hide}])
invite.fit_width(340)
invite.show()
get_tree().create_timer(15.0).timeout.connect(invite.hide)

• It starts hidden — call show(). It has no timer of its own; add one if the question expires.
• Its buttons do not close it — the actions decide. × (set_closable(true)) emits closed.
• fit_width(width) sets the width and predicts the height from the font, so nothing laid out against it jumps a frame later.
• Its face follows hud_alpha — it is part of the HUD, not a window.

GoBanner and tooltips

GoBanner.make("You're offline.", [{"text": "Retry", "action": reconnect}], GoIconSet.WARNING) sits in the page itself, above the content, and never times out; a button dismisses it unless it has "keep": true. GoStyle.tooltip_node(text) is what to return from _make_custom_tooltip() — the engine draws the plate (TooltipPanel), gohud the text, wrapped past 260dp. Tooltips are for a mouse; never hide what a player needs behind one.

Tours and the console

GoCoachMark — a tour of the real controls

var tour := GoCoachMark.new()
tour.keep_clear = [top_bar]
tour_layer.add_child(tour)
tour.finished.connect(func(completed: bool) -> void: save.tutorial_done = true)
tour.start([{"target": bag_button, "title": "Bag", "body": "Everything you pick up lands here."},
    {"target": map_button, "title": "Map", "body": "Tap to open the full map."}])

• A ring around the real control and a card beside it. Pressing the target advances (its pressed signal, or "signal" in the step); Next and Skip are on the card. A hidden target is skipped.
• The card stays out of the middle of the screen (avoid_center_band), off the HUD anchors and off keep_clear.
• While any GoSurface is open the tour hides and waits. Back or Escape ends it with finished(false).
• It has no layer of its own — add it last, or on a layer above the HUD.

GoConsole — cheats while you build

var console := GoConsole.new()
add_child(console)
console.register("give", "give <item> <count>", func(args: PackedStringArray) -> String:
    return "gave %s x%s" % [args[0], args[1]] if args.size() >= 2 else "give <item> <count>")

func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed(&"dev_console"): console.toggle()

Layer 200 — above everything, so you can debug over a dialog — and it keeps running while the tree is paused. A palette suggests commands as you type; Up and Down walk the history; Escape closes it. There is no built-in key: bind your own.

Layers, Back and input

Three rules decide what the player can touch while something is open: what is on top, who owns Back, and who takes a tap.

What sits on top

The order is deliberate: a snackbar reports what just happened, so it reads over a drawer; a popover belongs to what was just pressed, so it sits above that; a dialog asks a question and covers both; the console covers everything, because it is what you open when the rest has gone wrong.

Who owns Back

• Only the topmost window answers. Among the open surfaces, the one on the highest layer (then the latest in the tree) takes Escape, gamepad cancel (ui_cancel), Android Back and scrim taps. Stacked windows close one at a time, never together.
• Android Back is handled one frame later, so one press can never close two windows.
• While anything that owns Back is open, Android Back does not quit the app (GoBackPolicy counts the owners and restores quit_on_go_back after the last one). Your own popup that takes Back should call GoBackPolicy.acquire() and release() — in _exit_tree too.
• A drawer, a coach-mark tour and a form step aside while a surface is open — Back goes to the surface first.
• GoConfig.close_on_back (on) is the switch for surfaces.

Who takes a tap

• A surface covers the whole screen and stops input — a transparent scrim too. Nothing on a lower layer is pressed while it is open; layers above it (a snackbar) still are.
• Mouse-wheel and pinch gestures stop at the window as well: scrolling past the end of a list never scrolls the game.
• Gameplay input that does not go through controls — _unhandled_input for movement, a camera drag — should pause: if GoSurface.is_any_open(): return. That covers dialogs, sheets, popovers and the combobox; ask a drawer is_open() separately.
• Snackbar, notice, prompt card and coach mark take input only on their own card; everywhere else, the game gets it.

Focus

A window opened by a pointer focuses nothing — no ring flashes for a touch. Opened from a keyboard or gamepad, the close button (or initial_focus) takes focus. Focus stays inside the window while it is open and goes back to the control that had it when the window closes. Dialogs focus OK every time.

Pausing the game

Pausing the tree pauses popups too — only the console keeps working. For a pause menu, give its layer process_mode = PROCESS_MODE_ALWAYS; then the window, its buttons and Back keep running while the game is stopped.

The same popup in every look

The confirmation from the top of this page, over the same game, with only the preset changed. The code is identical — the theme, the skin and the icons do the rest.

What each look changes

Dress a popup from a skin

A skin decides the parts a Theme cannot reach. These hooks are the ones popups call — override them in your own GoSkin subclass; by default they do nothing.

How see-through

Each kind of popup follows its own opacity, so a HUD card can stay light while a dialog stays solid: windows, sheets, dialogs, popovers and the combobox follow panel_alpha; the drawer and coach card card_alpha; prompt cards and the console hud_alpha; snackbars and notices notice_alpha; menus popup_alpha. Material and kids make them all opaque; comic too, except prompt cards and the console at 92%, and arcade, except those two at 94%. Override one kind with GoConfig.container_alpha_overrides, all of them with container_alpha (a ratio — 0.95), or one window with its alpha. Only the face fades; text is never see-through. Opacity in detail →

Settings that shape every popup

Fields of GoConfig (GoUi.config). A few are copied when a window is created, so set them before building the UI — or call GoUi.refresh() after changing them.

Recipes

Copy, paste, change the words. Every call here is checked against the source.

A purchase with the price in it

func buy(item_name: String, price: int) -> void:
    if await dialogs.confirm("Buy {item}?", "It costs {price} gold.", "Buy", "", "",
            {"item": item_name, "price": price}):
        purchase(item_name)

A settings window with a pinned Save

func open_settings() -> void:
    var layer := CanvasLayer.new()
    layer.layer = 50
    add_child(layer)
    var window := GoSurface.new()
    window.set_title("Settings")
    window.dismiss_on_scrim = true
    window.close_requested.connect(layer.queue_free)
    window.body.add_child(GoStyle.section("Sound", false))
    window.body.add_child(GoStyle.toggle("Music", false))
    window.body.add_child(GoStyle.slider(0.0, 1.0, 0.05))
    var row := GoStyle.row()
    row.add_child(GoStyle.button("Cancel", window.request_close))
    row.add_child(GoStyle.button("Save", func() -> void:
        save_settings()
        layer.queue_free(), GoStyle.Tone.PRIMARY))
    window.footer.add_child(row)
    window.footer.visible = true
    layer.add_child(window)

A form that says what is wrong

var field := GoField.make("Name", GoStyle.line_edit(), "3–12 letters")
window.body.add_child(field)
create_button.pressed.connect(func() -> void:
    if name_is_taken():
        field.set_error("That name is taken")
        window.set_status_text("Name check failed", GoTheme.DANGER)
    else:
        window.clear_status()
        create_character())

A date in a sheet

sheet.open("Delivery date")
var picker := GoDatePicker.make({"year": 2026, "month": 10, "day": 14}, func(date: Dictionary) -> void:
    delivery = date
    sheet.close())
picker.min_date = GoDatePicker.today()
sheet.body.add_child(picker)

A pause menu

func pause() -> void:
    get_tree().paused = true
    var layer := CanvasLayer.new()
    layer.layer = 50
    layer.process_mode = Node.PROCESS_MODE_ALWAYS      # keeps running while the game is paused
    add_child(layer)
    var menu := GoSurface.new()
    menu.set_title("Paused")
    menu.close_requested.connect(func() -> void:
        get_tree().paused = false
        layer.queue_free())
    menu.body.add_child(GoStyle.button("Resume", menu.request_close, GoStyle.Tone.PRIMARY))
    menu.body.add_child(GoStyle.button("Settings", open_settings))
    menu.body.add_child(GoStyle.button("Quit to title", quit_to_title, GoStyle.Tone.DANGER))
    layer.add_child(menu)

Gameplay that waits for popups

func _unhandled_input(event: InputEvent) -> void:
    if GoSurface.is_any_open() or drawer.is_open():
        return
    handle_gameplay(event)

Pitfalls

• A GoSurface never frees itself. Connect close_requested, or × does nothing.
• Options set after add_child — scrim_transparent, show_header, resizable, scroll_body, and GoDialogs' layer_index and max_width — are not applied.
• A second confirm() returns false at once. Turn on queue_when_busy if two questions can meet.
• Enter confirms. OK has the focus, on destructive dialogs too.
• Back on a sheet closes the sheet, not the sub-page.
• Escape does not close a drawer, and is_any_open() does not see one.
• A popover or combobox list blocks the game until it closes, even with a transparent scrim — and a popover with dismissable = false and no title has nothing on screen that closes it.
• A prompt card starts hidden and has no timeout.
• A snackbar with seconds: 0 and no button never leaves. And it catches taps on its card by default.
• A long press nobody knows about is a feature nobody uses. Show a ⋯ too.
• A paused tree pauses your popup. Use PROCESS_MODE_ALWAYS on its layer.
• A notice without a width collapses to its narrowest — use preferred_width().
• Never ask in a snackbar, never inform in a dialog. A question goes away when ignored; news should not stop the game.