一個預設集把三層綁成一組。留空的欄位會退回使用預設值。
| 層 | 決定什麼 | 怎麼改 |
|---|---|---|
Theme |
顏色、尺寸、文字比例，以及引擎畫出來的一切的形狀 — 按鈕面板、輸入欄、分頁、切換開關的圖檔 | 自己寫一份 .tres，或用 tools/make_theme.py 產生一份 |
GoSkin |
程式碼畫出來的一切的形狀 — 搖桿、快捷格的面、導覽標記的圈、標籤片、骨架佔位、分隔線、區段標題 | 繼承它，只覆寫你在意的那幾個方法 |
GoIconSet |
用名稱取用的圖示 — 84 張預設圖案，或中世紀組疊在上面的 16 張雕刻圖案。可以是材質包，也可以是圖示字型；呼叫端的程式碼兩種都一樣 | 換上一整組，或只覆寫其中幾個名稱 |
StyleBoxFlat 只有圓角這一種角 —
把半徑設成零就變直角；中間什麼都沒有。斜切的角、單獨一道加粗的邊、外側的光暈：引擎一個都畫不出來。
而搖桿與導覽標記是在 _draw() 裡畫的，佈景主題根本伸不進去。
挑一個
GoUi.use_preset(GoThemePresets.SCIFI_DARK)這一行就換掉佈景主題、外觀與圖示。從編輯器要挑的話，用
專案設定 → Gohud → Theme → Preset；從設定資源則是 GoConfig.preset。
只留一個欄位給自己
GoUi.use_preset(GoThemePresets.SCIFI_DARK)
GoUi.config.icons = my_icons # 圖示用你的，其餘全部用預設集的明確設定 theme、skin 或 icons 會蓋過預設集。
內建的十四種預設集
| 預設集 | 面板 | 外觀 · 圖示 |
|---|---|---|
default_dark · default_light | 圓角的 StyleBoxFlat 面板，搭配分級的陰影刻度；主要按鈕會浮起，按下時沉下去 | GoSkin · 84 個預設圖示 |
scifi_dark · scifi_light | 切角的 GoStyleBoxCut 面板，帶霓虹邊與光暈；焦點記號用 GoStyleBoxBracket | GoSkinSciFi — 六邊形搖桿 · 預設圖示 |
medieval_dark · medieval_light | 鍛造的 GoStyleBoxMedieval 框 — 鐵與皮革，或羊皮紙 — 選單上還有鉚釘與角落裝飾 | GoSkinMedieval · 16 個雕刻圖示疊在預設之上 |
material_light · material_dark 新 | 給應用畫面的 Material 3 Expressive — 48dp 觸控區裡 40dp 的膠囊按鈕、28dp 對話方塊、填色卡片、外框輸入欄、Expressive 滑桿；應用元件（導覽列、頂端應用列、FAB、搜尋列、方塊標籤、進度、日期選擇器）依循 M3 元件權杖 | GoSkinMaterial · 預設圖示 |
kids_light · kids_dark 新 | 給兒童——玩具箱：粗描邊，每個按鍵下都有一道實心底邊，按下時會陷進去；凹陷的輸入框、泡泡分頁、果凍進度條；每類控制項各有一種蠟筆顏色，糖果般的快捷格、貼紙徽章、彩虹搖桿和蠟筆色圖表。尺寸和專案字型保持不變。 | GoSkinKids · 預設圖示 |
arcade_light · arcade_dark 新 | 由 GoStyleBoxArcade 繪製的街機：每個按鍵都以由上到下的漸層、一道白色高光與按下時會陷進去的底邊上色，裝在藏青色的墨線描邊裡，標籤是帶墨線描邊的白字 — 主色綠色，按鍵藍色，危險紅色，小按鍵淡紫色。厚實的面板是一圈彩色外框圍著淺色內芯；視窗有金色標題橫幅與圓形的紅色關閉鍵。 | GoSkinArcade · 預設圖示 |
comic_light · comic_dark 新 | 由 GoStyleBoxComic 繪製的漫畫分鏡：每個表面都有粗墨線描邊與硬陰影，按下時陰影消失；描了墨線的開關、核取方塊與滑桿把手，視窗有黃色的標題框。描邊粗細、陰影大小以及是否顯示陰影，都是 GoConfig 設定。 | GoSkinComic · 預設圖示 |
十四種並排比較
同一個藝廊畫面，只換了預設集的名稱 — 控制項的程式碼一行都沒變。 每張都是直拿的手機，390×844。
default_dark
default_light
scifi_dark
scifi_light
medieval_dark
medieval_light
material_light
material_dark
kids_light
kids_dark
comic_light
comic_dark
arcade_light
arcade_dark中世紀：鐵、皮革與羊皮紙
medieval_dark 把暗鐵與皮革配上古金色。medieval_light
用的是羊皮紙與墨水。兩者都用 GoSkinMedieval、現有的控制項，以及 16 個帶雕刻細節的
原創圖示；導覽類圖示則退回使用原本那一組。
GoUi.use_preset(GoThemePresets.MEDIEVAL_DARK)
# 或：GoUi.use_preset(GoThemePresets.MEDIEVAL_LIGHT)要在建立 UI 之前挑好預設集。明確指定的 GoConfig.theme、
skin 或 icons 依然優先。開啟
res://addons/gohud/examples/medieval/medieval.tscn 並按 F6，就能看到可運作的
角色面板、行囊與任務日誌。裡面的按鈕會切換變體，也會打開物品細節。
選單框上有一顆鉚釘與一小塊角落裝飾；始終顯示的 HUD 則保持安靜的邊。
生命、魔力與體力分別用紅、藍與橄欖綠填色。Cinzel 只用在標題與副標題；
內文文字維持宿主／預設字型。內附字型的授權放在
assets/fonts/cinzel/OFL.txt。
雕刻組重畫了 bag、book、box、coin、crown、
flag、heart、key、map、potion、shield、
star、sword 與 user，另外加上 scroll 與 seal。
其他每一個名稱都退回預設組，所以 close 與 settings 在每一種預設集裡都維持原本的
圖案。Cinzel 只涵蓋拉丁字母；在地化的標題請透過 shape.fonts 指定自己的字型。
DPITexture 匯入；實際的快捷格有用到該外觀；
改動複製出來的外觀的旋鈕，效果會傳到快捷格而不必更動預設集；切換回去時，預設與科幻的幾何形狀都能復原。
打造一個自己的王國
python3 addons/gohud/tools/new_theme.py kingdom --from medieval_dark
# 編輯 themes/palettes/kingdom.json，然後：
python3 addons/gohud/tools/make_theme.py kingdom
godot --headless --path . --import
# 在 GDScript 中，建立控制項之前：
GoUi.use_preset(&"kingdom")JSON 佈景主題可以繼承其他 JSON 佈景主題。省略的值沿用上層的設定； 循環繼承會被拒絕。產生出來的預設集會保留上層的圖示組。
| 設定 | 效果 |
|---|---|
shape.material | 0：鐵 · 1：皮革 · 2：羊皮紙。控制表面的紋路。 |
shape.grain_alpha | 紋理的不透明度。想要乾淨的表面就設成 0。 |
shape.ornament_scale · shape.bevel_strength | 選單角落裝飾的大小，以及斜角高光的強度。 |
shape.fonts | 把 title、subtitle、caption、body 與 button 這幾個角色對應到附加元件本地的 res:// 字型檔。省略的角色沿用繼承來的字型。 |
skin.dials | 快捷格圓角、鉚釘顯示與否、紋理與高光。下面的完整表格列出每一個旋鈕。 |
Material 3：給應用畫面的外觀 新
material_light 與 material_dark 把 Material 3 Expressive 帶進 gohud — M3 元件的形狀、尺寸與
字體排印，每一個數值都讀自官方的 M3 權杖集（material-web，
tokens/versions/latest）。當某個畫面應該讓人覺得像應用程式、而不是遊戲選單時，就用它們：
商店、收件匣、帳號與設定頁面、排行榜、配套應用程式。
GoUi.use_preset(GoThemePresets.MATERIAL_LIGHT)
# 或：GoUi.use_preset(GoThemePresets.MATERIAL_DARK)material_lightmaterial_dark
GoDialogs · material_light
GoDialogs · material_dark改了什麼
| 部分 | 在 Material 3 裡 |
|---|---|
| 按鈕 | 膠囊形（全圓角）。底板高 40dp，置中放在 48dp 的觸控目標裡，所以按壓範圍並不會縮小；緊湊按鈕的底板是 32dp。標籤使用字重 500 的 Roboto。 |
| 對話方塊與底部面板 | 28dp 圓角（extra-large）、24dp 內距與 24sp 的標題 — GoDialogs、GoSurface、GoSheet，以及建立在它們之上的每一種彈出視窗。 |
| 卡片 | 12dp 圓角、16dp 內距的填色卡片。 |
| 輸入欄與滑桿 | 外框輸入欄；把手較高的 Expressive 滑桿。 |
| 方塊標籤與區段按鈕 | 8dp 圓角（small）。 |
| 應用元件 | GoNavBar、GoAppBar、GoFab、GoSearchBar、方塊標籤、GoProgress 與 GoDatePicker 依循 M3 元件權杖。 |
| 字型 | 標題、副標題、說明文字與按鈕使用內附的 Roboto。內文保留你專案的字型，所以韓文、日文、中文或阿拉伯文照樣畫得出來。 |
| 不透明度 | 每塊面板都不透明 — M3 的表面是實心的。（預設、科幻與中世紀的面板是 80% 不透明，所以遊戲會透出來。） |
| 外觀 | GoSkinMaterial：抽屜是 M3 的強制回應側邊面板，主控台的表面是 M3 的浮動工具列，橫幅放在 surface_container_low 上。 |
tools/check_contrast.py 會像量其他外觀一樣量這兩種外觀。
Roboto 採用 SIL Open Font License 1.1 授權（assets/fonts/roboto/OFL.txt），只供 Material
預設集使用。
兒童：玩具箱 新
kids_light（奶油色與蜜桃色，主色是葡萄紫）與 kids_dark（藍莓色底、陽光黃主色、
薄荷色膠囊）是為兒童遊戲與學習應用程式打造的外觀 — 厚實、明亮、軟 Q，正是小小手指忍不住想按的那種東西。
GoUi.use_preset(&"kids_light")
# 或：GoUi.use_preset(&"kids_dark")kids_lightkids_dark
GoDialogs · kids_light
GoDialogs · kids_dark改了什麼
| 部分 | 在兒童外觀裡 |
|---|---|
| 每個表面 | 一顆果凍糖，由 GoStyleBoxJelly 繪製：粗描邊、每個可按之物下方的一道實心底邊、上淺下深的糖體，以及左上角的一道白色高光。按鍵、清單列、摺疊標題、輸入欄、量條、滑桿與面板全都用它。 |
| 按下 | 底邊消失，表面沉到底邊的位置，接著是一下果凍般的壓扁 — 先短暫地變寬變扁，再有彈性地彈回來。gohud 建立的每顆按鈕都有這個效果；reduce_motion 會把它關掉。 |
| 輸入欄、分頁、量條 | 輸入欄是同一種果凍往內凹的樣子 — 一個下陷的凹槽。分頁是泡泡，量條帶果凍般的高光。 |
| 顏色 | 每類控制項各有自己的蠟筆顏色，由和所有外觀相同的產生器挑選，所以每一道對比度檢查依然成立。 |
| 視窗 | 視窗標題後面一條陽光色的緞帶（夜間是薄荷色）— 標題會縮小（最小到 15）以保持在一行內 — 以及一顆用危險色蠟筆畫成、帶白色叉號的圓形糖果關閉按鈕。 |
| 外觀部件 | GoSkinKids：快捷格是冷卻時會下陷的糖果方塊，徽章是貼紙，方塊標籤與導覽膠囊是小果凍，頭像是圓糖果，搖桿是一道彩虹，圖表用蠟筆色，警示與提示是帶實心邊框的貼紙便條。 |
| 不透明度 | 面板、卡片、提示與彈出視窗都不透明。 |
打造一個自己的玩具箱
python3 addons/gohud/tools/new_theme.py candy --from kids_light
# 編輯 themes/palettes/candy.json，然後：
python3 addons/gohud/tools/make_theme.py candy
GoUi.use_preset(&"candy")漫畫：粗墨線 新
comic_light（紙張般的奶油色頁面上放白色面板，主色是鈷藍）與 comic_dark（夜色頁面上的石板色面板、
奶油色描邊、黃色主色）把每個表面都畫成一格漫畫分鏡 — 粗墨線描邊，背後襯一道硬陰影。
GoUi.use_preset(&"comic_light")
# 或：GoUi.use_preset(&"comic_dark")comic_lightcomic_dark
GoDialogs · comic_light
GoDialogs · comic_dark改了什麼
| 部分 | 在漫畫外觀裡 |
|---|---|
| 每個表面 | 由 GoStyleBoxComic 繪製：墨色的粗描邊裡填著表面顏色，往右下方投出一道硬陰影。按鍵、清單列、輸入欄、分頁、量條、滑桿、面板與彈出視窗全都用它。 |
| 按下 | 陰影消失，表面沉到陰影的位置。 |
| 控制項 | 開關、核取方塊、選項按鈕與滑桿把手也都描了墨線，各帶一道小陰影。 |
| 視窗 | 視窗標題後面一個黃色的標題框，以及一顆描了墨線的圓形關閉按鈕。 |
| 外觀部件 | GoSkinComic：快捷格、方塊標籤、徽章、頭像、提示、導覽列、FAB 與日期格子都描了墨線；搖桿的握把會投下陰影；圖表用醒目的原色。 |
| 不透明度 | 面板、卡片、提示與彈出視窗都不透明；HUD 卡片為 92% 不透明。 |
墨線與陰影設定
三個 GoConfig 設定會一次改變所有漫畫表面。不需要重建任何東西 — 設定的同時畫面就會重畫。
GoUi.config.comic_border_width = 2.0 # 描邊（dp）— 預設 3
GoUi.config.comic_shadow_size = 6.0 # 陰影（dp）— 預設 4
GoUi.config.comic_shadow = false # 所有地方都不要陰影單一控制項可以不管設定，自行其是：
GoStyle.comic_shadow(skip_button, false) # 這顆按鈕平貼著
GoStyle.comic_shadow(card, true, true) # 這張卡片與其中的一切保留陰影
GoStyle.comic_border(title, 5.0) # 只給這一個加粗描邊
打造一個自己的漫畫外觀
python3 addons/gohud/tools/new_theme.py inked --from comic_light
# 編輯 themes/palettes/inked.json，然後：
python3 addons/gohud/tools/make_theme.py inked
GoUi.use_preset(&"inked")街機：上色的按鍵與厚實的面板 新
arcade_light（天藍色頁面上的白色面板）與 arcade_dark（夜色頁面上的藏青色面板）
把每個畫面都打扮成一台街機：每個按鍵都上了色 — 從淺色頂端過渡到深色底部的漸層、一道白色高光與按下時會陷進去的底邊，
裝在藏青色的墨線描邊裡 — 而且每塊面板都很厚，一圈彩色外框圍著淺色內芯。
GoUi.use_preset(&"arcade_light")
# 或：GoUi.use_preset(&"arcade_dark")arcade_lightarcade_dark
GoDialogs · arcade_light
GoDialogs · arcade_dark改了什麼
| 部分 | 在街機外觀裡 |
|---|---|
| 按鍵 | 由 GoStyleBoxArcade 繪製：漸層主體、繞著左上角的一道白色高光、顏色更深的底邊與藏青色墨線描邊。主要按鍵是綠色，一般按鍵與選中的分頁是藍色，危險按鍵是珊瑚色與紅色，小按鍵與其餘分頁是淡紫色。 |
| 標籤 | 每個上色按鍵上都是帶墨線描邊的白字。每種顏色都會被調整，直到標籤在漸層的每個高度上都看得清 — 像 WCAG 一樣把描邊算作字母的一部分，達到 4.6:1 或更高。 |
| 按下 | 底邊消失，按鍵陷進原位，再彈回來。 |
| 面板 | 面板、卡片、HUD 卡片與彈出視窗都很厚：一圈自帶高光與底邊的彩色外框（視窗 6dp，卡片與 HUD 卡片 4，選單與提示 3），圍著一個帶墨線的淺色內芯。為了容納外框，內距會稍微加大，文字永遠不會碰到外框。 |
| 輸入欄與量條 | 輸入欄與量條的凹槽是凹陷的內芯；量條的填色是一根帶高光的上色管，用的是它那種顏色的明亮填色。 |
| 視窗 | 一條金色橫幅，上面是帶墨線描邊的白色標題，以及一顆畫著白色叉號的圓形紅色關閉鍵。 |
| 外觀部件 | GoSkinArcade：快捷格與方塊標籤是鍵帽，冷卻中的格子亮起金邊，徽章是淺色牌子，提示框圍著各自顏色的外框，選中的卡片亮起金邊，FAB 是金色按鍵，搖桿是有四個箭頭的高光底盤。 |
| 不透明度 | 面板、卡片、提示與彈出視窗都不透明；HUD 卡片為 94% 不透明。 |
替單一按鍵上自己的顏色
佈景主題依種類替按鍵上色。如果選單裡每個按鍵都想要自己的顏色，就一個一個上色 — 懸停時的表面會稍亮一點， 按下時稍深一點，停用時維持暗淡：
menu.add_child(GoStyle.arcade_paint(GoStyle.button("Resume", _resume, GoStyle.Tone.PRIMARY), Color("#4ACB3E")))
menu.add_child(GoStyle.arcade_paint(GoStyle.button("Shop", _shop), Color("#FF8A1E")))
GoStyle.arcade_paint(stage_card, Color("#E3343D"), true) # 面板的外框，以及其中的每個按鍵arcade_paint() 什麼也不做。
打造一個自己的街機外觀
python3 addons/gohud/tools/new_theme.py cabinet --from arcade_light
# 編輯 themes/palettes/cabinet.json — *_vivid 顏色就是上色用的顏色 — 然後：
python3 addons/gohud/tools/make_theme.py cabinet
GoUi.use_preset(&"cabinet")