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 下的日期选择器——键帽日期格，选中的日子是上色按键 — `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 下的范围滑块——墨线滑槽上的两个墨线手柄 — `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 把这些偏差集中到一处处理。

每个尺寸都是一个令牌

间距、圆角和字号都按名字取用，而不是写死数字。换掉主题，整个画面跟着一起变。

看得见的大小 ≠ 按得到的大小

关闭按钮看上去是 36dp，触摸目标却有 48dp。密集的快捷槽互相重叠时，中心更近的那个接住这次点按。

刘海与键盘

HUD 各部件待在安全区域之内，虚拟键盘弹出时输入框会抬到键盘上方。

返回只关掉一层

Esc 和安卓返回键只关闭最上面那一层。叠起来的窗口不会一起消失。

提示条从不抢走输入

隔着消息条按下去，底下的按钮照样收到。焦点也不会被夺走。

图标按名字取用

控件只认识 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 生成主题、控件贴图和皮肤旋钮，随后这套预设就会出现在选择器里。全部设置项与旋钮 →

皮肤 —— Theme 够不着的地方

皮肤管着摇杆、快捷槽的面、引导标记的光圈、标签片、骨架屏、内联提醒、分隔线和分节标题。继承它，只重写你想改的部分。

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	GoSnackbar —— 会自己找位置的消息条
`GoSpinner`	Control	GoSpinner —— 看不到尽头的等待
`GoBadge`	PanelContainer	GoBadge —— 未读的小圆点、NEW 角标、99+

表单与列表

类	基类	作用
`GoField`	VBoxContainer	GoField —— 会出错的那一行
`GoInputGroup`	HBoxContainer	GoInputGroup —— 和按钮焊在一起的输入框
`GoCombobox`	Button	GoCombobox —— 能搜索的选择器
`GoCodeInput`	VBoxContainer	GoCodeInput —— 兑换码和礼品码
`GoTable`	VBoxContainer	GoTable —— 可排序的表头、可选中的行
`GoPagination`	HBoxContainer	GoPagination —— 页码，或者一行“更多”

游戏真正用得上的形态

类	基类	作用
`GoRewardCalendar`	VBoxContainer	GoRewardCalendar —— 每日签到
`GoRadar` · `GoDonut`	Control	GoRadar 和 GoDonut —— 一眼看完的属性
`GoCarousel`	VBoxContainer	GoCarousel —— 横幅和角色选择
`GoKbd`	HBoxContainer	GoKbd —— 不会骗人的按键提示

盖在屏幕之上

类	基类	作用
`GoDrawer`	CanvasLayer	GoDrawer —— 侧边抽屉
`GoPopover`	RefCounted	GoPopover —— 贴着控件的卡片
`GoContextMenu`	RefCounted	GoContextMenu —— 长按与右键
`GoConsole`	CanvasLayer	GoConsole —— 开发者控制台

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

按下就是平的

其余的交给皮肤描线

窗口有标题框

白天黑夜都清晰可读

布局不变

三个设置和一次调用

放进游戏里是什么样子

它替你接手了什么

每个尺寸都是一个令牌

看得见的大小 ≠ 按得到的大小

刘海与键盘

返回只关掉一层

提示条从不抢走输入

图标按名字取用

十四种外观，一行代码

可读性靠量出来

安装 gohud

快速上手

换外观 —— 换颜色，也换形状

中世纪合集

同一个界面，在手机上和在桌面上

同一个面板，不同的外观

皮肤 —— Theme 够不着的地方

控件

等待、告知、计数

表单与列表

游戏真正用得上的形态

盖在屏幕之上

Go HUD Skill

可读性是量出来的，不是看出来的

检查、发布与这个网站

发布版本

这个网站

夜里：`arcade_dark`

夜里：`comic_dark`