evomeme-dev 0.1.7

package/skills/game-maker/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: game-maker
+description: 将游戏或游戏 Demo 的开发目标整理为可逐步完善的任务依赖图。初期只建立主要目标、关键决策、核心 Demo 和必要依赖组成的粗略任务骨架，随着开发决策和其他 Skill 的交付逐步细化相关分支。当开发者希望从零创作、原型化、扩展或系统性改造游戏，或需要建立并持续维护游戏开发任务列表时使用。
+---
+
+# Game Maker
+
+## Goal
+将开发者的游戏构想整理为能够启动开发的粗略任务依赖图，并随着项目推进逐步补全任务细节。根据当前已经确认的信息规划下一步，让相应 Skill 接管具体工作并将结果返回任务图。
+
+此 Skill 的核心产物是持续更新的游戏开发任务列表。初始列表表达主要工作与必要依赖，后续列表根据实际决策和交付结果扩展。
+
+## Core Principles
+1. 由开发者决定游戏方向和具体细节，包括玩法方向、美术风格、UI 风格与关键参数。
+2. 初始计划只表达主要目标、里程碑、关键决策和必要依赖，让尚未进入执行阶段的任务保持粗粒度。
+3. 只根据已经确认的信息建立任务和依赖关系，使计划能够立即开始执行。
+4. 使用稳定且唯一的任务 ID 标识每个任务节点。
+5. 在任务即将执行、依赖已经满足或新的交付结果出现时，细化对应分支。
+6. 细化任务时保留原任务 ID 作为里程碑，使用新的任务 ID 添加具体工作，并更新里程碑的前置依赖。
+7. 将核心 Demo 保持为一个早期任务节点，在同一任务中并行推进图片生成与代码构建，为所有图片提供 SVG 替代，并在代码可运行后立即向开发者展示。
+8. 将具体设计与实现交由相应 Skill 完成，并根据其交付结果更新策划案、任务状态和依赖关系。
+
+## 渐进式规划
+
+### 建立初始任务骨架
+
+读取开发者的游戏构想、已有策划案和当前项目状态。确认会影响整体方向的少量关键信息，然后建立包含主要决策、核心 Demo、后续主要工作和最终验收的粗略任务列表。
+
+初始任务可以表示一个完整里程碑。任务名称应让开发者理解需要完成什么，任务之间只连接当前已经明确的直接依赖。
+
+### 细化当前分支
+
+当某项任务成为下一步工作时，结合其前置任务产物判断是否需要拆分。可以直接交由相应 Skill 执行的任务保持原样；需要多个独立结果的任务使用新的任务 ID 展开。
+
+展开后保留原任务作为里程碑，并让它依赖新增的具体任务。其他尚未进入执行阶段的分支继续保持粗粒度。
+
+### 根据结果更新计划
+
+开发者作出决定或其他 Skill 返回交付结果后：
+
+1. 更新对应任务状态；
+2. 补充由结果明确的新任务；
+3. 更新直接受到影响的依赖关系；
+4. 选择下一项依赖已经满足的任务；
+5. 在进入该任务前继续细化对应分支。
+
+## 游戏开发要点
+
+### 明确开发者需求
+首先，Agent 应准确理解开发者想要创作的游戏。此阶段聚焦游戏的整体方向与核心玩法，具体细节在后续规划中逐步展开。当开发者的表述较为模糊时，针对影响整体方向的关键信息进行追问。
+
+### 任何游戏都从 Demo 开始
+将构建 Demo 作为游戏计划的第一个主要阶段。Demo 保持最简，只实现验证核心玩法所需的完整流程、工程结构和系统架构。代码安全性和首次交付成功的优先级高于功能数量、视觉完成度与扩展设计。
+
+Demo 与游戏概念图通常只交付其中一种，两者都用于让开发者快速看到游戏效果。进入 Demo 开发后，由可玩的 Demo 承担效果展示，不在 Demo 计划中安排游戏概念图绘制任务；只有开发者明确需要单独确认美术方向时，才增加概念图任务。
+
+任务列表使用一个“制作可玩 Demo”节点，统一承载核心循环确认、最少可玩系统、工程结构、代码构建、图片生成、SVG 替代、素材接入和浏览器验收。
+
+执行 Demo 任务时，优先发起所需图片素材的生成，并同步完成工程与代码构建。每项图片素材都准备对应的 SVG 替代图，并通过统一资源接口接入游戏。生成图片返回后逐项替换；尚未完成的图片继续使用 SVG，不影响核心玩法运行。
+
+代码构建完成且核心循环可以运行后，立即启动静态服务并打开游戏网页交由开发者验收。剩余图片在首次展示后继续生成和接入，图片生成进度不延迟可玩 Demo 的交付。Demo 的验收由开发者在浏览器中完成，不安排 Agent 端自动化测试任务。
+
+### 持续维护游戏总体策划案
+随着核心游戏循环和核心游戏系统逐步明确，Agent 与开发者会持续细化完整的游玩路径。使用 `/project.md` 详细记录游戏玩法、核心循环、游戏系统及其细节。
+
+每次调整游戏玩法时，同步更新 `/project.md`。所有玩法方向的改动都应与开发者讨论，并由开发者作出最终决定。
+
+### 保持代码模块化、函数化和参数化
+在构建 Demo 及后续优化玩法的过程中，将不同的游戏系统拆分到独立的代码模块中，并为相似系统复用公共函数和逻辑。保持代码路径有效、结构清晰且易于维护，提升工程的易用性与鲁棒性。
+
+为了便于开发者后续全面接管游戏开发，将所有配置参数化，并把变量集中到开发者容易查找和修改的位置。涉及图片素材时，为每项素材建立统一的 SVG 替代与资源加载流程，并在同一 Demo 制作过程中接入生成图片。
+
+### 美术与游戏代码可以同步推进
+开发者可以通过两个对话分别推进美术与代码工作。美术创作先从概念图和美术设定集开始，用于统一并把控游戏的整体美术风格。
+
+首先，根据开发者提供的信息创作表现最终游戏成品方向的概念图。随后，为游戏系统中的各类元素创作对应的设定图，并统一采用纯白背景三视图。
+
+根据开发者的反馈持续调整概念图与设定集。完成并确认美术方向后，依据对应的概念图和设定图生成游戏内所需的素材图。
+
+### 将复杂任务拆分为四类子任务
+任何复杂任务都可以拆分为以下四类子任务，每类可以包含多个具体任务：
+
+1. 生成任务：由 Agent 负责，生成游戏所需的图片、代码、模型和文本。
+2. 自动化任务：由 Agent 负责，对素材和文本执行抠图、格式化、Photoshop 操作等自动化处理。
+3. 决策任务：由开发者负责，对游戏开发方向作出判断和选择。
+4. 细节调整任务：由开发者负责，确定游戏内的具体参数，包括游戏元素的空间位置、游戏系统参数和游戏内颜色等。
+
+## EvoMeme平台游戏开发特殊需求
+当目标平台为 evomeme时，初始计划可以先建立一个平台适配里程碑。进入该分支后，将以下要求拆分为任务节点并建立依赖：
+
+1. 创建手机端竖屏、触控优先的网页游戏任务。
+2. 创建图片、音频、视频、字体和模型等二进制素材的 evomeme云端上传任务。
+3. 创建 `public/config.json` 资源配置任务，并依赖云端上传任务返回的素材链接。
+4. 创建生产构建任务，使用 `npm run build` 将最终网页输出到 `dist/`，并依赖游戏功能与资源配置任务。
+5. 创建 `dist/` 构建产物检查任务，使其仅包含网页运行所需的文本型构建产物，并依赖生产构建任务。
+6. 创建手机竖屏、触控交互和远程资源加载验证任务，并依赖生产构建任务。
+
+## Output
+使用 Markdown 输出扁平的任务依赖列表。初始列表保持粗略，只包含当前需要的主要任务；随着工作推进，在同一列表中增加细化任务。所有任务节点直接排列在标题下方，每项任务使用稳定且唯一的任务 ID，并通过任务 ID 引用前置依赖。
+
+```markdown
+# 游戏开发任务列表
+
+- [ ] T001 [决策任务 · 开发者] <任务名称>
+- [ ] T002 [生成任务 · Agent] <任务名称>（依赖：T001）
+- [ ] T003 [自动化任务 · Agent] <任务名称>（依赖：T001）
+- [ ] T004 [细节调整任务 · 开发者] <任务名称>（依赖：T002、T003）
+- [x] T005 [生成任务 · Agent] <已完成任务名称>
+```
+
+任务类型使用“生成任务、自动化任务、决策任务、细节调整任务”。使用 `[ ]` 表示待完成，使用 `[x]` 表示已完成。任务 ID 按新增顺序递增并保持稳定。初始任务可以代表较大的里程碑；细化时保留原编号，为新增任务分配新编号。存在直接依赖时，在任务末尾引用对应任务 ID，任务关系保持为有向无环图。

package/skills/game-maker/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Game Maker"
+  short_description: "把游戏构想整理成可逐步细化、持续维护的开发任务与依赖关系"
+  default_prompt: "请使用 $game-maker 根据我的游戏构想建立一份粗略的开发任务列表，并随着开发进展逐步补充和更新。"

package/skills/game-test/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: game-test
+description: 在游戏开发结束后，对 2D 或 3D 浏览器游戏执行冒烟测试与玩法 QA，验证游戏能够启动、显示并完成核心玩法循环，同时检查主要输入、状态切换、失败重试、桌面与移动端表现。当需要对刚完成的游戏或 Demo 进行最终自检、确认基本可玩性或记录玩法问题时使用。
+---
+
+# Game Test
+
+## Goal
+
+在游戏开发结束后执行一次冒烟测试与玩法 QA，以玩家视角确认游戏可以正常进入、操作、推进、结束和重新开始，并记录阻碍基本体验的问题。
+
+## 冒烟测试与玩法 QA
+
+执行测试前，读取项目的启动方式、目标设备、输入方式、核心玩法循环和胜负条件。加载 [`references/checklists/playtest-qa.md`](references/checklists/playtest-qa.md) 作为测试参考。
+
+### 工作流
+
+1. 根据项目需要安装依赖并运行已有的构建或类型检查命令。
+2. 启动开发服务器或预览服务器，并打开正确的游戏页面。
+3. 捕获浏览器控制台、页面和网络错误。
+4. 确认游戏画面正常显示，Canvas 具有有效尺寸和可见内容。
+5. 从干净加载开始，实际游玩核心循环至少 2 分钟。
+6. 测试移动、瞄准、跳跃、攻击、拖拽或玩法对应的主要输入。
+7. 验证目标推进、计分、收集、碰撞和其他核心状态变化。
+8. 触发成功、失败、暂停、继续和重新开始等实际存在的路径。
+9. 快速切换输入并测试游戏边界、重复操作和重新开始后的状态恢复。
+10. 在目标桌面与移动视口下检查画面、HUD、文字、安全区和触控区域。
+11. 音频属于核心体验时，验证首次交互解锁、主要音效、背景音乐、暂停和重开行为。
+12. 记录测试结果和发现的问题。
+
+### 2D 游戏关注点
+
+- 精灵、地块和平台位置清晰；
+- 动画、受击和状态反馈可读；
+- HUD 与核心游玩区域保持清晰；
+- 输入结果与游戏状态一致。
+
+### 3D 游戏关注点
+
+- 场景、摄像机、材质和灯光正常显示；
+- 角色、环境和目标具有清晰轮廓与深度关系；
+- 摄像机控制、碰撞和重新开始行为稳定；
+- 模型、纹理和动画能够在实际游玩中加载并运行。
+
+### 测试结果
+
+使用简短格式报告：
+
+```markdown
+# 冒烟测试与玩法 QA
+
+- **结果**：<通过 / 未通过>
+- **运行环境**：<命令、页面和测试视口>
+- **已验证路径**：<核心操作与玩法循环>
+- **发现的问题**：<无，或问题列表>
+```
+
+每条问题说明玩家看到的现象、复现步骤和对玩法的影响。

package/skills/game-test/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Game Test"
+  short_description: "从玩家视角完成游戏冒烟测试与玩法验收，记录影响体验的问题"
+  default_prompt: "请使用 $game-test 试玩这个游戏，完成冒烟测试和核心玩法验收，并记录发现的问题。"
+
+policy:
+  allow_implicit_invocation: true

package/skills/game-test/references/checklists/playtest-qa.md

@@ -0,0 +1,12 @@
+# Playtest QA Checklist
+
+- Start from a clean load.
+- Play through the main loop for at least 2 minutes.
+- Verify controls, camera, objective feedback, failure/retry, and progression.
+- Try rapid input changes and edge movement against arena boundaries.
+- Trigger collisions from multiple angles.
+- Pause, restart, resize, and refocus the tab if supported.
+- Check audio unlock and volume behavior after the first gesture.
+- Watch for unreadable moments, camera occlusion, jitter, and missed feedback.
+- Capture screenshots for desktop and mobile.
+- Record bugs as reproduction steps with expected and actual behavior.

package/skills/game-ui/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: game-ui
+description: 为游戏设计克制、清晰且具有类型感的 HUD、菜单、弹窗、触控区域、安全区和 UI 动效，并直接调用当前环境中的生图工具交付不同界面的 UI 概念图及其设计理念。当游戏需要确定或调整 UI 风格、信息层级、界面布局、交互反馈、移动端适配，或需要为开始、游玩、暂停、设置、胜负、结算和选择等状态生成 UI 概念图时使用。
+---
+
+# 游戏 UI 设计
+
+## Goal
+
+根据游戏玩法、美术方向和目标设备完成 UI 设计，并为不同界面生成能够表现最终游戏效果的概念图。概念图应同时体现信息层级、操作意图、画面构图和统一的视觉语言。
+
+## 核心设计宗旨
+
+1. **少即是多**：让每个 UI 元素服务于玩家当前的判断、操作或反馈理解。
+2. **保留必要信息**：优先呈现生存状态、当前目标、进度和即时反馈，再安排次要信息。
+3. **游戏画面优先**：为玩家、威胁、目标、拾取物和关键演出保留清晰的可玩区域。
+4. **游戏界面而非通用面板**：使用仪表、图标、准星、资源槽、状态条、冷却环和世界内标记表达游戏信息。
+5. **视觉语言统一**：让字体、图标、形状、材质、颜色和动效延续游戏的题材与美术风格。
+6. **全视口游戏舞台**：让游戏舞台本身按目标画幅适配视口；桌面端的额外空间作为被动背景，保持游戏区域完整。
+
+## UI 设计流程
+
+### 1. 建立设计上下文
+
+读取游戏策划案、玩法说明、已有界面、运行截图、概念图、美术设定和开发者提供的参考。确认：
+
+- 核心玩法与玩家在每个状态下需要作出的决定；
+- 目标设备、横竖屏、画面比例和安全区；
+- 键盘、鼠标、触控或原生输入方式；
+- 游戏美术风格、题材、气氛和已有视觉资产；
+- 需要设计的游戏状态及每个状态的主要行动。
+
+### 2. 确定 UI 风格
+
+根据游戏美术、类型、核心玩法和用户要求确定 UI 风格。明确以下视觉语言，并交由开发者确认：
+
+- 主色、状态色和中性色；
+- 字体方向与信息字号层级；
+- 按钮、面板、状态条和弹窗的造型；
+- 图标轮廓、材质、描边、阴影和装饰密度；
+- 点击、数值变化、奖励和危险状态的反馈方式。
+
+当方向尚未确定时，提出少量差异明确的候选风格，说明每种风格与游戏题材及玩法的关系。
+
+### 3. 确定需要设计的界面
+
+根据完整游戏流程识别需要概念图的界面，例如：
+
+- 开始与主菜单；
+- 核心游玩 HUD；
+- 暂停、继续与设置；
+- 失败、重试、胜利与结算；
+- 角色、关卡、装备或能力选择；
+- 加载、资源错误和其他必要状态；
+- 移动端触控操作层。
+
+具有相同布局的状态可以共用一套设计；布局、信息层级或主要行动明显变化的状态分别生成概念图。
+
+### 4. 设计 UI 布局
+
+先列出界面中的 UI 元素，再按 HUD、菜单与弹窗、操作 UI 分类整理。根据玩家目标确定每个元素的位置、大小、层级和出现状态。
+
+#### HUD
+
+- 将 HUD 集中在屏幕顶部、上方两侧或靠近相关世界对象的位置；
+- 让常驻 HUD 高度尽量控制在画面高度的 8% 以内；
+- 常驻 HUD 优先展示不超过 3 个影响当前决策的关键数值；
+- 为分数、时间、生命、弹药等动态数值使用稳定宽度的容器；
+- 使用状态条表现需要快速读取的连续数值；
+- 使用固定的危险、奖励、护盾、增益、目标和禁用状态色；
+- 将短暂警告、连击和事件反馈安排在玩家容易察觉且不遮挡行动的位置。
+
+#### 菜单与弹窗
+
+- 让开始、继续、重试、下一关或确认成为当前界面的主要行动；
+- 将设置、退出、重新开始和关卡选择放在次要层级；
+- 使用居中面板、底部抽屉或顶部提示表达不同重要程度；
+- 让覆盖层与游戏场景保持清晰的前后关系；
+- 为弹窗保留明确的触发来源、包含内容和返回路径。
+
+#### 操作 UI
+
+- 根据核心玩法选择点击、滑动、拖拽、摇杆或行动按钮；
+- 将移动控制安排在左下拇指区域，将主要行动安排在右下拇指区域；
+- 让主要触控区域通常达到至少 44 CSS px，并为相邻操作留出间距；
+- 让 HUD、操作控件、安全区和核心游玩路径保持清晰分区；
+- 使用按下状态、方向反馈和冷却表现传达操作是否生效。
+
+### 5. 精简 UI 元素
+
+逐项确认 UI 元素对应的玩家需求。将只在结算或奖励阶段有意义的数据放入对应界面；使用图标、交互暗示和即时反馈表达直观操作；让教学与说明集中服务玩家当前需要理解的内容。
+
+游戏通过场景内直接交互即可完成核心体验时，可以采用无常驻 UI 的游玩画面，并为暂停、结算和必要反馈设计对应状态。
+
+### 6. 设计 UI 动效
+
+让动效响应明确的玩家操作或游戏状态变化：
+
+- 按钮点击：缩放至 90–95% 后弹回，约 160–220ms，使用具有回弹感的缓动；
+- HUD 数值变化：使用约 120–200ms 的数字跳动、状态条变化或颜色反馈；
+- 结算与奖励：对最终结果或主要行动进行一次性强调；
+- 菜单与弹窗：使用简短的淡入、位移或缩放建立层级；
+- 危险与高强度反馈：组合形状、颜色、运动、声音或文字传递状态。
+
+在静态概念图中通过初始位置、运动方向、残影、光效或状态对比表达动效意图。
+
+### 7. 适配 2D 与 3D 游戏
+
+- 2D 游戏让 UI 与 Canvas 游戏画面形成明确层级，并使像素密度、描边和图标风格与场景一致；
+- 3D 游戏让平面 HUD、菜单和覆盖层保持清晰，需要展示角色、载具、武器或奖杯时，可以将 3D 预览作为界面焦点；
+- 场景内标签、目标标记和交互提示与镜头构图、景深和世界空间保持协调。
+
+### 8. 文本交互技术要求
+
+游戏内用于展示的 DOM 文本应无法被鼠标光标选中，并且在移动端长按时不出现文本选择或复制菜单。使用 `user-select: none`、`-webkit-user-select: none` 和 `-webkit-touch-callout: none` 实现；输入框、文本域和可编辑元素使用 `user-select: text` 保留正常的文本选择能力。
+
+### 9. 生成 UI 概念图
+
+生成 UI 概念图或任何其他图片前，先向用户说明本轮拟生成的图片、数量和视觉方向，获得用户明确同意后再调用生图工具。生成范围发生变化时重新确认。
+
+直接调用当前环境中可用的生图工具，为每个选定界面生成概念图并向开发者展示。生成时：
+
+- 使用目标设备的真实画幅和游戏视角；
+- 让图片直接呈现游戏场景与 UI 的组合效果；
+- 复用已有截图、概念图、美术设定和已确认界面作为视觉参考；
+- 表现 HUD 锚点、菜单层级、按钮位置、触控区域和安全区关系；
+- 在不同界面之间保持统一的字体方向、图标语言、组件造型和颜色角色；
+- 使用接近实际内容长度的文字和数值建立可信的排版关系。
+
+根据开发者反馈调整概念图，并将已确认的图片作为后续界面的视觉参考。
+
+每轮 UI 概念图生成并展示后，必须立即停止当前流程并等待用户反馈。后续调整、下一轮图片或其他界面的概念图，均在收到用户明确反馈或确认后开始。
+
+### 10. 检查概念图
+
+检查每张概念图的游戏感、HUD 可读性、信息层级、画面遮挡、文字适配、安全区和触控区域。确认动态数值变化后仍有稳定空间，并确保同一套视觉规则贯穿所有界面。
+
+## 常见质量问题
+
+- HUD 呈现为通用仪表盘或统计卡片；
+- 面板层级过多，装饰面积超过有效信息；
+- UI 遮挡玩家、威胁、目标、拾取物或下一步行动；
+- 动态数值改变宽度并推动其他元素；
+- 文字、图标或触控区域在目标画幅中过小；
+- 不同界面使用相互冲突的颜色、材质和组件造型；
+- 竖屏游戏以手机外壳或画中画形式缩小实际游戏舞台。
+
+## Output
+
+直接交付不同界面的 UI 概念图。每张图片标明界面名称，并说明该界面的设计目标与设计理念。
+
+```markdown
+# 游戏 UI 概念图
+
+## <界面名称>
+
+<直接展示生成的概念图>
+
+- **设计目标**：<玩家在该界面需要理解或完成的事情>
+- **设计理念**：<信息层级、视觉焦点、构图、操作区域和美术表达方式>
+```
+
+## Reference Routing
+
+- 设计 HUD、菜单、覆盖层、触控控件和响应式布局时，读取 [`references/ui-patterns.md`](references/ui-patterns.md)。
+- 检查整体游戏感与界面质量时，读取 [`references/checklists/game-ui-quality.md`](references/checklists/game-ui-quality.md)。
+- 检查 HUD 信息层级和动态可读性时，读取 [`references/checklists/hud-readability.md`](references/checklists/hud-readability.md)。
+- 检查目标画幅、文字边界和布局稳定性时，读取 [`references/checklists/responsive-ui-fit.md`](references/checklists/responsive-ui-fit.md)。
+- 检查触控区域和安全区时，读取 [`references/checklists/mobile-input.md`](references/checklists/mobile-input.md)。

package/skills/game-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Game UI"
+  short_description: "设计游戏各界面的信息层级、布局和交互，并在确认后生成概念图"
+  default_prompt: "请使用 $game-ui 为我的游戏设计主要界面，先向我确认设计方案，并在每轮界面概念图生成后停下来等待我的反馈。"

package/skills/game-ui/references/checklists/game-ui-quality.md

@@ -0,0 +1,14 @@
+# Game UI Quality Checklist
+
+- The first screen is the playable game or a deliberate modal state, not a landing page.
+- HUD hierarchy matches gameplay priority: survival/status, objective, feedback, secondary flavor.
+- UI visual language matches the game's genre, world materials, color, and motion.
+- Menus include expected states: pause, resume, restart, settings, win/lose when relevant.
+- Buttons and controls have stable dimensions plus hover, pressed, focus, and disabled states.
+- Icons are used for compact tool/actions when recognizable; ambiguous icons have labels or tooltips.
+- UI does not use nested cards, marketing-page layout, or generic dashboard styling.
+- UI does not block player, threats, goals, interactables, or near-future path unless intentionally modal.
+- Dynamic values such as score, time, health, combo, and ammo do not shift layout.
+- Reduced-motion and flash risk is considered for intense UI animation or damage feedback.
+- UI state is driven by the game state model and does not duplicate simulation rules.
+- Desktop and mobile screenshots show coherent composition and no clipped or overlapping controls.

package/skills/game-ui/references/checklists/hud-readability.md

@@ -0,0 +1,12 @@
+# HUD Readability Checklist
+
+- Player health/status is readable during normal movement and high-action moments.
+- Objective/progress information is visible without competing with threats or pickups.
+- Text contrast remains legible over bright, dark, and moving scene backgrounds.
+- Critical status changes have at least two feedback channels when useful: shape, color, motion, sound, or text.
+- Meters, timers, and counters have fixed-width or stable containers.
+- HUD placement avoids the player focal area and likely spawn/threat lanes.
+- HUD scale is appropriate for desktop, laptop, and mobile viewports.
+- Touch controls and HUD elements do not overlap each other.
+- UI transitions do not delay input response or hide the next player decision.
+- Screenshot review confirms HUD readability before and after interaction.

package/skills/game-ui/references/checklists/mobile-input.md

@@ -0,0 +1,12 @@
+# Mobile Input Checklist
+
+- Include `<meta name="viewport" content="width=device-width, initial-scale=1.0">`.
+- Set canvas and touch overlays to `touch-action: none` only where needed.
+- Use Pointer Events when possible.
+- Keep controls reachable with thumbs and away from safe-area edges.
+- Avoid tiny text or buttons below practical touch size.
+- Verify portrait and landscape if both are supported.
+- Check high-DPR canvas scaling and cap DPR if performance suffers.
+- Prevent page scroll/zoom gestures from stealing gameplay input.
+- Test virtual joystick/button release paths when the pointer leaves the control.
+- Verify with Playwright mobile emulation and real hardware when available.

package/skills/game-ui/references/checklists/responsive-ui-fit.md

@@ -0,0 +1,12 @@
+# Responsive UI Fit Checklist
+
+- Desktop, laptop, narrow, and mobile viewports have been checked.
+- Safe-area padding is applied for mobile edges and notches when controls sit near edges.
+- No text clips, overflows, overlaps, or becomes unreadably small.
+- Long labels wrap or compress intentionally without breaking button height.
+- Controls keep stable hit targets and do not shift during score/time/state changes.
+- Layout uses grid/flex/container-aware constraints instead of viewport-only guesses where practical.
+- Menu content remains reachable without hidden offscreen controls.
+- Touch controls are large enough, separated enough, and do not trigger page scroll.
+- Canvas resizing does not desynchronize HUD placement from gameplay framing.
+- Screenshots or Playwright artifacts prove fit at the tested sizes.

package/skills/game-ui/references/ui-patterns.md

@@ -0,0 +1,140 @@
+# Game UI Patterns
+
+Use this when designing HUDs, menus, overlays, pause/fail/win states, touch controls, typography, responsive layout, and UI/world cohesion.
+
+## UI Principles
+
+- Build the game interface, not a web dashboard.
+- Prioritize gameplay hierarchy: survival/status, objective/progress, immediate feedback, then flavor.
+- Use meters, icons, reticles, badges, alert strips, cooldown rings, inventory slots, minimaps, diegetic labels, and compact clusters before generic stat cards.
+- Keep UI outside the play path and away from threats, pickups, the player, and the next decision.
+- UI should reinforce the world art direction through material cues, color roles, icon shapes, and motion language.
+- Do not use visible text to explain obvious controls when an icon, affordance, or direct interaction can do the job.
+
+## Required States
+
+Inventory states before designing:
+
+- Gameplay HUD.
+- Pause/resume.
+- Settings or audio/accessibility controls when useful.
+- Fail/retry.
+- Win/milestone/level complete when relevant.
+- Loading/empty/error when async assets exist.
+- Mobile/touch controls when target includes mobile.
+- Debug/tuning UI gated separately from player UI.
+
+Premium games should not have only one HUD state.
+
+## HUD Composition
+
+Use intentional zones:
+
+- Top or top-left: objective, wave, distance, timer, route/progress.
+- Top or top-right: score, currency, combo, inventory, pause.
+- Bottom left/right: touch movement/action controls when needed.
+- Center top or near player: short event banners, combo, warnings.
+- Near-world labels: diegetic prompts, target markers, offscreen indicators.
+
+Rules:
+
+- Use fixed-width numeric containers for score, timer, ammo, speed, health, and best values.
+- Use icons plus short labels for unfamiliar resources.
+- Use meter fills for quantities the player must read quickly.
+- Use alert colors consistently: danger, reward, shield, boost, objective, disabled.
+- Animate state changes briefly: count-up, meter fill, pulse, slide/fade, snap, ring cooldown.
+- Do not stack multiple large banners over the play path.
+
+## Menus And Overlays
+
+Pause/fail/win overlays should support quick action:
+
+- Primary action first: resume, retry, continue, next.
+- Secondary actions: settings, quit, restart, level select.
+- Avoid marketing-page hero layouts inside a game.
+- Keep menu panels stable and readable across desktop/mobile.
+- Use icon buttons for pause, sound, restart, fullscreen, settings when familiar.
+- Provide focus/hover/pressed/disabled states.
+- Gate debug panels behind a dev flag or query param.
+
+## Touch Controls
+
+When mobile is in scope:
+
+- Use pointer events where possible.
+- Ensure controls emit the same game intents as keyboard/mouse.
+- Handle `pointerup`, `pointercancel`, `lostpointercapture`, blur, and visibility change.
+- Use safe-area insets.
+- Avoid controls overlapping HUD warnings or the play path.
+- Keep touch targets at least roughly 44 CSS pixels where practical.
+- Separate adjacent controls enough to prevent accidental presses.
+- Use `touch-action` to prevent unwanted page scrolling only in control regions or the game surface.
+
+## Responsive Constraints
+
+- Define stable dimensions with CSS variables, `clamp`, grid tracks, fixed icon slots, and fixed-width numbers.
+- Present a fixed-aspect game stage as the sole visual subject and maximize it within the viewport; keep extra desktop space as passive page background.
+- Do not scale text purely with viewport width.
+- Avoid negative letter spacing.
+- Check desktop, laptop, tablet/narrow, and phone viewports.
+- Test longest likely values: high score, long labels, multi-digit timers, localized-ish text if relevant.
+- No clipped text, overlapping controls, unreadably small labels, or layout shift from changing values.
+- Menus must remain reachable without offscreen controls.
+
+## Visual Style
+
+- Match the genre: arcade racers need speed/status readability; fighters need health/round/impact hierarchy; exploration games need inventory/objective clarity.
+- Prefer restrained panels with meaningful geometry, borders, ticks, glow accents, and material cues over nested cards.
+- Use a limited status palette plus neutral surfaces.
+- Avoid one-note purple/blue gradient UI unless it is strongly justified by the game world.
+- Connect UI motifs to world decals, faction marks, vehicle panels, pickups, or hazards.
+
+## 2D Asset Sourcing
+
+Prefer procedural/CSS/canvas UI art from this skill when hand-coded techniques are enough. When external 2D is needed:
+
+- User-supplied PNG/JPG/WebP wired via config or `<img>`/canvas textures.
+- Remote MCP `evomeme_generate_game_image` when available.
+- Procedural canvas exports saved under `assets/ui/` or `assets/textures/`.
+
+Use cases:
+
+- Faction logos, team crests, title marks.
+- Pickup, ability, weapon, inventory, achievement, and objective icons.
+- Hazard signs, decals, lane glyphs, cockpit labels, item badges.
+- Menu/loading/background plates, illustrated map panels, world-style UI textures.
+- GUI material references: glass panels, metal frames, holographic strips, paper/parchment, tactical screens.
+
+Use procedural geometry or a user-provided GLB only when the UI needs a 3D object: rotating character preview, vehicle garage, weapon inspect model, trophy, diorama, or diegetic 3D menu prop.
+
+## State Wiring
+
+- UI reads game state from a single source of truth.
+- UI events dispatch game intents; they should not mutate unrelated simulation internals directly.
+- UI should update on pause, restart, resize, mobile orientation, mute, fail/win, score, health, boost, combo, inventory, and accessibility settings.
+- Avoid stale values after restart.
+
+## Verification
+
+Capture evidence:
+
+- Gameplay HUD desktop screenshot.
+- Gameplay HUD mobile screenshot when in scope.
+- Pause/fail/retry state screenshot if changed.
+- Text-fit and overlap check with high values.
+- Touch target and safe-area check when mobile is in scope.
+- Interaction test for UI buttons and touch controls.
+- Console/page error check after UI events.
+- Sourced 2D asset path and source (procedural / user-provided / remote MCP) when external 2D was used.
+- Imported 3D preview model path and renderer diagnostics when a 3D UI prop/model was used.
+
+## Common Failures
+
+- Generic dashboard/stat-card HUD.
+- Nested cards and oversized decorative panels.
+- UI covers threats, pickups, player, or next decision.
+- Text explains obvious controls instead of designing affordances.
+- Mobile safe areas ignored.
+- Touch controls look correct but do not emit intents.
+- Values change width and shift layout during play.
+- Debug UI ships as player UI.

package/skills/game-ui/references/ui-prompt-templates.md

@@ -0,0 +1,63 @@
+# Game UI Prompt Templates
+
+Reusable prompt templates packaged with this skill. Use only templates relevant to the current request, and adapt placeholders to the game/project context.
+
+---
+
+# Premium HUD/UI Pass Prompt
+
+Use `game-ui` to make this browser game's HUD and in-game UI feel premium, readable, and genre-specific.
+
+Context to gather:
+- Current screenshots at desktop and mobile sizes.
+- Game genre, core verb, target mood, and player decisions the HUD must support.
+- Current HUD/menu files, game state sources, input model, and touch controls.
+
+Design goals:
+- Keep the playable game as the first screen.
+- Make survival/status/objective information readable during motion.
+- Use stable dimensions for counters, buttons, meters, and labels.
+- Use icons where they reduce clutter, with labels where meaning is ambiguous.
+- Match the game's world materials, color, typography, and feedback language.
+
+Constraints:
+- Do not add marketing-page hero sections or explanatory feature copy.
+- Do not nest cards inside cards.
+- Do not let UI cover critical gameplay at desktop or mobile sizes.
+- Avoid text overflow, clipped controls, layout shift, and generic dashboard styling.
+
+Verification:
+- Build and run locally.
+- Capture desktop and mobile screenshots.
+- Check console/page errors.
+- Verify text fit, no overlap, no clipped controls, and at least one UI state change from real input.
+
+---
+
+# Responsive Game Menu Pass Prompt
+
+Use `game-ui` to design or improve this browser game's pause, start, settings, win, lose, or restart menus.
+
+Menu states needed:
+- 
+
+Target devices/orientations:
+- 
+
+Requirements:
+- Menus must feel like part of the game, not a website overlay.
+- Modal menus may pause or dim gameplay, but should not look like marketing cards.
+- Buttons need clear hover, pressed, focus, disabled, and touch states.
+- Settings must use appropriate controls: toggles, sliders, segmented controls, icon buttons, and select menus.
+- Layout must respect safe-area insets and remain usable on mobile.
+
+Implementation notes:
+- Prefer semantic HTML/CSS over canvas-rendered UI unless 3D placement is required.
+- Keep UI state driven by the game state model.
+- Keep dimensions stable so labels and counters do not shift layout.
+
+Verification:
+- Test every menu state.
+- Capture desktop and mobile screenshots.
+- Check keyboard/mouse and touch paths when both are supported.
+- Confirm no text overflow, overlap, clipping, or unreachable controls.