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)、UnityUnityTheme(.uss、ScriptableObject.asset)、UnrealUnrealTheme(来自头文件和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 中,而不是添加到单个页面。