gohud — Godot 4 的 HUD 與 UI 套件

新增：街機、漫畫、Material 3，以及給孩子的外觀

四個新系列加入了預設、科幻與中世紀的行列 — 現在共有十四種內建外觀，每種都有深色與淺色。每個控制項、彈出視窗與 HUD 元件都能直接套用，程式碼一行都不用改：換掉預設集，整個畫面就跟著變。

material_light 下的 gohud 藝廊 — 膠囊按鈕、填色卡片與 Material 3 配色 — `material_light`

material_dark 下的 gohud 藝廊 — 同樣的 Material 3 形狀，換成深色基準配色 — `material_dark`

kids_light 下的 gohud 藝廊 — 陽光般明亮的頁面上，蠟筆色的厚實果凍按鈕 — `kids_light`

kids_dark 下的 gohud 藝廊 — 同一個玩具箱，放在夜藍色的頁面上 — `kids_dark`

comic_light 下的 gohud 藝廊 — 紙張般的奶油色頁面上，粗墨線描邊與硬陰影 — `comic_light`

comic_dark 下的 gohud 藝廊 — 夜色頁面上的奶油色描邊與黃色主色 — `comic_dark`

arcade_light 下的 gohud 藝廊 — 天藍色頁面上，帶漸層與高光的上色按鍵，以及藍色外框的厚實 HUD 面板 — `arcade_light`

arcade_dark 下的 gohud 藝廊 — 同樣鮮亮的按鍵，放在夜色頁面上 — `arcade_dark`

Material 3 — 給應用畫面

對照官方 M3 權杖逐項量過的 Material 3 Expressive：48dp 觸控目標裡附 40dp 底板的膠囊按鈕、 28dp 的對話方塊與底部面板、填色卡片、外框輸入欄，以及 Expressive 滑桿。應用元件 — 導覽列、頂端應用列、FAB、搜尋列、方塊標籤、進度與日期選擇器 — 依循 M3 元件權杖，標題使用內附的 Roboto。適合商店、設定、收件匣，以及每一個應該讓人覺得像應用程式的畫面。

兒童 — 玩具箱

為孩子而做：每個按鍵、清單列與面板都是一顆果凍糖，帶粗描邊與一道實心底邊，按下時會陷進去；每類控制項各有自己的蠟筆顏色。快捷格是糖果方塊，徽章是貼紙，搖桿是一道彩虹，視窗有陽光色的標題緞帶與圓形的糖果關閉按鈕，按下去還會被壓扁。尺寸與你專案的字型都維持原樣。

漫畫 — 粗墨線

每個表面都是一格漫畫分鏡：粗墨線描邊裡填著表面顏色，背後襯一道硬陰影，表面被按下時陰影隨之消失。一個設定開關所有陰影，另外兩個設定決定描邊粗細與陰影大小，一次呼叫就能對單一控制項做同樣的事。視窗有黃色的標題框。

街機 — 上色的按鍵

每個按鍵都上了色 — 漸層、一道白色高光與按下時會陷進去的底邊，全都裝在藏青色的墨線描邊裡 — 標籤是帶墨線描邊的白字：開始用綠色，其餘用藍色，刪除用紅色。面板很厚，一圈彩色外框圍著淺色內芯；視窗有金色的標題橫幅與一個圓形的紅色關閉鍵。

GoUi.use_preset(GoThemePresets.MATERIAL_LIGHT)   # 或 MATERIAL_DARK
GoUi.use_preset(&"kids_light")                   # 或 &"kids_dark"
GoUi.use_preset(&"comic_light")                  # 或 &"comic_dark"
GoUi.use_preset(&"arcade_light")                 # 或 &"arcade_dark"

Material 3 詳解 → · 兒童外觀詳解 → · 街機外觀，逐一控制項看 ↓ · 漫畫外觀，逐一控制項看 ↓ · 同一個彈出視窗在全部十四種外觀下的樣子 →

街機：上色的按鍵與厚實的面板

這款最新的外觀把每個畫面都打扮成一台街機。每個按鍵都上了色 — 從淺色頂端過渡到深色底部的漸層、一道白色高光與按下時會陷進去的底邊，全都裝在藏青色的墨線描邊裡 — 標籤是帶墨線描邊的白字。 每塊面板都很厚：一圈自帶高光的彩色外框圍著淺色內芯。 arcade_light 在天藍色頁面上放白色面板；arcade_dark 在夜色頁面上放藏青色面板。下面每一張圖都是真實的 gohud 畫面 — 同樣的程式碼，只差一行預設集。

GoUi.use_preset(&"arcade_light")   # 或 &"arcade_dark"

arcade_light 下的 gohud 藝廊 — 天藍色頁面上，綠、藍、紅、淡紫色的上色按鍵與藍色外框的 HUD 面板 — `arcade_light` · 藝廊

arcade_light 下的底部面板 — 從底邊升起的厚實外框面板，裡面是一排排鍵帽 — `GoSheet`

arcade_light 下的導覽標記 — 指向一個按鍵的帶外框泡泡 — `GoCoachMark`

arcade_dark 下的側邊抽屜 — 調暗的畫面上，一塊放著導覽列項目的藏青色面板 — `GoDrawer`

arcade_dark 下的彈出泡泡 — 錨定在開啟它的按鍵上的帶外框泡泡 — `GoPopover`

arcade_dark 下的提示對話方塊 — 藍色外框的藏青色面板上，金色 Level up! 橫幅、紅色關閉鍵與綠色 Great 鍵 — `GoDialogs.alert()`

arcade_light 下的底部提示列 — 沿底邊的棕色外框白色面板，帶一個 Undo 動作 — `GoSnackbar`

每個按鍵都上了色

arcade_light 下的按鈕 — 綠色的開始、藍色的詳情、白色外框按鍵、珊瑚色的刪除、紅色的永久刪除、淡紫色的精簡按鍵與灰色的停用按鍵，每個都在藏青色描邊裡以漸層、高光與底邊上色 — `GoStyle.button()`

arcade_light 下的分頁 — 選中的分頁是藍色上色按鍵，其餘是淡紫色按鍵 — `GoStyle.tabs()`

arcade_light 下的分段控制項 — 各自獨立的上色按鍵，選中的那個是藍色並被按下 — 分段按鍵

arcade_light 下的開關與核取方塊 — 開啟時是帶高光的綠色軌道，關閉時是淡紫色，核取方塊是綠色 — 開關與核取方塊

arcade_light 下的卡片 — 帶高光與底邊的厚藍外框裡的淺色內芯 — `GoStyle.card()`

arcade_light 下的表單 — 凹陷的白色輸入欄、一個開關與綠色的儲存鍵 — `GoForm`

arcade_light 下的選擇網格 — 鍵帽，選中的那個在綠色底色上鑲著金邊 — `GoStyle.choice_grid()`

arcade_light 下的格位網格 — 由帶高光的鍵帽組成、標著堆疊數量的物品欄 — `GoSlotGrid`

arcade_light 下的清單列 — 每一列都是帶圖示的淺色鍵帽 — 清單列

arcade_light 下的日期選擇器 — 鍵帽日期格，選中的日子是上色按鍵 — `GoDatePicker`

arcade_light 下的滑桿 — 墨線凹槽裡帶高光的藍色管與圓形鍵帽滑鈕 — `GoStyle.slider()`

arcade_light 下的選項按鈕群組 — 圓形鍵帽，選中的那個帶藍色圓點 — `GoStyle.radio_group()`

arcade_light 下的篩選標籤 — 鍵帽標籤，選中的那個染成藍色並帶勾，可移除的標籤帶叉號 — `GoStyle.filter_chip()`

arcade_light 下的搜尋列 — 墨線描邊裡凹陷的白色輸入欄，帶搜尋圖示與篩選圖示 — `GoSearchBar`

arcade_light 下的步驟條 — 每一步都是淺色鍵帽，展開的那一步顯示綠色的 Next 鍵 — `GoStepper`

arcade_light 下的排行榜表格 — 每隔一列是凸起的鍵帽 — `GoTable`

arcade_light 下的底部導覽列 — 選中分頁的圖示在藍色鍵帽膠囊上，紅色計數徽章 — `GoNavBar`

arcade_light 下的時間選擇器 — 大鍵帽上的小時與分鐘，錶盤上方的 AM 與 PM 鍵 — `GoTimePicker`

arcade_light 下的驗證碼輸入 — 八個鍵帽格，正在輸入的那格鑲著金邊 — `GoCodeInput`

arcade_light 下的滾輪選擇器 — 鍵帽色帶上的選中數量，其餘數字向上下漸隱 — `GoWheelPicker`

夜裡：`arcade_dark`

在深色頁面上，墨色變得深得多，成了頁面本身，而按鍵的顏色依舊鮮亮。

arcade_dark 下的按鈕 — 同樣鮮亮的顏色，放在夜色頁面上 — 夜裡的 `GoStyle.button()`

arcade_dark 下的 HUD 量條 — 凹槽裡的紅色 HP、藍色 MP 與綠色 XP 管 — `GoBar`

arcade_dark 下的 HUD 卡片 — 遊戲畫面上，厚藍外框裡的藏青色內芯 — `GoStyle.hud_panel()`

arcade_dark 下的快捷格 — 標著堆疊數量的鍵帽，冷卻中的格子鑲著金邊 — `GoSlot`

arcade_dark 下的虛擬搖桿 — 墨線圓環裡帶高光的底盤、四個箭頭與一個鍵帽握把 — `GoJoystick`

arcade_dark 下的提示框 — 以黃、綠、紅、藍外框圍起的小面板 — 提示框

arcade_dark 下的懸浮動作按鈕 — 帶高光的金色上色按鍵 — `GoFab`

arcade_dark 下的獎勵日曆 — 鍵帽日期格，今天鑲著金邊 — `GoRewardCalendar`

arcade_dark 下的分段控制項 — 選中的 Day 鍵塗成藍色，Week 與 Month 是淡紫色，文字全是白色 — 分段按鍵

arcade_dark 下的分頁檢視 — 上色的分頁按鍵，下面是藏青色鍵帽組成的清單列 — `GoTabView`

arcade_dark 下的捲動清單 — 藏青色鍵帽上的清單列與一排篩選標籤，選中的那個是藍色 — `GoScroll`

arcade_dark 下的開關與核取方塊 — 開啟時是帶高光的綠色軌道，關閉時是淡紫色 — 開關與核取方塊

arcade_dark 下的稀有度標籤 — 從 Common 到 Cursed 的上色小牌 — `GoStyle.chip()`

arcade_dark 下的格位網格 — 由藏青色鍵帽組成、帶白色圖示與堆疊數量的物品欄 — `GoSlotGrid`

arcade_dark 下的範圍滑桿 — 深色凹槽裡，兩個帶高光的滑鈕之間的藍色區段 — `GoRangeSlider`

arcade_dark 下的分頁導覽 — 目前頁面是綠色上色按鍵 — `GoPagination`

arcade_dark 下的徽章 — 圖示上方以墨線描邊的珊瑚色小牌 — `GoBadge`

街機外觀是怎麼做到的

表面

每個按鍵與面板都是一個 GoStyleBoxArcade：墨線描邊、漸層主體、底邊與高光，全都畫在控制項自己的矩形裡 — 按鍵在各種狀態下大小不變，按下只是讓它陷進去。

看得清的標籤

帶墨線描邊的白色標籤，在描邊能隔開的任何顏色上都看得清 — WCAG 把描邊算作字母的一部分。每種顏色都會被調整，直到它的標籤在漸層的每個高度上都超過 4.6:1。

視窗

視窗標題以帶墨線描邊的白字放在金色橫幅上，旁邊是一個圓形的紅色關閉鍵。對話方塊、底部面板、抽屜與彈出泡泡都是帶厚外框的面板。

單一按鍵可以有自己的顏色 — 例如暫停選單裡一個橘色的商店鍵：

menu.add_child(GoStyle.arcade_paint(GoStyle.button("Shop", _shop), Color("#FF8A1E")))

街機外觀詳解 → · 同一個彈出視窗在全部十四種外觀下的樣子 →

漫畫：粗墨線與硬陰影

漫畫外觀把每個表面都畫成一格漫畫分鏡 — 粗墨線描邊裡填著表面顏色，往右下方投出一道紮實的硬陰影。comic_light 在紙張般的奶油色頁面上用黑墨描畫，主色是鈷藍； comic_dark 在夜色頁面上用奶油色墨線描畫，主色是黃色。下面每一張圖都是真實的 gohud 畫面 — 同樣的程式碼，只差一行預設集。

GoUi.use_preset(&"comic_light")   # 或 &"comic_dark"

comic_light 下的 gohud 藝廊 — 紙張般的奶油色頁面上，帶硬陰影的墨線按鍵、清單列與量條 — `comic_light` · 藝廊

comic_dark 下的 gohud 藝廊 — 夜色頁面上的奶油色墨線與黃色主色 — `comic_dark` · 藝廊

comic_light 下的底部面板 — 從底邊升起的墨線面板，裡面是描了墨線的清單列 — `GoSheet`

comic_light 下的導覽標記 — 指向一顆按鈕的墨線對話框 — `GoCoachMark`

comic_dark 下的側邊抽屜 — 調暗的畫面上，一塊放著導覽列的墨線面板 — `GoDrawer`

comic_dark 下的彈出泡泡 — 錨定在開啟它的那顆按鈕上的墨線泡泡 — `GoPopover`

按鈕、開關、分頁、滑桿、卡片、表單、表格、選擇器與方塊標籤全都描上了墨線 — 不必一個個去設定樣式。按下一個按鍵，它的陰影就消失：表面像蓋章一樣沉進自己的位置。停用的表面失去陰影並變淡，能按的與不能按的一眼就分得清。

comic_light 下的按鈕 — 主要、次要、外框、危險、精簡、無框與停用按鍵，每個都有粗黑描邊與硬陰影 — `GoStyle.button()` — 所有種類

comic_light 下的開關與核取方塊 — 描了墨線的軌道與圓鈕，打了勾的墨線方框 — 開關與核取方塊

comic_light 下的選項按鈕 — 墨線圓環，選中的那個帶實心圓點 — 選項按鈕

comic_light 下的分頁 — 選中的分頁是一塊墨線面板，其餘的落在一條墨線底線上 — `GoStyle.tabs()`

comic_light 下的分段控制項 — 墨線格子，選中的那格被填滿 — 分段膠囊

comic_light 下的滑桿 — 墨線滑槽、細細的強調色填色與墨線把手 — `GoStyle.slider()`

comic_light 下的卡片 — 帶粗描邊與硬陰影的白色面板 — `GoStyle.card()`

comic_light 下的表單 — 附提示的墨線輸入欄、一個開關與墨線的儲存按鍵 — `GoForm`

comic_light 下的清單列 — 每一列都是一條墨線長條，附圖示、副標題或危險標籤 — 清單列

comic_light 下的表格 — 墨線分隔線上方是表頭，每一列分數都是一條墨線長條 — `GoTable`

comic_light 下的日期選擇器 — 墨線日期格子，選中的那天被填滿 — `GoDatePicker`

comic_light 下的時間選擇器 — 墨線的時、分方框，AM 與 PM 按鍵和一個錶盤 — `GoTimePicker`

comic_light 下的步驟條 — 墨線步驟列，完成的步驟打了勾，接下來的步驟變淡 — `GoStepper`

comic_light 下的篩選與輸入方塊標籤 — 墨線膠囊，選中的篩選項著色並打勾 — 篩選方塊標籤

comic_light 下的導覽列 — 頂端一條墨線，目前的分頁在墨線膠囊裡，Alerts 上有徽章 — `GoNavBar`

comic_light 下的輸入群組 — 輸入欄與它的傳送按鍵焊成一個墨線整體 — `GoInputGroup`

comic_light 下的分割按鈕 — 動作與選單箭頭是兩個墨線半邊 — `GoSplitButton`

comic_light 下的分頁導覽 — 目前頁面是一個帶硬陰影的墨線按鍵 — `GoPagination`

夜裡：`comic_dark`

在深色頁面上黑色描邊會消失不見，所以 comic_dark 用奶油色畫描邊，並投下一道帶著同樣墨色的淡淡陰影。HUD 元件 — 快捷格、量條、搖桿與獎勵日曆 — 遵循同樣的規則。

comic_dark 下的按鈕 — 夜色頁面上的奶油色描邊、黃色主要按鍵與淡淡的硬陰影 — 夜裡的 `GoStyle.button()`

comic_dark 下的快捷格 — 附堆疊數與冷卻的墨線方塊，亮起的格子鑲著黃邊 — `GoSlot`

comic_dark 下的 HUD 量條 — 奶油色墨線槽裡的 HP、MP 與 XP — `GoBar`

comic_dark 下的虛擬搖桿 — 奶油色圓環與一個投下陰影的握把 — `GoJoystick`

comic_dark 下的提示框 — 用奶油色墨線畫的資訊、成功、警告與危險面板 — 提示框

comic_dark 下的格子網格 — 由墨線方塊組成的背包 — `GoSlotGrid`

comic_dark 下的獎勵日曆 — 墨線日期格子，已領取的日子打了勾，今天鑲著黃邊 — `GoRewardCalendar`

comic_dark 下的稀有度方塊標籤 — 墨線膠囊，各自染上自己的顏色 — 方塊標籤

comic_dark 下的範圍滑桿 — 墨線滑槽上的兩個墨線把手 — `GoRangeSlider`

comic_dark 下的搜尋列 — 附搜尋與篩選圖示的墨線長條 — `GoSearchBar`

comic_dark 下的懸浮動作按鈕 — 奶油色墨線與硬陰影襯托的黃色按鍵 — `GoFab`

漫畫外觀是怎麼做到的

所有表面共用一個 StyleBox

每個表面都是一個 GoStyleBoxComic：填色、描邊與陰影，都畫在控制項自己的矩形之內。它每次繪製時都從 GoConfig 讀取描邊與陰影的大小，所以改一個設定，整個畫面立刻一起變。

按下就是平的

按下的按鍵收起陰影，挪進陰影的位置。滑鼠停留時陰影保留；取得焦點時加一圈內側墨線環，絕不會蓋住描邊；停用的表面失去陰影並變淡。

其餘交給外觀描線

GoSkinComic 替程式碼畫出的部分描上墨線：快捷格、方塊標籤、徽章、頭像、提示、導覽列、FAB、日期格子，還有握把會投下陰影的搖桿。

視窗有標題框

視窗標題放在一個黃色標題框裡，就像漫畫裡的旁白框，旁邊是一顆描了墨線的圓形關閉按鈕。對話方塊、底部面板、抽屜與彈出泡泡都是不透明的墨線面板。

白天晚上都清楚好讀

兩套調色盤都和其他所有預設集一樣通過 WCAG 對比檢查，按下與停用的按鍵也不例外。當標題框的顏色與頁面太接近時，它的描邊會退回頁面顏色。

版面不變

描邊與陰影都收在每個控制項之內，內距維持佈景主題給的樣子，所以用別的外觀排好的畫面會維持原本的版面 — 你專案的字型也一樣。

三個設定與一次呼叫

三個 GoConfig 設定會一次改變所有漫畫表面。不需要重建任何東西 — 設定的同時畫面就會重畫。

GoUi.config.comic_border_width = 2.0   # 描邊（dp）— 預設 3
GoUi.config.comic_shadow_size = 6.0    # 陰影（dp）— 預設 4
GoUi.config.comic_shadow = false       # 所有地方都不要陰影

單一控制項可以不管設定，自行其是。把 true 當成最後一個引數傳入，就連它裡面的一切都包含在內。

GoStyle.comic_shadow(skip_button, false)     # 這顆按鈕平貼著
GoStyle.comic_shadow(card, true, true)       # 這張卡片與其中的一切保留陰影
GoStyle.comic_border(title, 5.0)             # 只給這一個加粗描邊

打造一個自己的漫畫外觀。tools/new_theme.py inked --from comic_light 會複製調色盤；改掉紙張、墨線與主色，再執行 tools/make_theme.py inked。墨線、陰影與外觀都會一併帶上。

漫畫外觀詳解 → · 同一個彈出視窗在全部十四種外觀下的樣子 →

在遊戲裡長什麼樣

中世紀與科幻預設集 — 角色面板、背包與任務；表單、格狀排列與提示卡；稜角分明的面板與觸控操作。切換預設集只要一行程式碼。

gohud 中世紀佈景主題 — 角色面板上有生命、魔力與體力量條，一只裝著快捷格的行囊，以及鍛金框內的任務日誌 — **中世紀** — 角色、背包與任務

gohud 中世紀佈景主題 — 輸入面板上有名稱欄位、切換開關、核取方塊與音量滑桿，一片方塊格狀排列，以及帶有接受與拒絕的組隊邀請提示卡 — **中世紀** — 表單、格狀排列與提示卡

gohud 科幻佈景主題 — 切角的觸控操作面板，內有六邊形搖桿、固定／跟隨／相對切換，以及圓形動作按鈕 — 科幻 — 稜角分明的面板與觸控操作

十四種預設集與切換方式 →

它替你處理掉的事

遊戲 UI 最花時間的從來不是按鈕長什麼樣 — 而是那些在不同裝置之間逐漸走樣的一切。 gohud 把這些走樣集中在一個地方處理。

每個尺寸都是一個 token

間距、圓角與文字大小都用名稱呼叫，不寫死成數字。換一份佈景主題，整個畫面就跟著動。

看得到的尺寸 ≠ 按得到的尺寸

關閉按鈕看起來是 36dp，觸控範圍卻是 48dp。快捷格擠在一起而互相重疊時，中心比較近的那一個接下這次按壓。

瀏海與鍵盤

HUD 零件待在安全區域內，虛擬鍵盤跳出來時輸入欄會升到它上面。

返回一次只關一層

Escape 與 Android 的返回鍵只關掉最上層那一層介面。疊在一起的視窗不會一起消失。

訊息條不會搶走輸入

按在訊息條上，底下的按鈕照樣收得到。焦點也不會被拿走。

圖示按名稱索取

控制項只認得 GoIconSet.CLOSE。換掉整組圖示，所有圖案都跟著換，一行程式碼都不必動。圖示 →

十四種外觀，一行切換

GoUi.use_preset() 一次換掉佈景主題、外觀與圖示 — 圓角、切角的科幻、鍛造的中世紀框、Material 3 的應用元件、兒童的果凍糖、漫畫的墨線，或街機的彩漆。

清晰度是量出來的

每一份佈景主題都對照 WCAG 檢查過，包含按鈕的各種狀態，以及半透明 HUD 面板疊在純白與純黑上的情形。

不啟用外掛程式也一樣能用。啟用之後會多一個 GoRuntime 自動載入，負責追蹤視窗大小、dp 縮放與鍵盤高度，另外還多了設定資源與預設集的專案設定 — 那些是方便，不是必要。

安裝 gohud

兩條路：讓 AI 代理替你裝，或把資料夾放進專案 —— 此外不必設定任何東西。

安裝

快速上手

五行程式碼就能顯示帶佈景主題的畫面。完整流程請見安裝頁。

快速上手

換外觀 — 顏色與形狀一起

Theme 只能重新樣式化引擎畫出來的東西。StyleBoxFlat 只有圓角這一種角，而搖桿、快捷格與導覽標記是用程式碼畫的 — 光靠佈景主題永遠改不了它們的形狀。所以 gohud 附上預設集：佈景主題、外觀與圖示組當成一個整體一起挑。

GoUi.use_preset(GoThemePresets.MEDIEVAL_DARK)   # 佈景主題、外觀與圖示一起換

預設集	外觀
`default_dark`	最初的 gohud — 圓角，柔和的藍色強調色
`default_light`	同樣的形狀，換成淺色調色盤
`scifi_dark`	切角，青色霓虹邊與光暈，六邊形搖桿，瞄準框角
`scifi_light`	同樣稜角分明的形狀，換成明亮的藍圖調色盤
`medieval_dark`	暗鐵與皮革、古金色框、鉚釘、雕刻圖示、Cinzel 標題
`medieval_light`	羊皮紙、墨水與青銅，配上同樣的鍛造框
`material_light` 新	給應用畫面的 Material 3 — 膠囊按鈕、28dp 對話方塊、填色卡片、應用的導覽列、FAB 與搜尋列、Roboto
`material_dark` 新	同樣的 Material 3 形狀，換成深色基準配色
`kids_light` 新	給孩子的玩具箱 — 帶粗描邊的果凍糖按鍵，下方一道底邊，按下時會陷進去；蠟筆色，陽光般明亮的頁面
`kids_dark` 新	同一個玩具箱，放在夜藍色的頁面上
`comic_light` 新	漫畫分鏡 — 每個表面都有粗墨線描邊與硬陰影，紙張般的奶油色頁面上放著白色面板；陰影、陰影大小與描邊粗細都是設定項
`comic_dark` 新	同樣的墨線，放在夜色頁面上 — 奶油色描邊與黃色主色
`arcade_light` 新	一台街機 — 每個按鍵都以漸層、高光與底邊上色，標籤是帶墨線描邊的白字；天藍色頁面上的厚外框面板，視窗有金色標題橫幅
`arcade_dark` 新	同樣鮮亮的按鍵，放在藏青色面板與夜色頁面上

套用 default_dark 預設集的 gohud 藝廊 — 圓角，藍色強調色 — `default_dark` — 圓角，柔和的藍色強調色

default_light 預設集 — 同樣的形狀，換成淺色調色盤 — `default_light` — 同樣的形狀，淺色調色盤

scifi_dark 預設集 — 切角與青色霓虹 — `scifi_dark` — 切角，青色霓虹

scifi_light 預設集 — 同樣稜角分明的形狀，換成藍圖調色盤 — `scifi_light` — 同樣稜角分明的形狀，藍圖調色盤

這四張是同一個藝廊畫面。沒有一行程式碼不同 — 只有預設集的名稱不同。按鈕圓角、切換開關的形狀、清單列與輸入框邊框全都一起改變。

中世紀系列

medieval_dark 把鐵與皮革配上古金色；medieval_light 用的是羊皮紙與墨水。選單框上有一顆鉚釘和一小塊角落裝飾，而始終顯示的 HUD 保持安靜； 16 個雕刻圖示重畫了物品名稱，只有標題與副標題用到內附的 Cinzel 字型。

medieval_dark — 角色面板、裝著快捷格的行囊與任務日誌 — `medieval_dark` — 鐵與皮革

medieval_light — 同樣的角色、行囊與任務畫面，畫在羊皮紙上 — `medieval_light` — 羊皮紙與墨水

兩張圖都是 examples/medieval/medieval.tscn，全部用標準控制項組成。中世紀指南，以及怎麼打造自己的王國 →

同一個畫面，在手機與在桌機

藝廊那幾張是直向手機。下面是同樣的程式碼跑在 1280×800 — 內容停在好讀的寬度（480dp）並置中，HUD 則待在角落。表單會繞開浮動的 HUD 零件，但在本來就沒擋到時不會移動：硬推的話，寬螢幕上的內容就會歪掉。

1280x800 的 default_dark — 內容置中，HUD 待在角落 — `default_dark` · 1280×800

1280x800 的 scifi_dark — 同樣的版面，換成切角面板與霓虹 — `scifi_dark` · 1280×800

同一個面板，不同外觀

default_dark 下的底部面板 — 預設 — 圓角卡片、固定的搜尋列與頁尾

scifi_dark 下的底部面板 — 頂端沿著邊緣有一道霓虹強調邊 — 科幻 — 頂部強調邊、切角、光暈

可以從 專案設定 → gohud → Theme → Preset 挑一個，或設定 GoConfig.preset。明確填入 theme、skin 或 icons 會蓋過預設集，所以你可以拿一個預設集來，只覆寫其中一項。

一份新的佈景主題就是一個 JSON 檔。new_theme.py kingdom --from medieval_dark 會寫出一份把每個繼承值都寫清楚的調色盤；make_theme.py kingdom 接著產生佈景主題、它的控制項圖檔與外觀旋鈕，這個預設集就會出現在選擇器裡。所有設定與旋鈕 →

外觀 — 佈景主題碰不到的地方

外觀掌管搖桿、快捷格的面、導覽標記的圈、標籤片、骨架佔位、行內提示、分隔線與區段標題。繼承它，只覆寫你想改的部分。

class_name MySkin extends GoSkin

func slot_box(accent: Color, lit: bool) -> StyleBox:
    var box := GoStyleBoxCut.new()
    box.bg_color = accent
    box.cut = 6.0
    box.edge_color = accent
    return box

類別	畫得出來的形狀
`GoStyleBoxCut`	斜切的角（切角）、一道加粗的強調邊、外側光暈
`GoStyleBoxBracket`	只有角落的記號，不把內容框起來
`GoStyleBoxMedieval`	帶鉚釘、角落雕刻、斜角高光與材質紋理的鍛造框
`GoStyleBoxJelly`	果凍糖 — 粗描邊、按下時會陷進去的實心底邊、上淺下深的糖體，以及一道白色高光
`GoStyleBoxComic`	漫畫分鏡 — 粗墨線描邊與硬投影，兩者的大小都在遊戲執行時由 `GoConfig` 決定
`GoStyleBoxArcade`	街機的按鍵或面板 — 漸層主體、白色高光、按下時會陷進去的底邊與墨線描邊；面板再加一圈厚厚的彩色外框圍著淺色內芯

這六種都能序列化進 Theme 資源 — 這正是佈景主題改得了形狀、而不只是顏色的原因。 GoSkinSciFi、GoSkinMedieval、GoSkinMaterial、GoSkinKids、GoSkinComic 與 GoSkinArcade 是內附的子類別。

每一種內附外觀畫出的快捷格、搖桿與方塊標籤 — 預設、兒童、Material、中世紀與科幻 — 外觀畫出的部分 — 預設、兒童、Material、中世紀、科幻

漫畫外觀畫出的快捷格、搖桿與方塊標籤 — 墨線描邊與硬陰影 — ……以及漫畫外觀

街機外觀畫出的快捷格、搖桿與方塊標籤 — 帶高光的鍵帽與一個有四個箭頭的底盤 — ……以及街機外觀

GoStyle.box() 一律回傳 StyleBoxFlat，因為呼叫端拿到它之後會去調整 bg_color 或 corner_radius。當自訂形狀必須保留時，請改用 GoStyle.surface()。

控制項

所有零件，一張表看完。逐一細看 → · 每個控制項都附一張圖 → · 彈出視窗與對話方塊完整指南 →

類別	基底	功能
`GoSurface`	Control	浮動卡片外殼 — 置中、靠下或錨定擺放，固定的頁首與頁尾，可捲動的本文，拖曳改變大小
`GoSheet`	CanvasLayer	從底部升起的頁面，位於自己的圖層上，所以會蓋在 HUD 之上
`GoDialogs`	Node	可以 `await` 的確認與提示；不可逆的動作用 `destructive`
`GoForm`	MarginContainer	限制寬度的表單，會避開虛擬鍵盤，加上 `avoid_hud` 還會避開 HUD
`GoScroll`	ScrollContainer	觸控捲動；捲軸縮進卡片的內距裡
`GoNotice`	PanelContainer	既不吃輸入也不吃焦點的訊息條
`GoPromptCard`	PanelContainer	不會擋住遊戲的提問卡
`GoCoachMark`	Control	指向真實控制項的導覽；按下目標就前進到下一步
`GoHudAnchor`	Control	把 HUD 零件釘在安全區域的九個位置之一
`GoBar`	Control	生命、魔力與經驗量條，數值變化帶緩動
`GoSlot`	Button	一格快捷格 — 圖示、數量、冷卻與快速鍵全在同一個面上
`GoJoystick`	Control	固定、跟隨或相對模式的虛擬搖桿
`GoIconButton`	Button	看起來小，按起來大
`GoStyle`	static	按鈕、清單列、輸入欄、標籤片、表格、分頁等等，都用同一套一致的做法產生

等待、告知、計數

類別	基底	功能
`GoSnackbar`	Node	會自己找位置的訊息
`GoSpinner`	Control	看不到盡頭的等待
`GoBadge`	PanelContainer	未讀圓點、「新」標籤、99+

表單與清單

類別	基底	功能
`GoField`	VBoxContainer	會出錯的那一列
`GoInputGroup`	HBoxContainer	和按鈕焊在一起的輸入欄
`GoCombobox`	Button	會搜尋的選擇器
`GoCodeInput`	VBoxContainer	優惠券與禮物碼
`GoTable`	VBoxContainer	可排序的標題列、可選取的資料列
`GoPagination`	HBoxContainer	頁碼，或是一列「更多」

遊戲真的會用到的形狀

類別	基底	功能
`GoRewardCalendar`	VBoxContainer	每日簽到
`GoRadar` · `GoDonut`	Control	一眼看完的能力值
`GoCarousel`	VBoxContainer	橫幅與角色選擇
`GoKbd`	HBoxContainer	不會說謊的按鍵提示

蓋在畫面上

類別	基底	功能
`GoDrawer`	CanvasLayer	側邊面板
`GoPopover`	RefCounted	釘住的卡片
`GoContextMenu`	RefCounted	長按與右鍵
`GoConsole`	CanvasLayer	開發者主控台

Go HUD Skill

gohud 內建 AI 技能：完整 API、可直接執行的範本與預覽啟動器。把下面這一段貼給你的編碼代理，它就會裝好 gohud 並知道怎麼用。

Go HUD Skill

可讀性是量出來的，不是用眼睛估的

「好看」是品味；「看得清楚」量得出來。淺灰色的文字在好螢幕上看起來沒問題，到了白天的手機上就消失 — 用眼睛挑，遲早會踩到這一步。

python3 addons/gohud/tools/check_contrast.py

十四種佈景主題中的每一組配色，以及每個按鈕狀態下的標籤與它所在的面板，都會對照 WCAG 量過。半透明的顏色會先合成到它真正的背景上 — 直接量它們，得到的比值會比畫面上看到的更好看。

所以文字顏色是推算出來的，不是挑出來的：產生器拿調色盤裡的值當起點，把它的明度推到在每一個可能落腳的面板上都達標為止。改調色盤，對比就跟著走。背後的規則與陷阱 →

檢查、發行與這個網站

一個進入點跑完所有檢查；每一部分都看得到別人看不到的東西。

bash addons/gohud/tools/check_all.sh

檢查	抓得到什麼
四種螢幕尺寸下的 `run_tests.sh`	控制項行為與版面、RTL 位置、鍵盤焦點、執行時的外觀對比、每一種預設集
`new_project_check.sh`	對宿主專案的隱藏相依；加上 `--zip` 檢查實際發行的內容，加上 `--export` 檢查 Web 建置
`check_contrast.py`	每份佈景主題檔的 WCAG 對比，含按鈕狀態與半透明面板
`check_generated.py` · `check_scaffold.sh`	產生的佈景主題與其調色盤相符；用完即丟的佈景主題能建置並通過對比檢查
`check_package.py`	採用 package.json 的版本號、變更紀錄搬移與 ZIP 內容，全都在暫時的副本上進行
`check_site.py`	這個網站的連結、錨點、頁面語言、詞彙表與旋鈕表格

最近一次記錄的執行 — 2026-09-13，Godot 4.7.2，macOS，Compatibility 繪製器。在空白專案中，於 390×844、844×390、768×1024 與 1280×800 下 438 項檢查全數通過；加上 GoRuntime 自動載入後再次 438 項全過；一次 Web 匯出；六種佈景主題的對比零失敗。實體 Android、iOS 裝置不在這次執行的範圍內。

發行版本

cat addons/gohud/package.json       # { "version": "1.1.0" }
bash addons/gohud/tools/release.sh  # 全部檢查 → ZIP → 在空專案中驗證
bash addons/gohud/tools/package.sh  # 1.1.0 → builds/1.1.0/gohud-1.1.0.zip

版本就是 package.json 裡寫的那個，打包絕不會自動調高。要發行新版本，先改這個數字。成功執行時會把 plugin.cfg 與 GoUi.VERSION 設成該版本，且只在該版本第一次打包時，把 CHANGELOG.md 中 Unreleased 的內容搬進一筆有日期的紀錄。同一版本再次打包會重新產生 ZIP 並取代舊的。執行失敗則什麼都不改。 ZIP 裡不含這個網站、測試、工具與 package.json。

這個網站

python3 addons/gohud/tools/make_site.py            # 詞彙表與外觀旋鈕表格，從原始碼產生
python3 addons/gohud/tools/check_site.py           # 連結、錨點、語言、詞彙表、產生的表格
bash addons/gohud/tools/site_shots.sh /tmp/shots   # 每一頁的桌機與手機螢幕截圖

這些頁面就是 www/ 底下的純 HTML — 根目錄是英文，ko/ 是韓文。一個 GitHub Actions 工作流程會把那個資料夾發佈成網站根目錄。

用一份資源驅動的遊戲 UI

新增：街機、漫畫、Material 3，以及給孩子的外觀

Material 3 — 給應用畫面

兒童 — 玩具箱

漫畫 — 粗墨線

街機 — 上色的按鍵

街機：上色的按鍵與厚實的面板

每個按鍵都上了色

夜裡：arcade_dark

街機外觀是怎麼做到的

表面

看得清的標籤

視窗

漫畫：粗墨線與硬陰影

每個控制項都描上墨線

夜裡：comic_dark

漫畫外觀是怎麼做到的

所有表面共用一個 StyleBox

按下就是平的

其餘交給外觀描線

視窗有標題框

白天晚上都清楚好讀

版面不變

三個設定與一次呼叫

在遊戲裡長什麼樣

它替你處理掉的事

每個尺寸都是一個 token

看得到的尺寸 ≠ 按得到的尺寸

瀏海與鍵盤

返回一次只關一層

訊息條不會搶走輸入

圖示按名稱索取

十四種外觀，一行切換

清晰度是量出來的

安裝 gohud

快速上手

換外觀 — 顏色與形狀一起

中世紀系列

同一個畫面，在手機與在桌機

同一個面板，不同外觀

外觀 — 佈景主題碰不到的地方

控制項

等待、告知、計數

表單與清單

遊戲真的會用到的形狀

蓋在畫面上

Go HUD Skill

可讀性是量出來的，不是用眼睛估的

檢查、發行與這個網站

發行版本

這個網站

夜裡：`arcade_dark`

夜裡：`comic_dark`