develop-web-game

开发 Web 游戏

分小步构建游戏，并验证每次更改。将每次迭代视为：实现 → 操作 → 暂停 → 观察 → 调整。

技能路径（设置一次）

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export WEB_GAME_CLIENT="$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js"
export WEB_GAME_ACTIONS="$CODEX_HOME/skills/develop-web-game/references/action_payloads.json"

用户级技能安装在 $CODEX_HOME/skills 下（默认路径：~/.codex/skills）。

工作流

1. 选择目标。 确定要实现的单一功能或行为。
2. 小步实现。 进行能推动游戏进展的最小更改。
3. 确保集成点。 提供单个画布和 window.render_game_to_text，以便测试循环读取状态。
4. 添加 window.advanceTime(ms)。 强烈建议提供确定性的步进钩子，让 Playwright 脚本能够可靠地推进帧；如果没有此钩子，自动化测试可能会不稳定。
5. 初始化 progress.md。 如果 progress.md 已存在，先读取并确认顶部记录了用户的原始提示词（以 Original prompt: 为前缀）。同时记下前一位 Agent 留下的 TODO 和建议。如果文件不存在，则创建文件，并在追加更新内容前于顶部写入 Original prompt: <prompt>。
6. 确认 Playwright 可用。 确保 playwright 可用（本地依赖或全局安装均可）。如不确定，先检查 npx。
7. 运行 Playwright 测试脚本。 每次有意义的更改后都必须运行 $WEB_GAME_CLIENT；除非确有需要，否则不要另行创建客户端。
8. 使用负载参考。 根据 $WEB_GAME_ACTIONS 执行操作，避免猜测按键。
9. 检查状态。 每轮操作后捕获屏幕截图和文本状态。
10. 检查屏幕截图。 打开最新的截图，确认视觉效果符合预期；修复任何问题后重新运行脚本。重复此过程，直至结果正确。
11. 验证控制和状态（重点关注多步操作）。 全面测试所有重要交互。针对每个交互，梳理其完整的多步操作序列（触发 → 中间状态 → 结果），并端到端验证整个流程。确认 render_game_to_text 反映的状态与屏幕上显示的状态一致。如有任何异常，请修复并重新运行。 重要交互示例：移动、跳跃、射击／攻击、交互／使用、在菜单中选择／确认／取消、暂停／恢复、重新开始，以及请求中定义的任何特殊能力或谜题操作。多步操作示例：射击敌人应降低其生命值；生命值降为 0 时，敌人应消失且分数应更新；收集钥匙应解锁门并允许进入下一关。
12. 检查错误。 查看控制台错误，并在继续之前修复第一个新出现的问题。
13. 在不同场景之间重置。 验证不同功能时，避免状态相互影响。
14. 小幅迭代。 每次只更改一个变量（帧数、输入、时序、位置），然后重复步骤 7–13，直至稳定。

示例命令（需要操作）：

node "$WEB_GAME_CLIENT" --url http://localhost:5173 --actions-file "$WEB_GAME_ACTIONS" --click-selector "#start-btn" --iterations 3 --pause-ms 250

示例操作（内联 JSON）：

{
  "steps": [
    { "buttons": ["left_mouse_button"], "frames": 2, "mouse_x": 120, "mouse_y": 80 },
    { "buttons": [], "frames": 6 },
    { "buttons": ["right"], "frames": 8 },
    { "buttons": ["space"], "frames": 4 }
  ]
}

测试清单

测试为满足请求而添加的任何新功能，以及逻辑更改可能影响的任何部分。发现问题后予以修复，并重新运行测试以确认问题已解决。

测试示例：

• 主要移动／交互输入（例如移动、跳跃、射击、确认／选择）。
• 胜利／失败或成功／失败状态转换。
• 分数／生命值／资源变化。
• 边界条件（碰撞、墙壁、屏幕边缘）。
• 菜单／暂停／开始流程（如有）。
• 与请求相关的任何特殊操作（强化道具、连击、能力、谜题、计时器）。

要检查的测试产物

• Playwright 运行生成的最新屏幕截图。
• 最新的 render_game_to_text JSON 输出。
• 控制台错误日志（继续之前，先修复第一个新错误）。 运行 Playwright 脚本后，必须实际打开并目视检查最新屏幕截图，而不能只生成截图。确保所有应出现在屏幕上的内容都确实可见。不要只停留在开始画面，还要截取涵盖所有新增功能的游戏过程截图。将截图视为真实情况的依据；如果缺少某项内容，说明构建中就缺少该内容。如果怀疑是无头模式或 WebGL 截图问题，请在有头模式下重新运行 Playwright 脚本并再次检查。紧密循环执行修复和重跑，直至截图和文本状态均正确。验证修复后，重新测试所有重要交互和控件，确认其正常工作，并确保改动没有引入回归。如果引入了回归，就修复并循环重跑所有测试，直至交互、文本状态和控件都按预期工作。彻底测试所有控件；游戏不能出现故障。

核心游戏指南

画布 + 布局

• 优先使用一个居中显示在窗口中的画布。

视觉效果

• 尽量减少屏幕上的文字；在开始或菜单画面中显示控件说明，而不要在游戏过程中叠加显示。
• 避免场景过暗，除非设计需要如此。确保关键元素清晰易见。
• 在画布上绘制背景，不要依赖 CSS 背景。

文本状态输出（render_game_to_text）

公开一个 window.render_game_to_text 函数，返回描述当前游戏状态的简洁 JSON 字符串。文本应包含足够的信息，让玩家无需视觉画面也能进行游戏。

最简模式：

function renderGameToText() {
  const payload = {
    mode: state.mode,
    player: { x: state.player.x, y: state.player.y, r: state.player.r },
    entities: state.entities.map((e) => ({ x: e.x, y: e.y, r: e.r })),
    score: state.score,
  };
  return JSON.stringify(payload);
}
window.render_game_to_text = renderGameToText;

保持有效载荷简洁，并优先包含屏幕上当前可见或可交互的内容，而非完整历史记录。 明确说明坐标系（原点和坐标轴方向），并编码所有与玩家决策相关的状态：玩家位置/速度、活动中的障碍物/敌人、可收集物、计时器/冷却时间、分数，以及正确决策所需的模式/状态标志。避免记录大量历史；只包含当前相关且可见的内容。

时间步进钩子

提供确定性的时间步进钩子，让 Playwright 客户端能够以可控的增量推进游戏。公开 window.advanceTime(ms)（或一个转发到游戏更新循环的简单封装），并确保游戏循环在该钩子存在时使用它。 Playwright 测试脚本会使用此钩子，以确定性的方式推进帧。

最简模式：

window.advanceTime = (ms) => {
  const steps = Math.max(1, Math.round(ms / (1000 / 60)));
  for (let i = 0; i < steps; i++) update(1 / 60);
  render();
};

全屏切换

• 使用单个按键切换全屏（优先使用 f）。
• 按 Esc 退出全屏。
• 切换全屏时，调整画布/渲染尺寸，确保视觉效果和输入映射保持正确。

进度跟踪

如果 progress.md 不存在，请创建该文件，并随着工作推进追加 TODO、备注、注意事项和未完成事项，以便其他 Agent 可以无缝接手。 如果 progress.md 已存在，请先阅读，包括顶部的原始用户提示（你可能正在继续其他 Agent 的工作）。不要覆盖原始提示；请保留它。 每完成一项有实质意义的工作（添加功能、发现错误、运行测试或作出决定）后，都要更新 progress.md。 工作结束时，在 progress.md 中留下 TODO 和给下一位 Agent 的建议。

Playwright 前置要求

• 如果项目已有本地 playwright 依赖，优先使用它。
• 如果不确定是否可用，请检查是否有 npx：

  command -v npx >/dev/null 2>&1
  

• 如果没有 npx，请安装 Node/npm，然后全局安装 Playwright：

  npm install -g @playwright/mcp@latest
  

• 除非明确要求，否则不要切换到 @playwright/test；请使用客户端脚本。

脚本

• $WEB_GAME_CLIENT（安装后的默认值：$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js）——基于 Playwright 的操作循环，支持虚拟时间步进、截图捕获和控制台错误缓冲。必须通过 --actions-file、--actions-json 或 --click 传入一组操作。

参考

• $WEB_GAME_ACTIONS（安装后的默认值：$CODEX_HOME/skills/develop-web-game/references/action_payloads.json）——操作负载示例（键盘 + 鼠标，逐帧捕获）。使用这些示例来构建操作组。