在遊戲裡長什麼樣
中世紀與科幻預設集 — 角色面板、背包與任務；表單、格狀排列與提示卡；稜角分明的面板與觸控操作。 切換預設集只要一行程式碼。
它替你處理掉的事
遊戲 UI 最花時間的從來不是按鈕長什麼樣 — 而是那些在不同裝置之間逐漸走樣的一切。 gohud 把這些走樣集中在一個地方處理。
每個尺寸都是一個 token
間距、圓角與文字大小都用名稱呼叫，不寫死成數字。換一份佈景主題，整個畫面就跟著動。
看得到的尺寸 ≠ 按得到的尺寸
關閉按鈕看起來是 36dp，觸控範圍卻是 48dp。快捷格擠在一起而互相重疊時，中心比較近的那一個接下這次按壓。
瀏海與鍵盤
HUD 零件待在安全區域內，虛擬鍵盤跳出來時輸入欄會升到它上面。
返回一次只關一層
Escape 與 Android 的返回鍵只關掉最上層那一層介面。疊在一起的視窗不會一起消失。
訊息條不會搶走輸入
按在訊息條上，底下的按鈕照樣收得到。焦點也不會被拿走。
圖示按名稱索取
控制項只認得 GoIconSet.CLOSE。換掉整組圖示，所有圖案都跟著換，一行程式碼都不必動。
六種外觀，一行切換
GoUi.use_preset() 一次換掉佈景主題、外觀與圖示 — 圓角、切角的科幻，或鍛造的中世紀框。
清晰度是量出來的
每一份佈景主題都對照 WCAG 檢查過，包含按鈕的各種狀態，以及半透明 HUD 面板疊在純白與純黑上的情形。
安裝 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 | 羊皮紙、墨水與青銅，配上同樣的鍛造框 |
default_dark — 圓角，柔和的藍色強調色
default_light — 同樣的形狀，淺色調色盤
scifi_dark — 切角，青色霓虹
scifi_light — 同樣稜角分明的形狀，藍圖調色盤這四張是同一個藝廊畫面。沒有一行程式碼不同 — 只有預設集的名稱不同。 按鈕圓角、切換開關的形狀、清單列與輸入框邊框全都一起改變。
中世紀系列
medieval_dark 把鐵與皮革配上古金色；medieval_light 用的是羊皮紙
與墨水。選單框上有一顆鉚釘和一小塊角落裝飾，而始終顯示的 HUD 保持安靜；
16 個雕刻圖示重畫了物品名稱，只有標題與副標題用到內附的 Cinzel 字型。
medieval_dark — 鐵與皮革
medieval_light — 羊皮紙與墨水兩張圖都是 examples/medieval/medieval.tscn，全部用標準控制項組成。
中世紀指南，以及怎麼打造自己的王國 →
同一個畫面，在手機與在桌機
藝廊那幾張是直向手機。下面是同樣的程式碼跑在 1280×800 — 內容停在好讀的寬度（480dp） 並置中，HUD 則待在角落。表單會繞開浮動的 HUD 零件，但在本來就沒擋到時不會移動： 硬推的話，寬螢幕上的內容就會歪掉。
default_dark · 1280×800
scifi_dark · 1280×800同一個面板，不同外觀
可以從 專案設定 → gohud → Theme → Preset 挑一個，或設定 GoConfig.preset。
明確填入 theme、skin 或 icons 會蓋過預設集，
所以你可以拿一個預設集來，只覆寫其中一項。
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 | 帶鉚釘、角落雕刻、斜角高光與材質紋理的鍛造框 |
這三種都能序列化進 Theme 資源 — 這正是佈景主題改得了形狀、而不只是顏色的原因。
GoSkinSciFi 與 GoSkinMedieval 是內附的子類別。
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 | 開發者主控台 |
AI SKILL
gohud 內建 AI 技能：完整 API、可直接執行的範本與預覽啟動器。把下面這一段貼給你的編碼代理，它就會裝好 gohud 並知道怎麼用。
可讀性是量出來的，不是用眼睛估的
「好看」是品味；「看得清楚」量得出來。淺灰色的文字在好螢幕上看起來沒問題， 到了白天的手機上就消失 — 用眼睛挑，遲早會踩到這一步。
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 | 這個網站的連結、錨點、頁面語言、詞彙表與旋鈕表格 |
發行版本
cat addons/gohud/package.json # { "version": "1.1.0" }
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 工作流程會把那個資料夾發佈成網站根目錄。