Communitygithub.com

UI 预览

在游戏项目中,在引擎中实现之前,构建一个可调节的 HUD 元素、菜单、提示、过渡或屏幕效果的 HTML 预览,并将用户调节的值转换为构建规范。

UI 预览 是什么?

UI 预览技能是一种系统化的工作流程,用于在游戏项目中设计、原型和调整 UI 元素或视觉效果。它要求所有 UI 更改在构建之前必须通过 HTML 预览页进行可视化调节并保存为 `values.json` 文件,该文件作为唯一规范,确保每个数字值都成为引擎编辑器暴露的属性或主题条目,避免代码中的魔术数字。该技能适用于 Godot、Unity 和 Unreal 引擎,并提供引擎特定的脚本(`apply_godot.py`、`apply_uss.py`、`apply_unreal.py`)将批准的数值直接写入项目文件。工作流程包括:获取真实游戏截图作为背景、编写带有调节面板(滑块、颜色、变体、状态)的预览页、生成包含所有状态的审查表、通过实时保存和版本控制进行迭代,以及最终的构建与预览对比验证。它还支持可访问性(减动/减闪)切换,并要求像素级精确匹配游戏字体、颜色和像素艺术渲染。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomas-ratz/game-ui-proof/tree/HEAD/skills/ui-preview

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

UI 预览 是做什么的?

任何改变游戏 UI 外观的内容,都必须先让用户调节 HTML 预览并按下“保存”按钮,然后才能开始构建。保存的 values.json 就是规范:其中的每个数字都成为编辑器暴露的属性或主题条目,绝不会是代码中的魔术数字。没人能看到的更改不需要预览。

工作顺序: 要预览什么 → 该位置的截图 → 预览页面 → 审查表 → 用户调节并保存 → 从 values.json 构建 → 构建与预览对比表。

1. 初始化(每个项目仅一次)

  • 将 assets/kit/ 复制到 docs/mockups/kit/(另一个文件夹也可:向脚本传递 --mockups)。不用的引擎文件可以省略:godot_theme.js + apply_godot.py(Godot)、unity_theme.js + apply_uss.py(Unity)、unreal_theme.js + apply_unreal.py(Unreal)。对于 Godot:还要将 assets/godot/project.js 复制到 kit/ 中并填写内容(字体、按键图符);Godot 页面会从那里加载它。
  • project.css 是唯一需要编辑的 kit 文件:游戏的字体(@font-face)和面板调色板,包括 --display。kit.js 会在绘制前加载所有声明的字体。
  • 将预览文件排除在引擎的导入之外(Godot:在 docs/mockups/ 中创建一个空的 .gdignore),并将 docs/mockups/*/values.draft.json 和 docs/mockups/*/shots/ 添加到 .gitignore。
  • 启动项目根目录的服务:python docs/mockups/kit/serve.py(仅使用标准库),然后打开 http://127.0.0.1:8765/docs/mockups/<feature>/。页面通过相对路径加载游戏资源,并将调节内容保存到磁盘(§5)。
  • 将项目自身的样式读入面板:Godot GodotTheme(主题 .tres)、Unity UnityTheme(.uss、ScriptableObject .asset)、Unreal UnrealTheme(来自头文件和 Default*.ini 的 C++ 类默认值,导出为 JSON/CSV 的 DataTable)。参见 references/engines.md;每个引擎在 assets/<engine>/ 下都有一个可用的示例页面。

2. 询问,然后获取真实背景

  • 询问是哪个屏幕、元素或效果,以及什么情况下出现,除非已经很明确。
  • 以游戏视口大小(项目的分辨率设置;也是 manifest 的 stage)截取该位置(隐藏 UI)的一张截图,以及一张显示当前 UI 的基线截图。使用引擎运行的小脚本(Godot 模板:assets/godot/game_shots.gd;其他:references/engines.md),并将其放在预览旁边,用于构建检查。
  • 只有在无法通过脚本到达该位置时才向用户索取截图。对于全新且没有可截图内容的情况,或者无法在此运行引擎时,使用纯色或模拟背景,并在状态说明中注明。

3. 编写页面

将 assets/template/(或 assets/<engine>/)复制到 docs/mockups/<feature>/。页面格式、面板规范、Kit.spec 和 URL 参数见 references/kit.md。

  • manifest.json: 标题、stage([宽, 高])、states(玩家可能看到的每种情况:空、满、聚焦、禁用、最长文本、动画中间帧;每个状态都有说明和 shotTime)、variants(有真实选择时 2–4 个,每个有名称和备注)、recommend(推荐的变体及原因,一两行)。
  • index.html: Kit.start({ feature, images, groups, variants, draw })。为超过约六个值的组添加 section,以便面板可以折叠它们。每个组对应这些值在引擎中的存储位置(脚本类、主题类型、着色器),每个键对应构建时将使用的属性名称,使用引擎的单位。draw(ctx, values, s) 必须是 s.t 的纯函数(使用 t % length 循环动画)。
  • 使用游戏自身的外观,而非近似: 游戏字体和大小、主题颜色(新颜色是一个提议:说明它会加入哪个调色板)、通过相对路径引用的真实资源、真实文本和数字,以及显示实际绑定按键的提示。
  • 像素艺术:整像素,无抗锯齿(kit 的默认设置)。
  • 动画按其真实持续时间和缓动进行。任何会晃动、漂移、闪烁或闪烁的内容,在一个 preview: true 组中添加“减动”/“减闪”切换开关,显示这些设置将其变成什么样子。
  • 当调节现有内容时,变体 a 应完全按当前状态重新绘制。将其与基线截图对比,直到它们匹配,否则其他每个变体都会与错误的基线进行比较。
  • 多个预览需要共用内容时,放在 kit 中的共享文件中,不要复制到每个页面。

4. 审查表

  • python docs/mockups/kit/shots.py <feature>(需要 Chrome、Edge 或 Chromium,以及 Pillow ≥ 10.1)会生成 shots/<variant>_<state>.png 并拼接为 sheet.png。它使用保存的 values.json 作为其变体(--defaults 使用页面的默认值),如果页面失败则非零退出,并在该截图上绘制错误信息。
  • 在展示之前查看表;以 2 倍放大裁剪需要决策的部分:文本被裁剪或重叠、错误字体、超出舞台、动画卡在平淡时刻(移开其 shotTime)。
  • 发送表、实时 URL 和需要做出的决策,并附上你的建议。

5. 读取调节结果

  • 在用户调节时,每一次更改都会写入 <feature>/values.draft.json。每当用户询问你的意见时,读取该文件;永远不要从草稿构建。
  • 保存(或 Ctrl/Cmd+S)会写入 <feature>/values.json(已批准的规范),页面随后基于它打开:有差异的行会被标记,↺ 将单个值恢复,重置将所有值恢复。仅预览的值不会被标记或保存。
  • 没有 serve.py 时,调节内容仅存在于浏览器中:保存会复制 JSON(并将其保持为该浏览器的默认值),用户将其粘贴到聊天中,你将其保存为 values.json。
  • 格式:{"feature", "variant", "values": {Group: {Key: value}}};仅预览的组会被省略。

6. 从规范构建

  • Godot: python docs/mockups/kit/apply_godot.py <feature> 列出规范在主题 .tres 中以及在每个组命名的脚本的 [Export] / @export 默认值中所做的更改,在 <name>.gdshader 组的统一默认值中、尚未导出的键以及覆盖这些属性的场景中所做的更改。--write 应用。
  • Unity: python docs/mockups/kit/apply_uss.py <feature> 对 USS 自定义属性(uss: 组)执行相同操作。ScriptableObject 值手动应用。
  • Unreal: python docs/mockups/kit/apply_unreal.py <feature> 列出规范在每个组的 C++ 类中所做的更改:配置类的 Config/Default<Config>.ini 覆盖(--target header 改为重写声明中的默认值)、尚未设置 UPROPERTY 的键(附有待粘贴的声明)以及需要手动设置的默认值。--write 应用。DataTable 值通过重新导入编辑后的导出应用。
  • 构建尚不存在的内容:颜色、字体和面板放在引擎的主题或样式系统中;大小、偏移、持续时间和强度作为编辑器暴露的属性,按 JSON 分组,批准值作为默认值。
  • 在运行中的游戏中验证:截取预览中每个状态的截图,并制作 <feature>/build_vs_preview.png,游戏截图与预览截图并排放置。修复差异。说明哪些未检查;浏览器和引擎文本抗锯齿效果不同,因此判断位置和大小,而不是边缘像素。
  • 对已批准外观的后续更改是一个新的轮次:预览、审查表、保存、构建。

规则

  • 预览保留在仓库中:它们记录了 UI 为何如此。提交 sheet.png 和 values.json;shots/ 和草稿会被重新生成。
  • 在 values.json 存在之前不构建;永远不要从草稿构建。
  • 如果 kit 缺少预览所需的内容,则将其添加到 kit 中,而不是添加到单个页面。

相关技能