彈出視窗與對話框

挑對彈出視窗

彈出視窗會打斷玩家。挑選之前，先回答一個問題：玩家必須先回答，遊戲才能繼續嗎？ 是，就擋住；不是，就絕對不要擋 — 為了玩家根本沒問過的消息把遊戲停下來的卡片，是讓玩家關掉你的遊戲最快的方法。

1. 有答案的問題 — 購買、刪除、離開、覆寫 → GoDialogs.confirm()。只需要知道的事 → alert()。從幾個選項中挑一個 → choose()。
2. 自成一頁的畫面 — 設定、角色面板、商店裡的一件物品 → 畫面正中央的 GoSurface。
3. 長清單或管理頁面 — 背包、郵件、好友 → 手機上從底部升起的 GoSheet，寬螢幕上從側邊滑入的 GoDrawer。
4. 關於剛按下那個東西的資訊 — 物品屬性、可以做的動作 → 在它旁邊彈出的 GoPopover 或 GoContextMenu。
5. 遊戲可以照常進行的消息 — 已存檔、已丟棄、收到邀請 → GoSnackbar、GoNotice 或 GoPromptCard。它們從不佔據畫面。
6. 教玩家怎麼操作 → GoCoachMark。開發時用的作弊 → GoConsole。

所有彈出視窗一覽

每一種開在哪個圖層上、為什麼是這個順序，請看圖層、返回鍵與輸入。

本頁的每張圖都是同一個小遊戲 — 左上角是生命與魔力，右上角是金幣，底部是搖桿與三個快捷格 — 用的是 default_dark，上面開著一個彈出視窗。同一個彈出視窗在全部十四種外觀下的樣子 →

彈出視窗的構造

gohud 裡幾乎每一個會擋住遊戲的彈出視窗 — 對話方塊、底部面板、錨定卡片、組合方塊的清單，以及你自己的 視窗 — 都是同一個節點：GoSurface。把它的各個部分認識一遍，就全部都認識了。

可以 await 的對話方塊

GoDialogs 負責發問與等待。一個節點，三種問法 — 答案就在同一行回來， 所以程式碼的順序就是玩家經歷的順序。

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()

三種問法

confirm(title, body, ok_text := "", cancel_text := "", extra := "",
        args := {}, destructive := false) -> bool
alert(title, body, ok_text := "", extra := "", args := {})      # 用 await 等它結束
choose(title, options: Array, cancel_text := "", translate := false) -> int
confirm_key(…) · alert_key(…)                                 # 翻譯鍵

按鈕標籤留空時，會退回套件自己的用字（GoConfig.text_keys 裡的 confirm、cancel）。 extra 會另起一行接在本文後面。args 會填入標題與本文裡的 {placeholders}：confirm("Buy {item}?", "It costs {price} gold.", "Buy", "", "", {"item": name, "price": 300})。

每一種離開方式都有答案

所以 await 之後的程式碼一定會執行 — 不會有哪個回答一直懸著，就算對話方塊底下的場景已經換掉也一樣。

破壞性動作

無法復原的動作請傳入 destructive = true。確定按鈕會變成實心的 Tone.DANGER_SOLID 按鈕 — 在每一種外觀下都是紅底白字；而著色的危險標籤在淺色佈景主題上 必須一路變深到接近黑色才讀得清楚。因為視窗會被重複使用，色調在每次呼叫時都會重設。

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

按鈕排列

action_gap 是按鈕之間的間距，body_gap 是按鈕上方的間距 — 把後者調得比按鈕間距更寬， 問題與選項才會讀起來像兩個部分。只想改某一個對話方塊時，在開啟之前呼叫 set_next_action_layout()。提示對話方塊唯一的那顆按鈕永遠佔滿整個寬度。

一次只開一個

已經開著一個時再呼叫 confirm()，會立刻回傳 false — 對話方塊絕不會意外疊在對話方塊上。 打開 queue_when_busy，它就會改成排隊等候；alert() 一律排隊等候。 queue_limit（8）限制隊伍的長度，滿了的時候最早的請求會得到 false。 pending() 計算正在等候的請求數，clear_pending() 讓它們全部得到 false。 choose() 從不排隊：已經有對話方塊開著時，它回傳 -1。

手機與桌機

在 Android 與 iOS 上，choose() 會以底部面板的形式從下方升起 — 那裡正是拇指所在的位置；在桌機上則是 畫面正中央的一張卡片。確認對話方塊的寬度上限是 max_width（420dp），並且置中顯示。layer_index、 max_width 與其他匯出屬性請在 add_child 之前設定；它們在節點進入場景樹時才會套用。

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 — 你自己的視窗

當彈出視窗不只是一個問題 — 設定、角色面板、要購買的物品 — 就在 GoSurface 上打造。安全區域、鍵盤、固定列、捲動、返回鍵、焦點與改變大小都已經處理好了。

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)

三種擺放方式

ANCHOR 需要設定 anchor_control。右側放得下 anchor_min_width 時，卡片會放在它的右邊； 否則放在比較寬的那一側；再不行就放在畫面內；上方空間比較大時則往上展開。錨點移動時，它每一格都會跟上。 anchor_width（320）與 anchor_max_height（520）決定它的大小。

能長到多大

超過上限的比例會被裁回，並在除錯建置中發出一次警告。鍵盤會把卡片往上推，並把取得焦點的輸入欄 捲到看得見的位置；在 Android 與 iOS 上，安全區域讓它避開瀏海與手勢列。

屬性

訊號與呼叫

底部面板與抽屜

需要空間的清單，在直拿的手機上從底部升起 — 那裡正是拇指所在的位置；在平板或桌機上則從 側邊滑入，因為在那裡底部面板會把遊戲蓋住。

GoSheet — 從底部升起的頁面

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))

• 它是一個 CanvasLayer（圖層 10），裡面裝著一個 BOTTOM、可以改變大小的 GoSurface — 所以它待在 HUD 之上，玩家還能把它拉高。
• open(title) 會開始一個全新的頁面：清空本文、工具列與返回按鈕，並釋放 add_footer() 加進來的東西。再呼叫一次，就能在同一個底部面板裡顯示另一頁；set_back() 會顯示一顆 用來回到首頁的返回按鈕。open_key() 收的是翻譯鍵。
• close() 只是把它隱藏 — 並不釋放，所以下一次 open() 會立刻完成。closed 與 page_changed 會告訴你什麼時候發生。
• height_ratio（0.6）是它打開時的高度；max_height_ratio 提高上限；dismissable （true）讓點按遮罩時關閉它。

GoDrawer — 從側邊滑入

var drawer := GoDrawer.new()
drawer.side = GoDrawer.Side.LEFT
drawer.follow_text_direction = true      # 起始那一側：一般在左邊，阿拉伯文底下在右邊
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")

• 圖層 80。寬度是畫面的 42%（width_ratio），介於 min_width（320dp）與 max_width （420dp）之間 — 在手機上它會蓋住大半個畫面，所以在那裡底部面板是比較好的選擇。
• 面板一路延伸到畫面邊緣；只有裡面的內容會從安全區域往內縮，所以圓角絕不會切掉第一列。
• 就算在阿拉伯文底下，LEFT 也是指畫面左側。你要的是「起始那一側」時，請打開 follow_text_direction；effective_side() 會告訴你它最後在哪一側。
• open(title) 會保留本文 — 填一次就夠了。set_title("") 會隱藏頁首。 motion_seconds（0.2）控制滑入；reduce_motion 讓它立即出現。

控制項旁邊的卡片與選單

玩家剛按下的東西，答案應該出現在手指旁邊，而不是畫面正中央。

GoPopover — 釘在被按下之物旁的卡片

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}))

一個 ANCHOR 擺放的視窗，圖層、錨點與善後都已經接好 — 就是每個遊戲都要一再重寫的那十行。 一次只開一張：打開第二張會關掉第一張，因為卡片疊起來會把畫面埋掉，誰也分不出哪張屬於哪一格。 遮罩是透明的 — 為了比較裝備而打開的卡片，不可以把裝備變暗 — 但它仍然會接住外面的第一次點按： 卡片隨之關閉，這次點按也不會再往下傳。

GoPopover.close() 與 GoPopover.is_open() 是靜態方法。open() 回傳這個視窗 — 錨點不在場景樹裡時則回傳 null，所以在 await shown.close_requested 之前請先檢查。

GoContextMenu — 長按與右鍵

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))

• 按右鍵會立刻打開。手指按住半秒（HOLD_SECONDS）會打開；移動超過 12dp 就取消 — 所以捲動清單絕不會跳出選單。
• 項目是 {text, action, icon, disabled, checked, separator, danger, translate}。項目要看按到的是什麼才能決定時， 傳一個 Callable 來代替陣列；每次打開選單時都會呼叫它。
• danger 會在文字前面加上「⚠ 」 — 引擎的選單只能一次替所有項目上色。
• 它就是引擎的 PopupMenu，由 GoStyle.style_popup() 打扮。它不算是開著的視窗。

下拉選單、選擇器與分割按鈕

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"])

三者打開的都是引擎的彈出選單：dropdown() 是執行動作的 MenuButton， select() 是保存一個值的 OptionButton，GoSplitButton 是一個主要動作，再加上它箭頭上的選單 （chosen(index)）。選單刻意保持完全不透明 — 顯示在獨立作業系統視窗裡的選單，會把半透明的像素變成黑色。

GoCombobox — 可以搜尋的清單

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

按下後，它會在圖層 96 上打開一份錨定的清單，遮罩是透明的。項目達到 search_threshold（8）個時， 會出現搜尋欄並取得焦點；它在文字或提示的任何位置比對，不分大小寫，找不到結果時也會明白告知。 list_width（0 = 按鈕的寬度，至少 180dp）決定清單的寬度。

從不打斷遊戲的彈出視窗

玩家可以邊玩邊讀的消息。這些都沒有遮罩；點按卡片本身以外的任何地方， 都會傳給遊戲。

GoSnackbar — 附「復原」的訊息

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() 回傳被按下的按鈕的索引；逾時或被關掉時回傳 -1。訊息會排隊 （queue_limit 為 4，最早的一則以 -1 被丟掉），正在顯示時再送一次相同的文字，只會重設它的計時。 它待在底部（或頂端，見 placement），在安全區域與鍵盤之上，圖層 90 — 蓋在抽屜上也讀得到。 開啟 tap_to_dismiss（預設開啟）時，點按沒有按鈕的卡片會關閉它；點按卡片以外的地方則一律 傳給遊戲。show_text() 與 show_key() 是一行的簡寫。

GoNotice — 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)

一塊由你自己擺放的普通面板 — 放進 GoHudAnchor、放在角落，放哪裡都行。它既不接收輸入也不取得焦點， 所以隔著它按下去，按到的是底下的按鈕；新訊息會取代舊訊息。記得給它一個寬度： preferred_width(limit) 對短文字回傳它的自然寬度，對長文字則在 limit 之內換行。 set_content() 可以用任何控制項取代文字來顯示。

GoPromptCard — 可以等一等的提問

var spot := GoHudAnchor.new()
spot.spot = GoHudAnchor.Spot.TOP_CENTER
spot.reserve_space = false
spot.avoid_peers = true            # 退到生命條下方，而不是蓋住它們
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)

• 它一開始是隱藏的 — 要呼叫 show()。它沒有自己的計時器；如果提問會過期，請自己加一個。
• 它的按鈕不會關閉它 — 由動作決定。×（set_closable(true)）會發出 closed。
• fit_width(width) 設定寬度，並依字型預測高度，所以依它排版的東西不會在下一格跳一下。
• 它的表面跟隨 hud_alpha — 它是 HUD 的一部分，不是視窗。

GoBanner 與工具提示

GoBanner.make("You're offline.", [{"text": "Retry", "action": reconnect}], GoIconSet.WARNING) 就放在頁面裡、 內容的上方，從不逾時；按下按鈕就會關閉它，除非那顆按鈕帶有 "keep": true。 GoStyle.tooltip_node(text) 是 _make_custom_tooltip() 應該回傳的東西 — 底板由引擎繪製 （TooltipPanel），文字由 gohud 繪製，超過 260dp 就換行。工具提示是給滑鼠用的；玩家需要的東西絕不要藏在它後面。

導覽與主控台

GoCoachMark — 帶玩家認識真正的控制項

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."}])

• 真正的控制項周圍一個圈，再加上旁邊的一張卡片。按下目標就會往下一步（靠它的 pressed 訊號，或步驟裡的 "signal"）；卡片上有「下一步」與「略過」。隱藏的目標會被跳過。
• 卡片會避開畫面中間（avoid_center_band）、HUD 錨點與 keep_clear。
• 只要有任何 GoSurface 開著，導覽就會隱藏並等待。返回鍵或 Esc 會以 finished(false) 結束它。
• 它沒有自己的圖層 — 請最後才加入它，或放在 HUD 之上的圖層裡。

GoConsole — 開發時用的作弊

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()

圖層 200 — 在所有東西之上，所以你可以蓋在對話方塊上除錯 — 而且場景樹暫停時它照樣執行。輸入時，指令面板會 提示指令；上下方向鍵瀏覽歷史紀錄；Esc 關閉它。沒有內建的快速鍵：請自己綁一個。

圖層、返回鍵與輸入

有東西開著時玩家碰得到什麼，由三條規則決定：誰在最上面、誰握有返回鍵、 誰接住點按。

誰在最上面

這個順序是刻意安排的：訊息條回報的是剛剛發生的事，所以蓋在抽屜上也要讀得到；錨定卡片屬於剛按下的東西， 所以待在它上面；對話方塊提出問題，把兩者都蓋住；主控台蓋住一切，因為它是其他東西都出問題時你要打開的那一個。

誰握有返回鍵

• 只有最上層的視窗會回應。在開著的視窗當中，圖層最高的那一個（同一層時取場景樹中最晚加入的） 接收 Esc、遊戲手把的取消鍵（ui_cancel）、Android 返回鍵與遮罩點按。疊起來的視窗一次關一個， 絕不會一起關掉。
• Android 返回鍵會延後一格才處理，所以按一下絕不會關掉兩個視窗。
• 只要有任何握有返回鍵的東西開著，Android 返回鍵就不會結束應用程式（GoBackPolicy 計算持有者， 並在最後一個關閉後還原 quit_on_go_back）。你自己的彈出視窗如果接管了返回鍵，應該呼叫 GoBackPolicy.acquire() 與 release() — 在 _exit_tree 裡也要呼叫。
• 有視窗開著時，抽屜、導覽與表單都會讓路 — 返回鍵先交給視窗。
• GoConfig.close_on_back（預設開啟）是視窗這一項的開關。

誰接住點按

• 視窗蓋住整個畫面並擋下輸入 — 透明遮罩也一樣。它開著時，較低圖層上的任何東西都按不到； 它上面的圖層（例如訊息條）仍然按得到。
• 滑鼠滾輪與雙指縮放手勢同樣停在視窗上：捲過清單的盡頭也絕不會捲動到遊戲。
• 不經過控制項的遊戲輸入 — 用來移動的 _unhandled_input、拖曳鏡頭 — 應該暫停： if GoSurface.is_any_open(): return。這涵蓋了對話方塊、底部面板、錨定卡片與組合方塊；抽屜則要另外問它的 is_open()。
• 訊息條、提示條、提示卡片與導覽標記只在它們自己的卡片上接收輸入；其他地方的輸入都交給遊戲。

焦點

用指標打開的視窗不會把焦點放在任何東西上 — 觸控時不會閃出焦點框。用鍵盤或遊戲手把打開時，關閉按鈕 （或 initial_focus）取得焦點。視窗開著時焦點留在視窗裡，關閉後回到原本握有 焦點的那個控制項。對話方塊每次都會把焦點放在確定按鈕上。

暫停遊戲

暫停場景樹也會暫停彈出視窗 — 只有主控台照常運作。做暫停選單時，請替它的圖層設定 process_mode = PROCESS_MODE_ALWAYS；這樣遊戲停下來時，視窗、它的按鈕與返回鍵都會繼續運作。

同一個彈出視窗，每一種外觀

本頁開頭的那個確認對話方塊，蓋在同一個遊戲上，只換了預設集。程式碼一模一樣 — 其餘都交給佈景主題、外觀與圖示。

每種外觀改了什麼

用外觀打扮彈出視窗

外觀決定佈景主題碰不到的那些部分。下面這些掛鉤是彈出視窗會呼叫的 — 在你自己的 GoSkin 子類別裡覆寫它們；預設它們什麼都不做。

要透明到什麼程度

每一類彈出視窗各自依循自己的不透明度，所以 HUD 卡片可以保持通透，而對話方塊保持實心：視窗、底部面板、對話方塊、 錨定卡片與組合方塊依循 panel_alpha；抽屜與導覽卡片依循 card_alpha；提示卡片與 主控台依循 hud_alpha；訊息條與提示條依循 notice_alpha；選單依循 popup_alpha。Material 與兒童外觀 讓它們全部不透明；漫畫外觀也一樣，只有提示卡片與主控台是 92%；街機外觀同樣如此，只是這兩者是 94%。用 GoConfig.container_alpha_overrides 覆寫某一類，用 container_alpha（一個比例 — 0.95）覆寫全部，或用某個視窗自己的 alpha 覆寫單一視窗。只有表面會變淡；文字 絕不會變成半透明。不透明度詳解 →

影響每個彈出視窗的設定

GoConfig（GoUi.config）的欄位。其中幾個在視窗建立時就會被複製，所以請在 建立 UI 之前設定 — 或在改動之後呼叫 GoUi.refresh()。

常用寫法

複製、貼上、改改文字就好。這裡的每一個呼叫都對照過原始碼。

把價格寫進去的購買確認

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)

附固定「儲存」按鈕的設定視窗

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)

說得出哪裡錯的表單

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())

在底部面板裡選日期

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)

暫停選單

func pause() -> void:
    get_tree().paused = true
    var layer := CanvasLayer.new()
    layer.layer = 50
    layer.process_mode = Node.PROCESS_MODE_ALWAYS      # 遊戲暫停時也繼續執行
    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)

等彈出視窗關閉後才回應的遊戲操作

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

常見陷阱

• GoSurface 從不自己釋放。請連接 close_requested，否則按 × 不會有任何反應。
• 在 add_child 之後才設定的選項 — scrim_transparent、show_header、resizable、 scroll_body，以及 GoDialogs 的 layer_index 與 max_width — 都不會套用。
• 第二個 confirm() 會立刻回傳 false。如果兩個問題可能撞在一起，請打開 queue_when_busy。
• Enter 會確認。焦點在確定按鈕上，破壞性對話方塊也一樣。
• 底部面板上的返回鍵會關閉整個底部面板，而不是退出子頁面。
• Esc 不會關閉抽屜，而且 is_any_open() 也看不到它。
• 錨定卡片或組合方塊的清單會擋住遊戲，直到它關閉為止，即使遮罩是透明的 — 而一張 dismissable = false 又沒有標題的錨定卡片，畫面上沒有任何東西能關閉它。
• 提示卡片一開始是隱藏的，而且沒有逾時。
• seconds: 0 又沒有按鈕的訊息條永遠不會離開。而且預設情況下，它會接住落在卡片上的點按。
• 沒有人知道的長按，就是沒有人用的功能。請同時顯示一個 ⋯。
• 場景樹暫停時，你的彈出視窗也會暫停。請替它的圖層設定 PROCESS_MODE_ALWAYS。
• 沒設寬度的提示條會縮到最窄 — 請用 preferred_width()。
• 絕不在訊息條裡發問，絕不用對話方塊發通知。問題被忽略就消失了；消息則不該讓遊戲停下來。