evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/zh-CN/game-ui-generator/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: game-ui-generator
+description: 通过 evomeme_generate_ui_components 生成可复用的游戏 UI 组件图片库，按需去底色并拆出独立 PNG。生成按钮、面板、进度条、滑块、图标槽等 UI 皮肤或为生成图配置三段切分、九宫格、平铺、填充和状态切换时使用。重点解释资源如何在游戏中拼装，并提供组件构造与生成提示词；整套界面布局和概念图使用 game-ui。
+---
+
+# 游戏 UI 组件库生成与使用
+
+生成可复用游戏 UI 图片素材时使用本技能。先决定图片在运行时如何变长、变高、填充和切换状态，再生成适合这种构造的底图。完整界面布局、信息层级和概念图使用 [游戏 UI 设计](../game-ui/SKILL.md)；本技能交付组件美术资源，不把界面截图当作可交互组件。
+
+## 工具实际执行什么
+
+`evomeme_generate_ui_components` 与画布调用同一个原有任务函数 `executeUiComponents`，继续复用已有 image 函数：一次 AI 生成组件素材表 → 非原生透明时本地色键去底色 → 按需把独立主体裁成 PNG。保留基础素材表、可选透明素材表和拆出的图片，保存到工作区 `assets/`。MCP 不调用其他 MCP。
+
+三段、九宫格、部件分离等建议只在本技能中维护，按实际任务写入用户 `prompt`，不要为此修改 image 函数或内置提示词。工具继续使用原有 22 类组件清单，没有 `components` 参数，用户提示词不替换固定清单。严格限定为单个按钮或少量部件时，通过 [通用图片生成技能](../game-asset-image-generator/SKILL.md) 使用 `evomeme_generate_game_image`，继续遵循本技能的构造建议；通用图片工具不会自动去底色或拆图。
+
+**自动拆图不等于三段切分或九宫格配置。** 自动拆图把一张素材表中的按钮、边框等分成独立图片；三段/九宫格是在某一张组件图片内部指定哪些部分可伸缩。工具不自动测量这些边距，也不输出控件代码、点击逻辑、语义文件名或引擎主题配置。
+
+## 先明确这些术语
+
+- **组件皮肤／素材表**：皮肤是按钮底板、边框等视觉图片；素材表是一张同时放置多个皮肤的图片，不具备交互逻辑。一个清单条目可能包含多个状态或部件，条目数不等于文件数。
+- **三段切分（3-slice）**：水平分为左端帽、中间、右端帽。端帽是需要保留形状的两端装饰；只改变中段宽度，适合固定高度、可变长度的按钮。竖向控件可按上、中、下处理。通常在同一图片上设置采样区域即可，不必真的另存三个文件。
+- **九宫格（9-slice / nine-patch）**：使用左、右、上、下四条边距分成九区，不是平均九等分。四角保持形状，上下边只沿水平方向延展，左右边只沿竖直方向延展，中央适配宽高，适合面板和可多行文本框。[Phaser 官方说明](https://docs.phaser.io/phaser/concepts/gameobjects/nine-slice)
+- **拉伸／平铺**：拉伸把区域缩放到目标尺寸，适合纯色、平滑渐变；平铺复制纹理片段，适合需要保留纹理尺度的像素纹理或重复花纹，重复边界必须连续。平铺不足一块时可裁切末块，或使用引擎提供的整块适配模式；不要拉长端帽。[Godot 的伸缩模式](https://docs.godotengine.org/en/stable/classes/class_styleboxtexture.html)
+- **切片边距／内容内边距**：前者决定源图中哪些边框不能变形，后者决定文字、图标与边框保持多少距离。二者可以不同，必须依据实际输出测量；提示词中的像素数不是已验证的切片数据。
+- **填充与遮罩（fill / mask）**：按数值只显示填充图片的一部分，例如血量 40% 时仅露出对应区域；遮罩限定可见范围。不要把整条血条连同边框横向压缩。动态文字、数值、选中标记和冷却效果通常由运行时叠加。
+- **状态变体**：普通、悬停、按下、焦点、禁用等外观。它们应保持同一尺寸和对齐基准，通过换图、着色或动画表达状态；触屏没有持续悬停，键盘/手柄焦点也不等于按下。[Unity 状态切换](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/script-SelectableTransition.html)
+
+## 按钮：两端固定，中间适配长度
+
+生成一张完整按钮底板，不画切割线，不让 AI 把三段分别散放。检查后在圆角和端部装饰之外选两条垂直切线：`左端帽 | 中段 | 右端帽`。文字和图标作为独立 UI 元素叠加，避免随底板拉长。
+
+例如，实际裁出的按钮为 240×64，检查后两端各需 24 像素，则原中段宽 192。显示为 360×64 时，两端仍各宽 24，中段显示宽 312。拉伸模式把中段适配到 312；平铺模式在 312 宽的区域重复中段或已验证的更小纹理单元，裁掉超出部分。**不是把整个 240×64 图片直接拉到 360×64，也不是固定切成三个等宽部分。**
+
+最小宽度既要容纳两端，也要容纳文字及内容内边距；允许正的中段宽度。按钮高度需要变化或文字需要多行时改用九宫格。精细纹样不一定可无缝重复；不能仅凭“平铺”提示词就认为纹理已连续。
+
+每种组件的结构和生成提示词见 [组件构造与提示词目录](references/component-patterns.md)。接入 Phaser、Unity、Godot 或 DOM 时读取 [切片与引擎接入](references/runtime-integration.md)。这些是主流引擎支持的常见做法，具体选择取决于组件形状和目标渲染器。
+
+## MCP 参数与参考准备
+
+| 参数 | 说明 |
+| --- | --- |
+| `prompt` | 可选，全局主题、画风、材质、配色、光照及构造约束。 |
+| `model` | 默认 `asset-max`，也支持 `asset-pro`、`asset-lite`。此流程原生透明仅 Max。 |
+| `size` | 素材表整体预设尺寸，默认 `1664x2496`；不是每个按钮的尺寸。使用模型支持的预设，Lite 不支持 `1024x1024`。 |
+| `reference_ids` | 工作区风格参考图 ID 数组，默认 `[]`；Pro 最多 10 张，Max/Lite 在此流程最多 14 张。 |
+| `transparent_background` | 默认 `false`，生成纯色底后自动色键；`true` 请求 Max 原生透明并跳过色键。 |
+| `background_color` | 默认 `#ff00ff`；`#RGB` 或 `#RRGGBB`，用于纯色底和色键，避开主体颜色。原生透明时不作为底色。 |
+| `auto_split` | 默认 `true`，分离检测到的主体，不补齐成相同尺寸。`false` 返回整张素材表，不改变固定生成清单。 |
+| `workspace_dir` | 工作区根目录绝对路径，建议显式指定；省略使用 MCP 当前目录。 |
+
+先将附件或外部参考复制到所选工作区 `assets/`，避免覆盖已有素材；只有可访问 URL 时先下载。确认文件真实可读，再传 `assets/ui/style.png` 这类工作区相对 ID。不能传原附件绝对路径、URL 或 Base64；已有 `asset_id` 直接复用。
+
+色键固定强度 80，按 Oklab 感知颜色距离处理近似底色，全图处理、柔化边缘，不开启去溢色（消除主体边缘的底色偏色）。它可能误删主体中的相近颜色；半透明玻璃、光晕和阴影优先考虑 Max 原生透明，并检查实际 alpha 通道。没有单独关闭默认色键或调强度的参数。
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "model": "asset-max",
+  "size": "1664x2496",
+  "transparent_background": true,
+  "auto_split": true,
+  "prompt": "手绘奇幻木质游戏 UI，统一暖棕木纹与金色细边，正面正交，部件之间留宽空隙，无文字数字与切割线。按钮完整底板各状态保持相同轮廓和端帽，中段可水平延展且不放独特花纹；面板固定四角装饰，中央留空；进度条空槽、满长度填充、外框分别绘制。"
+}
+```
+
+自动拆图需要至少检测到两个独立主体；内部孔洞、独立装饰或相邻粘连可能造成误分或合并，图片编号不表示组件类别。需要高细节的小批次时使用通用图片生成工具，明确目标部件并复用同一风格参考；不要承诺组件库工具可以精确指定子集。
+
+## 返回值与交付
+
+成功返回文本元数据，不包含图片字节或 Base64：`operation_id` 表示步骤，生成阶段的 `job_id` 表示一次远端生图。任务记录由原有任务服务管理，不承诺返回独立 `task_id` 字段。
+
+- `images`：最终使用的图片列表。拆图时是独立 PNG；不拆时是一张处理后的素材表。顶层 `asset_id` / `local_path` 对应列表第一张，不表示所有组件的合成图。
+- `generated`：原始素材表；`color_key`：去底色时返回的素材表。拆图前素材表取 `color_key`，没有时取 `generated`。
+- 文件条目含 `id` / `asset_id`、`local_path`、`mime_type` 及适用的步骤/远端任务 ID。色键和拆图输出为 PNG；本地处理结果不继承原图云端 URL，也不自动上传。需要 URL 时上传最终 `local_path`。
+- `auto_split`、`background_color`、`transparent_background`、`color_key_strength` 表示配置。一次调用只有一次 AI 生图，本地色键和裁切不增加次数。
+- 原有返回值没有 `sheet`、`outputs`、`split`、`component_count` 或 `ai_generation_count` 字段。文件数可读 `images.length`，不等于语义类别数；裁切框保存在步骤记录中，也不是三段/九宫格边距。
+
+生成后查看每张组件，按实际内容命名并记录：图片 ID、用途、状态、源尺寸、三段/九宫格边距、拉伸或平铺模式、内容内边距、对齐基准。需要引擎配置时依据这些测量值创建；本工具不会生成这些配置。不要把 AI 画出的比例或阴影边缘当作已精确测量的边界。
+
+至少检查短、中、长三种宽度；九宫格再检查不同高度；进度条检查 0%、中间值、100%；交互状态检查换图不跳动。修正拆图造成的不同裁边或画布尺寸后再共用一套切片参数。像素风采用整数缩放和合适采样；图集打包时保留状态对齐信息、边缘余量，检查相邻素材串色。详细做法见接入参考。
+
+失败时读取具体错误。拆图失败不抹掉已经保存的生成图或透明素材表；先在任务记录/画布中定位它们，按需要继续处理，避免为了取得已生成的图片重新付费生图。原生透明和可伸缩构造是生成约束，仍需目视验收。

package/dist/skills/zh-CN/game-ui-generator/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "游戏 UI 组件库生成与使用"
+  short_description: "生成可复用 UI 组件图片，说明按钮三段、面板九宫格与运行时拼装"
+  default_prompt: "使用 $game-ui-generator 生成游戏 UI 组件图片，并说明各组件的切片、拉伸或平铺、状态切换及运行时拼装方式。"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/zh-CN/game-ui-generator/references/component-patterns.md

@@ -0,0 +1,65 @@
+# UI 组件构造与生成提示词
+
+本目录解释“生成什么图、运行时如何使用”。前 22 类对应工具固定清单；细分构造是建议，不保证默认输出每一种部件。将所需构造与风格写入用户 `prompt`，不要修改 image 内置提示词。工具没有 `components` 参数，不能替换固定清单；严格限定的部件或扩展类别使用 `evomeme_generate_game_image`，由本技能指导提示词，后续按需处理图片。
+
+三段/九宫格、填充和状态切换是引擎提供的基础能力；下列组件组合是基于这些能力的美术与实现建议，不表示存在统一的行业强制规格。引擎差异与官方依据见 [接入参考](runtime-integration.md)。这些生成提示词是可编辑的示例，输出仍需检查和测量。
+
+## 共用提示词骨架
+
+`prompt` 示例：
+
+> 为游戏制作可复用 UI 皮肤素材表，【画风】，【材质】，【主色和强调色】，统一光源、描边与圆角，正面正交视图。每个独立部件完整展示，之间留宽空隙，不重叠、不粘连。按钮端帽和面板四角保留完整装饰，中段与中央适合延展；需要重复的纹理明确指定重复方向。状态变体保持相同外轮廓、尺寸、光照和对齐位置。无文字、数字、水印、标签、切割线、示意箭头或界面截图；动态图标和数值留给运行时。遵循请求的背景模式。
+
+“完整展示”指生成完整按钮/面板底图，然后在引擎中配置采样切片；不是让 AI 把九块散开。对进度条、滑块等组合控件则明确要求部件彼此独立。不要要求 AI 将资源排在精确图集坐标：本工具按检测主体裁切，文件序号和几何位置不能替代语义检查。
+
+不要在同一条全局提示词中同时要求“纯洋红底”和“透明底”。由 `transparent_background` 与 `background_color` 决定背景。装饰使用的颜色接近色键底色时，换底色或选择 Max 原生透明。
+
+## 默认 22 类组件
+
+下面每条生成描述可并入用户 `prompt`。组件库工具仍附带固定清单；通用图片工具适合严格限定的小批次。指定的像素与比例是目标，不是精确输出保证。
+
+| 组件 | 独立部件与运行时用法 | 生成描述示例 |
+| --- | --- | --- |
+| 1. 窗口面板 | 完整底板用九宫格；四角固定、边框沿各自方向延展，中央承载运行时内容。独特徽章单独叠加。 | 一个完整窗口面板底板，四角装饰紧凑，边框等厚，中央纯净且可双向拉伸，无文字图标；中央不放独特图案，不画九宫格分割线。 |
+| 2. 标题栏 | 固定高度用三段；中央显示动态标题。徽章、折叠/关闭按钮作为独立元素。 | 完整水平标题栏及独立装饰徽章，两端造型固定，中段可水平延展，标题区域留空，徽章不要与栏体粘连。 |
+| 3. 标准按钮 | 固定高度三段切分；高度也变化则九宫格。普通/悬停/按下/禁用换图，文字独立；按下态不改变外轮廓。 | 同一完整水平按钮底板的普通、悬停、按下、禁用四态，端帽位置和外轮廓一致，中段无独特装饰，适合水平拉伸；用亮度和内阴影表达状态，无文字。 |
+| 4. 页签 | 三段或九宫格页签底板，与内容面板分离；切换选中皮肤，不拉伸标签文字。 | 同形页签的未选中、选中底板，统一尺寸与圆角；选中态只改变边缘强调和色调，中央空白可延展，不连接整张页面。 |
+| 5. 文本输入框 | 单行三段或九宫格，多行九宫格；光标、输入内容、占位提示、选择高亮由代码绘制。 | 完整输入框底板的普通、聚焦、禁用三态，边框与内阴影一致，中央留空可伸缩，不画文字、光标或选区。 |
+| 6. 下拉框 | 可伸缩字段、箭头图标、九宫格菜单底板、菜单行状态分开；代码展开列表并布局文字。 | 下拉输入底板、独立向下箭头、弹出菜单底板、菜单行普通和选中皮肤，分别摆放；字段可横向延展，菜单可九宫格延展，不画菜单文本。 |
+| 7. 单选按钮 | 固定比例的外圈和选中点，或对齐的未选中/选中整图；逻辑保证组内单选，不单向拉长圆圈。 | 同尺寸圆形单选控件的未选中与选中态，外圈形状和位置完全一致，选中点清晰居中，独立摆放，无标签。 |
+| 8. 开关 | 轨道用三段，滑钮固定尺寸；运行时平移滑钮、换轨道颜色。也可换整图，但不能自动获得滑钮运动。 | 开关的关闭轨道、开启轨道及一个独立圆形滑钮，轨道完整且可水平延展，滑钮不要画在轨道上，所有部件统一光照。 |
+| 9. 水平滑块 | 轨道、可选满长度填充、滑钮分离。轨道三段，滑钮固定；值映射到有效移动距离，避免越出端部。 | 水平滑块空轨道、满长度填充条和独立滑钮，三个部件分开，轨道两端完整，中段均匀可延展；不画数值和刻度文字。 |
+| 10. 竖向滚动条 | 上中下三段轨道和可变长度滑块分别生成；滑块长度表达可见比例，位置表达滚动进度。 | 完整竖向滚动槽和独立竖向滑块，各自上下端帽完整，中段可纵向拉伸，无固定纹章、箭头和文字，便于改变轨道及滑块长度。 |
+| 11. 血条 | 空槽、满长度血量填充、外框分离；只裁切/遮罩填充，外框不随血量变化。延迟掉血可另叠一条填充。 | 水平血条的空槽、完整满血填充条、透明中心外框，三个独立部件；填充形状匹配内槽，外框端部装饰固定，无生命值数字或局部缺口。 |
+| 12. 通用进度条 | 背景、完整填充、边框分离；水平/竖直裁切或填充属性表示进度。分段条重复单元，不拉长每格。 | 水平加载条的空槽、全长度填充、独立边框，内部没有百分比和文字；填充平滑连续，槽体两端完整，中段适合水平延展。 |
+| 13. 技能快捷栏 | 可选可伸缩底板 + 重复单个槽位；代码排列任意数量槽位。不要把整排槽位整体拉伸。 | 一个可水平延展的快捷栏底板和一个独立空技能槽框，槽框固定正方形比例，底板无内嵌槽格、技能图标、快捷键或数字。 |
+| 14. 技能图标槽 | 槽框、独立图标、选中覆层、锁图标分离；冷却用运行时遮罩与数值。不要把当前冷却角度烘焙进每个技能图。 | 同尺寸空技能槽普通与选中边框，独立锁图标及可被程序裁切的完整冷却覆层，槽中心透明，全部分开，无技能图案、倒计时和固定扇形缺口。 |
+| 15. 物品槽 | 槽框与物品图标分离；选中/锁定覆层单独显示，数量由文本绘制。方形装饰框保持比例。 | 空物品槽框的普通和选中态、独立锁定覆层，尺寸与轮廓一致，中心透明，不画物品、数量或稀有度文字。 |
+| 16. 头像框 | 头像、裁切遮罩和装饰框分层；遮罩限制头像边界，框保持比例，避免单向拉长人物。 | 一个完整圆形头像装饰框，中心透明、内外轮廓清晰，框外留余量；不画人物、文字、头像内容或不规则悬空碎片。 |
+| 17. 货币/资源显示 | 三段或九宫格底板 + 固定图标 + 动态数量文本；不要把图标烘焙在可伸缩中段。 | 一个可水平延展的资源数量底板和一个独立金币图标，底板中央留空，无数字或文字，图标与底板分开摆放。 |
+| 18. 对话框 | 九宫格主体，尾巴、头像、姓名和文字独立；尾巴随指向位置移动，不随面板拉长。 | 完整对话气泡主体底板和一个独立短尾巴，主体适合九宫格延展，尾巴材质与边框一致，二者不要连接；无角色、姓名或对话文字。 |
+| 19. 角色名牌 | 三段底板适配名字长度，徽章/阵营图标独立；姓名、称号由文本布局。 | 完整水平角色名牌底板和独立阵营徽章，端帽紧凑，中段干净可延展，名称区留空，不将徽章连接在中段。 |
+| 20. 对话选项按钮 | 单行三段，多行九宫格；选中皮肤、文字、序号、任务图标分别处理。 | 对话选项按钮底板的普通、聚焦、禁用三态，适合九宫格和多行文本，内区留空，三态角形及外轮廓一致，无选项文本和序号。 |
+| 21. 确认弹窗 | 复用九宫格面板、标题栏、按钮和独立关闭图标；代码布局，屏幕遮罩另外绘制。 | 确认弹窗需要的完整面板底板、两个相同轮廓的主要/次要按钮底板、独立关闭图标，分别摆放，不拼成完整弹窗截图，不画标题、正文或背景遮罩。 |
+| 22. 通知横幅 | 三段或九宫格底板 + 固定类型图标 + 动态文字；按文案长度布局，进出场动效由代码驱动。 | 一条可水平延展的通知横幅底板和独立提示图标，两端装饰完整，中段空白，无文字；图标不粘连底板，不画运动轨迹。 |
+
+滑块与滚动条都要独立控制轨道和滑动部件；滚动条滑块还需按可见内容比例改变长度。这些构造对应 [Unity Slider](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/script-Slider.html) 和 [Scrollbar](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/script-Scrollbar.html) 的运行时部件。
+
+## 可按需增加的组件（不在默认 22 类内）
+
+| 组件 | 使用方式 | 生成描述示例 |
+| --- | --- | --- |
+| 复选框 | 固定尺寸底框 + 勾选/不确定状态标记，逻辑独立开关，不与单选组混用。 | 同尺寸复选框空底框、独立勾号和独立短横标记，保持统一描边和居中对齐，无标签。 |
+| 提示气泡 | 九宫格主体 + 独立指向尾巴，代码根据屏幕边缘换方向、位置与文本布局。 | 一个紧凑提示气泡底板及上下左右四种独立短尾巴，主体边框可九宫格延展，尾巴与主体材质一致，无文字。 |
+| 圆环进度/冷却 | 完整底环、完整填充环、中心图标分离；代码控制扇形遮罩角度，不生成固定 25%/50% 截图。 | 空进度底环与完整连续填充圆环，尺寸、圆心和环宽一致，中心透明，不画缺口、百分比或数字。 |
+| 分隔线/装饰带 | 两端固定，中部拉伸或按重复单元平铺；纵向同理。 | 完整水平装饰分隔线，左右端帽固定，中段纹样沿水平方向可连续重复，纹理尺度统一，无文字和中间徽章。 |
+| 列表行/树节点 | 九宫格行背景 + 独立展开箭头/状态图标，代码布局缩进与文本。 | 列表行普通、悬停、选中背景及独立展开箭头，行背景可九宫格延展，尺寸一致，中央留空，不画数据文字。 |
+
+圆环和直条都应先生成完整填充图，再由运行时选择显示范围；例如 [Godot TextureProgressBar](https://docs.godotengine.org/en/stable/classes/class_textureprogressbar.html) 提供背景、进度、覆盖图层和不同填充方向。
+
+## 分批生成与交付
+
+1. 整套基础组件使用 UI 组件库工具；限定为 4 态按钮、血条 3 个部件等小批次时使用通用图片生成工具，仍按本技能组织提示词。组件库工具的 `auto_split=false` 只关闭拆图。
+2. 将共用风格和部件要求写入 `prompt`。后续批次引用验收过的素材表维持风格。固定清单只是起点，不能保证一次生成整个项目所需的完整 UI 系统。
+3. 检查主体是否粘连、拆分是否正确、状态尺寸是否一致。对分离出的状态图补齐画布和对齐基准，再测量切片；保留原图以便重新裁切。
+4. 向开发者同时交付图片和基于实际图像测量的使用说明：组件名、部件关系、切片边距、伸缩方向、重复方式、状态映射、填充方向与内容内边距。任何示例数字都不能直接当作生成图的测量结果。

package/dist/skills/zh-CN/game-ui-generator/references/runtime-integration.md

@@ -0,0 +1,45 @@
+# 切片与引擎接入
+
+本页解释生成后的图片如何使用。以下配置由查看实际图片后测量得到，生成工具不自动输出。构造要求和提示词只维护在 skill 中，不修改 image 函数；MCP 与画布继续调用同一个原有任务函数。
+
+## 从原图确定切片
+
+先分离组件，再测量组件自身的左、右、上、下边距。不要把素材表上的组件间空隙当作边框宽度，也不要按三等分或九等分计算。边距应完整覆盖圆角、端帽、描边和需要保留的装饰。
+
+| 区域 | 运行时处理 |
+| --- | --- |
+| 水平三段的两端 | 保持尺寸；需要不同整体视觉比例时统一缩放整个控件体系。 |
+| 水平三段的中间 | 拉伸到目标宽度减去左右端帽；或在这个区域内重复纹理并裁掉余量。 |
+| 九宫格四角 | 保持形状与尺寸。 |
+| 九宫格上下边、左右边 | 分别沿水平、竖直方向延展。 |
+| 九宫格中央 | 适配目标宽高；可不绘制透明中心，只显示边框。 |
+
+例如实际按钮 240×64，左右边距各 24，目标宽 360，则中段宽 `360−24−24=312`。这些数字只是示例，不能直接用于生成图。最小尺寸还要容纳文字和内容内边距；内容内边距负责文字布局，与切片边距分开设置。
+
+拉伸适合平滑底色；平铺适合已检查连续性的纹样。带有独特符号、明显光照变化的区域通常不适合重复。高度也需要变化时采用九宫格，不把固定高度三段按钮直接纵向拉长。
+
+## 引擎对应方式
+
+| 环境 | 常见接入方式与限制 |
+| --- | --- |
+| Phaser | `NineSlice` 支持三段和九宫格；只有左右边距、上下边距为零时可做水平三段，改尺寸用 `setSize`。其拉伸能力不代表任意中段都能平铺；需要重复纹理时组合固定端帽与受裁切的 `TileSprite`，并核对项目渲染器支持。[官方说明](https://docs.phaser.io/phaser/concepts/gameobjects/nine-slice) |
+| Unity uGUI | 在 Sprite 中配置边框，用 `Image.Type.Sliced` 拉伸或 `Tiled` 平铺，通过 RectTransform 调整尺寸。进度填充使用独立 `Image` 的 `Filled` 或遮罩，不能让同一个 Image 同时采用 Sliced 和 Filled 两种类型。[Image 类型](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/api/UnityEngine.UI.Image.Type.html) |
+| Godot | 控件主题使用 `StyleBoxTexture`，直接显示切片图片可用 `NinePatchRect`；纹理边距控制切片，内容边距控制子内容布局，按需选择拉伸、平铺或整块适配。[StyleBoxTexture](https://docs.godotengine.org/en/stable/classes/class_styleboxtexture.html)、[NinePatchRect](https://docs.godotengine.org/en/stable/classes/class_ninepatchrect.html) |
+| HTML/CSS | `border-image-slice` 定义源图分区，`border-image-width` 定义显示边宽；需要中央时加 `fill`。`border-image-repeat` 的 `stretch`、`repeat`、`round` 对应拉伸、重复和整块适配，`space` 会留间隙，不适合连续边框。[切片](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-image-slice)、[重复模式](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-image-repeat) |
+
+以上是官方文档所支持的方式，具体 API 和渲染器能力应按项目使用的版本确认，不代表所有引擎配置完全相同。
+
+## 组合控件如何驱动
+
+- **进度/血量**：底槽和外框尺寸保持稳定，只更新满长度填充图的显示比例。比例先限制在 0～1；文字另外绘制。圆形冷却使用扇形遮罩，完整圆环为源图。[Godot TextureProgressBar](https://docs.godotengine.org/en/stable/classes/class_textureprogressbar.html)
+- **滑块**：轨道长度适配布局，滑钮保持大小。有效行程需扣除端部留白和滑钮占用，值映射到行程内的位置；不要拉伸滑钮。[Unity Slider](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/script-Slider.html)
+- **滚动条**：滑块长度根据可见内容占全部内容的比例确定，并设置可操作的最小长度；滑块在剩余行程中移动。[Unity Scrollbar](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/script-Scrollbar.html)
+- **按钮状态**：同尺寸、同对齐基准的图片按状态换图，或用着色/动画；键盘焦点、禁用、按下分别处理。点击区域由控件定义，不依赖透明图片自动产生。[Unity 状态切换](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/script-SelectableTransition.html)
+
+## 实际资源交付与验收
+
+记录每张图片的路径、角色、状态、源尺寸、切片边距、内容内边距、拉伸/平铺方式，以及与其他部件的对齐位置。比如“按钮：240×64，左/右 24，上/下 0，水平三段拉伸”必须来自实际测量，不能从提示词或示例推断。
+
+自动拆图不会补齐同尺寸。状态图裁边不一致时先补齐画布、统一对齐基准，再共用切片参数。打包图集时保留裁边偏移、边距和独立留白，检查采样是否串入相邻素材；切片参数不能继续指向裁剪前的位置。像素风检查整数缩放与采样设置，避免把模糊缩放当作美术问题。
+
+用短、中、长宽度和多种高度检查变形；进度检查 0%、中间值、100%；状态切换检查跳动；文本检查长字符串和不同语言。边框、头像、图标、尾巴、滑钮和数量文字应各自符合构造目录中的伸缩规则。

package/dist/skills/zh-CN/game-video-cycle/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: game-video-cycle
+description: 使用 evomeme_extract_video_cycle 从已有视频中提取以首帧为参照的候选循环片段，另存一个 MP4。适用于原地待机、行走、旋转等重复动作或可循环视频背景；解释工具实际检测与截取步骤、文件产物、相似度阈值、最小间隔、检测帧率和首尾验收。不用于生成新动作、寻找任意中间片段、自动修补接缝或导出序列帧。
+---
+
+# 视频循环提取
+
+使用 `evomeme_extract_video_cycle` 从已有视频开头提取候选循环。先查看视频是否从合适的循环姿态开始、是否包含返回该姿态的完整过程，再设置相似度阈值和最小间隔。返回成功说明找到了达到算法门槛的结束点，仍需播放检查。
+
+## 工具具体做什么、生成什么
+
+MCP 与画布共用 `video_cycle` 任务及 `extractVideoCycleAsset`，由已有 `extractVideoCycle` 串联检测和截取。处理均在本地完成，没有 MCP 调用 MCP，不修改共享 task/image 算法或提示词。
+
+一次调用：
+
+1. 读取工作区内已有视频的时长和尺寸。
+2. 按固定 **24 帧/秒**生成检测用灰度缩略图，默认宽 96 像素，高度随比例调整且至少为 8。缩略图只用于分析，不是最终导出尺寸。
+3. 以第一个检测帧为参照。跳过早于 `min_gap_sec` 的候选结束点，逐帧计算与首帧的结构相似分数；遇到第一个 `score >= threshold` 的帧即停止。
+4. 截取 **从 0 秒到匹配时间**的片段，用 H.264 重新编码，另存 **一个 MP4 文件**到 `assets/`；有可用音轨时随片段编码为 AAC。保留源视频并登记任务。
+
+输出文件名由 `cycle.mp4` 加唯一标识生成，以返回路径为准。不是无损复制原始压缩数据；不调用 AI、不自动上传、不输出 GIF、透明视频或序列帧整图，不重新生成动作，也不通过补帧、倒放、交叉淡化或修音来制造循环。
+
+“首个完整循环”在当前实现中指**从视频开头到第一个合格匹配点的候选区间**。它不会跳过片头寻找任意中间循环，不寻找全片最高分，也不验证动作是否完成了一个语义上的完整周期。相似姿态但速度、方向或动作阶段不同，仍可能被匹配。
+
+## 什么时候使用
+
+| 需求或源视频 | 使用建议 |
+| --- | --- |
+| 原地待机、步行、物体旋转等重复动作，开始姿态会再次出现 | 使用本工具，检查镜头、位置和背景是否稳定。 |
+| 已有视频包含多轮重复动作，只需要开头的一轮 | 以默认参数开始，根据真实周期设置最小间隔；输出不保证总是恰好一轮。 |
+| 需要可重复播放的视频背景或特效片段 | 可尝试提取，但镜头移动、光照变化或粒子随机性可能导致找不到匹配或接缝仍明显。 |
+| 开头有淡入、字幕、静止等待或不属于循环的片头 | 先另行裁掉片头，再对裁后视频调用。当前工具没有开始时间参数。 |
+| 只需要按指定起止时间裁切 | 使用已有视频编辑能力；本工具自动检测结束点，没有 `start` / `end` 输入。 |
+| 需要新生成循环动作视频 | 使用 [视频生成技能](../game-video-generator/SKILL.md)，将首帧和尾帧设为同一图片的拷贝或同一素材 URL；生成后再按需要提取和验收。 |
+| 需要把视频转换为游戏精灵帧表 | 本工具只提供候选循环 MP4，提帧和帧表布局需另行处理，不能声称本次已生成帧表。 |
+
+大面积静止背景可能掩盖小主体的变化；近乎纯色的画面也可能无法形成有效相关信号。镜头平移、前后不同的背景、主体位移或中途短暂停留，都可能影响检测；降低门槛并不等于修复这些问题。
+
+## 参数与术语
+
+| 参数 | 实际含义 |
+| --- | --- |
+| `id` | 必填，工作区 `assets/` 内的已有视频素材 ID，例如 `assets/idle.mp4`。不接受图片、URL、绝对路径或 Base64。 |
+| `threshold` | 默认 `0.98`，数值范围 `0.5～0.999`。相似度门槛，必须传小数，不能传 `98`。画布显示的 98 对应此处的 0.98。 |
+| `min_gap_sec` | 默认 `0.4`，范围 `0.1～10`，单位秒。从首帧起至少经过多久，才开始比较结束帧。 |
+| `workspace_dir` | 可选，工作区根目录绝对路径，建议显式传入；省略时使用 MCP 当前目录。 |
+
+- **循环片段／循环周期（loop / cycle）**：一段重复播放时应自然衔接的视频。首尾画面相近是必要参考，但还要看动作速度、方向、背景和声音是否连续；本工具只用视觉相似性确定候选结束点。
+- **相似度分数与 NCC（归一化互相关）**：先把灰度缩略图减去平均亮度并除以亮度变化幅度，再比较相同位置的明暗结构。分数越接近 1，结构越相似。它不是像素相同百分比、AI 置信度或动作识别概率；灰度与缩小分析也可能忽略颜色、微小物体和细节差异。
+- **阈值（threshold）**：候选帧必须达到的分数。提高通常更严格，也更容易失败；降低更容易接受不完整动作或明显接缝。不是对视频执行“相似度修复”。
+- **最小间隔（minimum gap）**：避免刚开始就把相邻的相似画面当成一轮循环。它不是目标时长、最大搜索时长或开始裁切的位置；过大可能跳过真正的第一轮，输出多轮或最终失败。
+- **检测帧率（detection fps）**：每秒采样多少画面用于查找，此处固定 24，候选时间步长约为 1/24 秒。返回的 `fps` 是这个检测值，不是原视频或导出视频的实际帧率，工具也没有可设置的 `fps` 参数。
+- **重新编码（re-encoding）**：将截出的画面重新压缩为 H.264，将可用音频转为 AAC，封装在 MP4 中。质量、码率和文件字节可能变化；音频不是按波形或节拍寻找循环点，也不自动淡入淡出。
+
+源视频时长必须大于 `min_gap_sec + 1/24` 秒，否则会报过短错误。没有 `prompt`、`model`、期望时长、候选数量、音频修复、静音、质量、分辨率或自定义起止时间参数。
+
+## 调用示例
+
+调用 `evomeme_extract_video_cycle`：
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "id": "assets/idle.mp4",
+  "threshold": 0.98,
+  "min_gap_sec": 0.4
+}
+```
+
+若查看源视频后确认动作不可能在 1.2 秒以内完成一轮，可将 `min_gap_sec` 设为 `1.2`，排除过早的相似帧。这个例子不会把输出长度固定为 1.2 秒；工具仍寻找该时间之后首个达到阈值的画面。不要仅因短片段“不好看”就盲目把最小间隔改得很大。
+
+若上游视频生成工具只返回 `local_path`，先确认文件位于当前工作区 `assets/` 内，再按真实相对路径得到 `assets/...` 素材 ID。不能把远端 URL 或完整本地路径直接填到 `id`，也不要假设上游一定返回了 `asset_id`。
+
+## 返回什么
+
+返回文本元数据，不内嵌视频字节或 Base64：
+
+| 字段 | 含义 |
+| --- | --- |
+| `asset_id`、`local_path`、`mime_type` | 新 MP4 的工作区 ID、本地绝对路径、`video/mp4`。 |
+| `source_id`、`operation_id`、`status` | 源视频 ID、本地操作 ID及成功状态；无远端 AI `job_id`。 |
+| `start`、`end` | 相对于源视频的候选截取起止秒数。当前 `start` 固定为 0；`end-start` 是目标片段时长，不是对封装后文件精确时长的探测结果。 |
+| `score` | 匹配结束帧与首帧的相关分数；不是全片最佳分数。 |
+| `fps` | 检测采样帧率，固定 24。 |
+| `scanned` | 实际参与首帧比较的候选帧数，不含首帧及最小间隔之前跳过的帧；不是原视频总帧数。 |
+| `threshold`、`min_gap_sec` | 本次实际相似度门槛和最小间隔。 |
+
+当前不额外返回宽高、导出实际帧率、`duration`、帧表、候选列表或公网 URL。原任务返回的 `minGapSec` 在 MCP 输出中统一为 `min_gap_sec`。检测结束点的画面相似，不代表导出后的最后一帧与第一帧逐像素相同。
+
+## 检查与接入
+
+至少连续播放两轮，检查接点是否跳帧、停顿、位置跳变、运动速度突变，背景或光照是否闪烁；有声音时另听接缝是否有爆音或节奏中断。不要只依据高 `score` 宣称无缝。
+
+片段过短时，先确认是否因静止背景、动作开始停留或半周期姿态重合而提前匹配；确有依据时再调整最小间隔或提高阈值。找不到匹配时，检查完整动作是否回到首帧、视频是否够长；可适度降低阈值但必须重新验收，不能把失败当作成功返回原视频，也不要自动调用付费视频生成来替换源素材。
+
+在网页或游戏里使用输出 MP4，并在运行时启用重复播放。这个开关负责播放行为，文件本身不包含“无限循环”的保证。需要无声显示时在项目播放配置中处理静音，工具没有静音参数。需要公网地址时用 `evomeme_upload_game_asset` 上传结果 `local_path`，不要使用原视频 URL 代替已截取片段。
+
+失败时查看具体错误和任务记录；检测不到结束点不会导出候选 MP4，编码中失败则可能已有不完整文件。不要将残留文件当作成功产物。

package/dist/skills/zh-CN/game-video-cycle/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "视频循环提取"
+  short_description: "从已有视频提取候选循环，解释相似度、最小间隔、视频产物与验收"
+  default_prompt: "使用 $game-video-cycle 检查已有视频并提取候选循环，说明截取区间、检测分数和首尾衔接需要检查的内容。"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/zh-CN/game-video-generator/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: game-video-generator
+description: 使用 evomeme_generate_game_video 根据提示词、首尾帧或图片/视频/音频参考生成一段视频，用于游戏演示、过场和动作素材原片。说明使用同一张图片的拷贝作为首尾帧来制作循环动画，以及参考 URL、参数和本地视频输出；不自动提帧、抠图或修正循环接缝。
+---
+
+# 游戏视频生成
+
+## 工具做什么、生成什么、何时使用
+
+`evomeme_generate_game_video`（视频生成）与画布视频生成共用客户端底层能力：提交提示词和可选参考，等待生成结束，下载一段视频到当前工作区 `assets/`，返回本地路径和云端 URL。文件格式以 `mime_type` 为准。适用于游戏过场、宣传演示，或后续制作角色动作素材所需的视频原片。
+
+视频是随时间连续变化的画面。它不会直接输出可供游戏播放的角色序列帧图集，也不自动提帧、抠图或保证首尾无缝循环。静态图片使用 [游戏图片技能](../game-asset-image-generator/SKILL.md)，角色多朝向使用 [角色多视图技能](../game-character-view-generator/SKILL.md)。
+
+## 参考与术语
+
+- **首帧**：希望视频开始时呈现的图像，图片参考的 `role` 设为 `first_frame`。
+- **尾帧**：希望视频结束时呈现的图像，图片参考的 `role` 设为 `last_frame`。制作循环动画时，使用首帧图片的拷贝，具体调用见下方。
+- **参考图片**：用于约束角色外观、风格或场景，可设 `role="reference_image"`；不等同于指定首帧。
+- **参考视频/音频**：提供动态或声音参考，`type` 分别为 `video`、`audio`；具体效果取决于模型支持。
+
+`references` 的每项为 `{type,url,role?}`，`url` 必须是可访问的 HTTP/HTTPS 链接，不能填素材 ID、本地路径或 Base64。需要用户附件或本地素材时，先定位可读取文件并复制到工作区 `assets/`，同名不同内容不覆盖；再用 [云端素材上传技能](../evomeme-tos-upload/SKILL.md) 上传，使用实际返回的 `asset_url`。已有可访问链接可以复用。
+
+## 循环动画的关键技巧：首尾帧使用同一张图片
+
+**生成循环动画时，首帧和尾帧应使用同一张图片的拷贝，确保两端参考画面完全一致，让动作结束后能接回起点。** 不要分别生成两张看起来相似的图片作为首尾帧；姿势、位置、构图或光照的细微差异也会影响循环衔接。
+
+在 MCP 中，将同一张图片的真实 URL 填入两条图片参考，分别设置 `role="first_frame"` 和 `role="last_frame"`，即可表达这一做法，无需重复上传同图。提示词明确要求“完成一个完整动作周期，结束时回到首帧姿态和位置，首尾运动连续”；原地待机、行走或攻击循环通常还应固定镜头并保持背景一致。
+
+```json
+{
+  "prompt": "参考角色原地完成一个完整的待机呼吸周期，镜头固定，背景一致，结束时回到首帧姿态和位置，首尾运动自然连续，适合重复循环播放",
+  "references": [
+    {"type": "image", "url": "https://example.com/hero-idle.png", "role": "first_frame"},
+    {"type": "image", "url": "https://example.com/hero-idle.png", "role": "last_frame"}
+  ],
+  "generate_audio": false,
+  "workspace_dir": "D:/my-game"
+}
+```
+
+两处示例 URL 必须替换为同一张实际图片的链接。生成后连续播放至少两个周期，检查接点是否跳帧、停顿或速度突变；相同首尾参考约束了两端画面，中间动作和最终循环效果仍需检查。
+
+## 入参
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `prompt` | 是 | 描述主体、动作起止、镜头运动、场景和风格。 |
+| `references` | 否 | `{type,url,role?}` 数组，`type` 为 `image`、`video` 或 `audio`。 |
+| `ratio` | 否 | 画面宽高比：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9` 或 `adaptive`（由服务决定适配比例）。 |
+| `duration` | 否 | 时长秒数：4、5、6、8、10、12、15；`-1` 表示自动时长。 |
+| `resolution` | 否 | 分辨率档位：`480p`、`720p`、`1080p`。 |
+| `generate_audio` | 否 | 是否生成音频，默认 `true`；需要无声素材时设为 `false`。 |
+| `watermark` | 否 | 是否添加水印，默认 `false`。 |
+| `seed` | 否 | 非负整数随机种子，用于控制生成随机性；不保证重复结果完全相同。 |
+| `video_model` | 否 | 当前支持 `doubao-seedance-2-5-260628`，也是默认值。 |
+| `workspace_dir` | 否 | 当前工作区根目录绝对路径，调用时显式指定。 |
+
+未指定比例、时长、分辨率时由服务使用默认配置。有明确需求时显式传参。
+
+```json
+{
+  "prompt": "参考角色原地挥剑一次，镜头固定，保持角色造型与背景一致",
+  "references": [{"type": "image", "url": "https://example.com/hero.png", "role": "first_frame"}],
+  "ratio": "1:1",
+  "duration": 4,
+  "resolution": "720p",
+  "generate_audio": false,
+  "workspace_dir": "D:/my-game"
+}
+```
+
+示例 URL 仅展示格式，实际调用使用上传结果或真实参考链接。
+
+## 出参与失败
+
+成功返回文本：`job_id`、`local_path`、`mime_type`、`bytes`、`asset_url`/`tos_url`、`status`、`attempts`、`model`、`ratio`、`duration`、`resolution`。记录本地路径和 URL，不将视频字节或 Base64 放入上下文。当前视频工具不返回图片工具的 `asset_id`。
+
+失败返回 `isError: true` 和具体错误；鉴权错误按 [登录恢复技能](../evomeme-login/SKILL.md) 处理。不要把失败当成生成成功，也不要因等待中断盲目重复提交。

package/dist/skills/zh-CN/game-video-generator/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "游戏视频生成"
+  short_description: "生成游戏过场、演示与动作视频，说明首尾帧参考和实际输出文件"
+  default_prompt: "使用 $game-video-generator 根据提示词和可选参考生成游戏视频，明确用途、动作、首尾帧与输出路径。"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/zh-CN/godot-3d-game/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: godot-3d-game
+description: 用 Godot 4 构建和维护 3D 游戏，并消费 EvoMeme canonical 资产包。涉及 Godot 场景结构、GLB 导入、对齐 wrapper、骨骼动画、碰撞体、构建或 3D 运行时 QA 时使用；资产未就绪时必须转回 game-asset-align。
+---
+
+# Godot 3D Game
+
+## Responsibility boundary
+
+Godot 是出货运行时，不是资产朝向猜测器。资产对齐事实源属于 `game-asset-align`；本技能负责导入门禁、唯一 wrapper、游戏场景集成和 Godot 实机验证。
+
+## Required workflow
+
+默认使用本地 CLI。先读 [CLI 契约](../game-asset-align/references/tool-contract.md) 选择启动方式；下文 `evomeme` 是 `npx -y evomeme@latest` 或同版本本地构建的简写。指定 `--workspace`，机器读取时加 `--json`。Stage 需保持前台会话运行，拿到 URL 即交给用户，后续命令使用另一终端。
+
+1. 确认工程根含 `project.godot`，并阅读与任务相关的参考文件。
+2. **Blender 建模后必须先打开 Stage 展板，确认后才能导入 Godot。** 读取 canonical `asset.json` 并执行格式检查，调用 `evomeme stage --asset <id> --workspace "<workspace>" --target godot --json`，在 Stage 对比 Blender 与 Godot 原生画面的空间、结构、材质和灯光。由用户点击“确认当前版本，允许导入”。不得替用户点击、写确认文件或用技术 ready 状态跳过。
+3. 调用 `evomeme asset sync <id> --target godot --project "<project>" --workspace "<workspace>" --json`，不要手工复制部分文件。
+4. 完整场景使用 `CanonicalAssetLoader.load_scene(parent, package_dir)`，同时接入 Stage 已确认的 PBR 材质校准、灯光、环境、曝光和相机。道具进入已有关卡时使用 `load_package`，避免叠加场景环境。模型只能位于一个带 `canonical_alignment_key` 的 `A3AlignmentRoot` 下。
+5. 将玩法节点、动画、碰撞与可视模型分层；不要在角色控制器或动画树里补 canonical Transform。
+6. 在真实 Godot 运行画面中检查构图、接地、朝向、比例、材质和交互碰撞。
+
+## Routing references
+
+- 工程目录与场景分层：读 [project-structure.md](references/project-structure.md)。
+- 材质、灯光、曝光、相机和 Stage 原生预览：读 [appearance-alignment.md](references/appearance-alignment.md)。
+- v2 loader、revision 与单 wrapper 规则：读 [canonical-asset-runtime.md](references/canonical-asset-runtime.md)。
+- 导入前/运行时/交付门禁：读 [alignment-gates.md](references/alignment-gates.md)。
+- GLB 导入、继承场景与 wrapper 维护：读 [import-and-wrapper-scenes.md](references/import-and-wrapper-scenes.md)。
+- 角色骨骼与动画：读 [skeleton-animation.md](references/skeleton-animation.md)。
+- 物理体与碰撞层：读 [physics-colliders.md](references/physics-colliders.md)。
+- 构建、运行与截图 QA：读 [build-and-qa.md](references/build-and-qa.md)。
+
+## Completion gates
+
+- 同步结果带 `alignment_status=aligned` 和非空 `alignment_key`。
+- Stage 确认来自当前 Godot 原生画面；修改模型或显示配置后重新查看并确认，再同步。
+- Godot 场景中同一资产只有一个 canonical alignment root。
+- 模型节点保留原始导入 Transform，游戏逻辑不重复应用修复配方。
+- 骨骼、动画、碰撞和视觉节点职责分离。
+- 使用 Godot 实际运行截图验收；发现偏差时更新 canonical 包，不在 Godot 局部打补丁。

package/dist/skills/zh-CN/godot-3d-game/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Godot 3D Game"
+  short_description: "构建 Godot 4 三维游戏并安全消费持续对齐的 canonical 资产"
+  default_prompt: "请使用 $godot-3d-game 把已验收的 canonical 资产集成到这个 Godot 4 工程，并完成场景、运行时与构建验证。"
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/zh-CN/godot-3d-game/references/alignment-gates.md

@@ -0,0 +1,26 @@
+# Alignment gates
+
+## Before sync
+
+- Godot root contains `project.godot`.
+- Blender modeling/changes MUST be followed by opening Stage with target=godot and explicit user confirmation of the current native Godot view. Opening the page or setting ready/spec metadata is insufficient; no manual-copy bypass.
+- Package is v2 and all required conditions are aligned or explicitly waived.
+- Current `model.glb` bytes match the recorded SHA-256 and byte count.
+- Recipe binds current source and intent revisions.
+- Scene supplement, when present, passes coordinate, camera, manifest and path validation.
+- Current confirmation binds the Godot profile, native screenshot, shared adapter, camera and source revision. A Three.js confirmation cannot authorize a Godot sync.
+
+`evomeme asset sync <id> --target godot --project "<project>" --workspace "<workspace>" --json` performs these checks before creating or overwriting destination files.
+
+## At runtime
+
+The loader repeats lightweight schema/revision assertions before loading the PackedScene. It does not recompute SHA-256 inside Godot; host-side sync owns byte validation. A package edited after sync is unsupported—resync it.
+
+## Before delivery
+
+- inspect the remote scene tree for one `A3AlignmentRoot` per asset instance;
+- verify intended forward motion, ground contact, scale and camera framing;
+- exercise animation and physics so they do not reapply the wrapper transform;
+- record a Godot run capture for render acceptance.
+
+If any gate fails, use `game-asset-align`. Do not turn off assertions or hard-code fallback rotations.

package/dist/skills/zh-CN/godot-3d-game/references/appearance-alignment.md

@@ -0,0 +1,54 @@
+# Godot 基础材质与灯光对齐
+
+以下命令按 [CLI 契约](../../game-asset-align/references/tool-contract.md) 启动；Stage 需保持前台会话，JSON 结果位于 `data`。
+
+## 必须遵守的顺序
+
+**Blender MCP 建模/修改并保存 → `evomeme scene export "<scene.blend>" --id <id>` → Stage 选择 Godot → 用户查看并确认 → `evomeme asset sync <id> --target godot --project "<project>"` → Godot 工程集成与复验。** 源契约、可选程序材质烘焙与参数见 [场景导出流程](../../game-asset-align/references/blender-scene-pipeline.md)。
+
+`evomeme stage --asset <id> --workspace "<workspace>" --target godot --json` 打开目标引擎视窗。宿主通过 `EVOMEME_GODOT` / `GODOT_PATH`（绝对可执行文件路径）或 PATH 提供 `godot`。右侧 PNG 来自独立 Godot 原生进程，模型快照写入 `.evomeme/godot-previews/`；不会提前写入最终游戏工程。左侧使用与契约相机匹配的 Blender 基准或当前机位原生渲染。未安装 Godot、原生渲染失败或机位变化时不能确认旧帧。
+
+## 数据与可调参数
+
+默认保留 GLB 标准 PBR 材质与纹理、法线、透明度；有 COLOR_0 的网格启用线性顶点颜色。默认从 `scene.contract.json.blender_lights` 重建 SUN/POINT/SPOT，按 `[x,y,z]→[x,z,-y]` 转换位置及 Blender Euler XYZ 灯光方向。AREA 使用聚光灯近似，界面明确提示；功率是基础换算，须目视校准。
+
+需要校准时，写入包内 `runtime/godot.profile.json`，并把文件字节数和 SHA-256 加到 `scene.contract.json.files`，设置 `display_profiles.godot.profile_file` 为该路径。例如：
+
+```json
+{
+  "schema": "evomeme.godot_scene_profile.v1",
+  "asset_id": "my_scene",
+  "renderer": "gl_compatibility",
+  "environment": {
+    "background_srgb": [0.10, 0.14, 0.16],
+    "ambient_srgb": [0.75, 0.82, 0.85],
+    "ambient_energy": 0.5,
+    "exposure": 1.0,
+    "tonemapper": "filmic",
+    "fog": {"enabled": false, "color_srgb": [0.6, 0.7, 0.8], "density": 0.01}
+  },
+  "materials": [{"material_name": "Stone", "roughness": 0.8, "metallic": 0.0}]
+}
+```
+
+材质按精确名称覆盖，名称缺失会使原生预览失败，避免静默无效。还可指定 `albedo_srgb` RGBA、`emission_srgb` RGB、`emission_energy`、`double_sided`；未指定字段保留 GLB 值和贴图。
+
+可显式提供 `lights` 数组替换派生灯光。每项 `type` 为 `directional/omni/spot`，使用 Godot Y-up 米制 `position`、`quaternion_xyzw`、`color_linear` RGB、`energy`、`range`、`spot_angle_degrees`（半角，0.1–89）及 `shadow_enabled`。`lights:[]` 明确禁用额外灯光。显式配置使用 Godot 能量值，不再进行 Blender 功率换算。
+
+## 对比与修改循环
+
+颜色环境光固定 `ambient_light_sky_contribution=0`，避免默认天空贡献值使 profile 的颜色环境光无效。Compatibility 的顶点颜色按 sRGB 参与着色，不能仅依赖 `vertex_color_is_srgb` 开关：共享适配器将 glTF 线性 COLOR_0 编码到私有网格副本，只更新 RGB 字节并保留 Alpha、UV、索引、骨骼、LOD 和源资源；Forward+/Mobile 保持线性数据。原生 Stage 隐藏 `-colonly` / `-convcolonly` 辅助网格（含复制后缀），防止 GLTFDocument 的运行时加载把碰撞体画成实物。
+
+1. 固定相机 quaternion、垂直 FOV、画幅，核对正反面、法线、透明度、贴图和顶点色。
+2. 核对主光方向、亮暗关系、阴影、粗糙度、金属高光、自发光、环境色和曝光。
+3. 修几何/节点材质回 Blender；基础引擎校准改 Godot profile，更新清单摘要。
+4. 重新载入 Stage，在当前 Godot 原生画面点击确认。`ready=true`、规范检查通过或 Three.js 确认不能替代此步骤。
+5. 同步后完整场景用 `CanonicalAssetLoader.load_scene(parent, package_dir)`。它应用与预览相同的 `canonical_appearance.gd`、`godot.appearance.json` 和相机；`load_package` 只处理道具模型与空间变换。
+
+## 运行时与范围
+
+profile.renderer 支持 gl_compatibility（默认）、mobile、forward_plus。导出时可读取已有工程的实际 renderer；Stage 用相同模式原生预览，不静默退回 OpenGL；同步时校验目标工程模式一致。选择更高级渲染器不会自动实现体积或 GI 资源转换，展板仍明确显示缺失项。Camera3D 保持垂直 FOV，调用方用 SubViewport 或留边保持确认画幅；场景环境只接入一次，避免与关卡已有 WorldEnvironment/灯光叠加。玩法相机可在集成后接管，变化后要复验构图和材质。
+
+Godot 导出设置需包含 `*.json` 非资源文件，保证 asset.json/godot.appearance.json 打入游戏。规范里的 Three.js 着色器、Cycles 全场景烘焙显示模块和 LUT 不会被 Godot 执行。基础 PBR、实时灯光/雾不承诺 Blender 程序节点、体积光、间接光或逐像素等价。
+
+API 依据：[GLTFDocument](https://docs.godotengine.org/en/stable/classes/class_gltfdocument.html)、[Environment](https://docs.godotengine.org/en/stable/classes/class_environment.html)、[SpotLight3D](https://docs.godotengine.org/en/stable/classes/class_spotlight3d.html)。

package/dist/skills/zh-CN/godot-3d-game/references/build-and-qa.md

@@ -0,0 +1,22 @@
+# Build and QA
+
+## Minimum verification
+
+1. Let Godot finish GLB import with no resource errors.
+2. Run the scene that instances the asset through `CanonicalAssetLoader`.
+3. Confirm one alignment root and the expected alignment key in the remote scene tree.
+4. Exercise movement, animation, collision, camera and material visibility.
+5. Restart the scene or load the asset twice to confirm idempotency.
+6. Capture the actual Godot viewport/build for visual acceptance.
+
+## Failure routing
+
+- schema/readiness/revision assertion: resync or return to `game-asset-align`;
+- missing PackedScene/import failure: inspect GLB export and Godot import log, then repair/re-export the canonical source;
+- wrong pose or missing parts: structural review/Blender path;
+- wrong identity/detail: semantic review/source regeneration;
+- material/culling/texture mismatch: render review, with Godot capture as evidence;
+- collision or gameplay transform issue: fix the authored Godot scene above/beside the visual root without modifying canonical TRS.
+
+Do not claim completion from a successful file copy alone. A successful run and target-engine visual check are required.
+

package/dist/skills/zh-CN/godot-3d-game/references/canonical-asset-runtime.md

@@ -0,0 +1,27 @@
+# Canonical asset runtime
+
+Before any engine sync, open Stage with `target=godot` after Blender modeling and obtain the user's explicit confirmation of the current native frame. Technical alignment metadata alone cannot authorize import.
+
+For a complete scene, call `CanonicalAssetLoader.load_scene(parent, package_dir)`. It applies the same material overrides, native lights, environment/exposure and reference camera reviewed in Stage. Use `load_package` below for props in a level with its own lighting. See [appearance-alignment.md](appearance-alignment.md).
+
+Call:
+
+```gdscript
+var visual := CanonicalAssetLoader.load_package(
+    visual_parent,
+    "res://assets/canonical/hero"
+)
+```
+
+The generated loader verifies:
+
+- canonical asset and alignment schema versions;
+- `alignment.ready=true` and `overall_status=aligned`;
+- source fingerprint revision equality;
+- recipe source and intent revision equality;
+- a non-empty `alignment_key`;
+- complete translation, quaternion and positive scale values.
+
+It creates `<asset_id>_A3AlignmentRoot`, tags it with the asset ID and alignment key, and places the raw imported model below it. A second call with the same key returns the existing root. A newer key replaces that one root; calling it below another canonical root is rejected.
+
+Do not copy recipe values into a `.tscn`, animation track or controller. The generated loader remains the only application point. Gameplay transform belongs above the canonical root; model-local animation remains below it.