三层结构

一套预设把三层打包在一起。留空的字段会回退到默认值。

层	决定什么	怎么改
`Theme`	颜色、尺寸、文字缩放，以及引擎自己绘制的一切的形状 —— 按钮面板、输入框、标签页、开关贴图	手写一份 `.tres`，或用 `tools/make_theme.py` 生成
`GoSkin`	由代码绘制的一切的形状 —— 摇杆、快捷槽的面、引导标记的光圈、标签片、骨架屏、分隔线、分节标题	继承它，只重写你在意的那几个方法
`GoIconSet`	按名字取用的图标 —— 84 个默认图形，或者中世纪图标集覆盖其上的 16 个雕刻图形。可以是贴图包，也可以是图标字体；调用方的代码完全一样	提供一整套，或者只覆盖其中几个名字

为什么光有 Theme 还不够。 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 预设的 gohud 控件画廊 — `default_dark`

使用 default_light 预设的 gohud 控件画廊 — `default_light`

使用 scifi_dark 预设的 gohud 控件画廊 — `scifi_dark`

使用 scifi_light 预设的 gohud 控件画廊 — `scifi_light`

使用 medieval_dark 预设的 gohud 控件画廊 — `medieval_dark`

使用 medieval_light 预设的 gohud 控件画廊 — `medieval_light`

使用 material_light 预设的 gohud 控件画廊 — `material_light`

使用 material_dark 预设的 gohud 控件画廊 — `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 控件画廊 — `arcade_light`

使用 arcade_dark 预设的 gohud 控件画廊 — `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 指定各自的字体。

测试套件对两个变体都检查了什么。 中世纪皮肤确实被选中；菜单和 HUD 面板是锻造边框，且纹饰只出现在菜单上；标题使用 Cinzel 而正文保持继承来的字体；雕刻图标以 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_light 下的 gohud 画廊——胶囊按钮、填充卡片和描边输入框 — `material_light`

material_dark 下的 gohud 画廊 — `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` 上。

规范为可读性让路的地方。M3 把禁用状态的标签淡化到 38%；gohud 把它保持在 4.5:1，好让它依然读得清。消息条保留浅色底板，因为它的文字颜色是控件自己挑选的令牌——换成反色底板，就会变成深色文字压在深色底上。 tools/check_contrast.py 会像测量其他外观一样测量这两种外观。

Roboto 采用 SIL Open Font License 1.1 授权（assets/fonts/roboto/OFL.txt），只供 Material 预设使用。

儿童：玩具箱新

kids_light（奶油色和蜜桃色，主色为葡萄紫）和 kids_dark（蓝莓色底、阳光黄主色、薄荷色胶囊）是为儿童游戏和学习应用打造的外观——厚实、明亮、软弹，正是小手指忍不住想去按的那种东西。

GoUi.use_preset(&"kids_light")
# 或者：GoUi.use_preset(&"kids_dark")

kids_light 下的 gohud 画廊——蜡笔色的果冻糖按钮 — `kids_light`

kids_dark 下的 gohud 画廊——夜蓝色页面上的玩具箱 — `kids_dark`

有哪些变化

部分	在儿童外观中
每个表面	一颗果冻糖，由 `GoStyleBoxJelly` 绘制：粗描边、每个可按之物下方的一道实心底边、上浅下深的糖体，以及左上角的一道白色高光。按键、列表行、折叠标题、输入框、进度条、滑块和面板都用它。
按下	底边消失，表面沉到底边的位置，接着是一下果冻般的压扁——先短暂地变宽变扁，再弹性地回弹。gohud 创建的每个按钮都有这个效果；`reduce_motion` 会把它关掉。
输入框、标签页、进度条	输入框是同一种果冻向内凹进去的样子——一个下陷的凹槽。标签页是气泡，进度条带果冻般的高光。
颜色	每类控件各有自己的蜡笔颜色，由与所有外观相同的生成器挑选，所以每一道对比度检查依然成立。
窗口	窗口标题背后一条阳光色的彩带（夜间为薄荷色）——标题会缩小（最小到 15）以保持在一行内——以及一颗用危险色蜡笔画成、带白色叉号的圆形糖果关闭按钮。
皮肤部件	`GoSkinKids`：快捷槽是冷却时会下陷的糖果方块，徽章是贴纸，纸片和导航胶囊是小果冻，头像是圆糖果，摇杆是一道彩虹，图表用蜡笔色，警示和提示是带实心边框的贴纸便签。
不透明度	面板、卡片、提示和弹窗都不透明。

尺寸不变。描边和底边都画在每个控件自己的矩形之内，每个表面也保留主题给它的内边距，所以在别的外观下排好的界面会保持原有布局，自己固定尺寸的宿主项目测得的也还是同样的部件。你项目的字体同样保留，所以非拉丁文字照样能显示。

每套皮肤下的快捷槽、摇杆和纸片——默认、儿童、Material、中世纪和科幻 — 皮肤画出的部分——第二行是儿童外观

造一个自己的玩具箱

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_light 下的 gohud 画廊——带硬阴影的墨线按键、列表行和进度条 — `comic_light`

comic_dark 下的 gohud 画廊——夜色页面上的奶油色墨线 — `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_light 下的 gohud 画廊——天蓝色页面上，绿、蓝、红、淡紫色的上色按键和蓝色边框的 HUD 面板 — `arcade_light`

arcade_dark 下的 gohud 画廊——同样鲜亮的按键，放在夜色页面上 — `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() 什么也不做。

按键大小不变。底边和高光都画在每个按键自己的矩形之内，所以在别的外观下排好的界面会保持原有布局。面板会给内容多留一点内边距（卡片和 HUD 卡片 12dp，底部 15），让文字不碰到边框。你项目的字体同样保留。

街机皮肤画出的快捷槽、摇杆和纸片——带高光的键帽和一个带四个箭头的底盘 — 街机皮肤画出的部分

造一个自己的街机外观

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

挑一套

保留其中一项由自己决定

十四套内置预设

十四套并排对比

中世纪：铁、皮革与羊皮纸

造一个自己的王国

Material 3：面向应用界面的外观 新

有哪些变化

儿童：玩具箱 新

有哪些变化

造一个自己的玩具箱

漫画：粗墨线 新

有哪些变化

墨线与阴影设置

造一个自己的漫画外观

街机：上色的按键与厚实的面板 新

有哪些变化

给单个按键上自己的颜色

造一个自己的街机外观

Material 3：面向应用界面的外观新

儿童：玩具箱新

漫画：粗墨线新

街机：上色的按键与厚实的面板新