openai-develop-web-game

开发 Web 游戏

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

脚本和参考资料位于 {baseDir}/ 下。

工作流

1. 选择目标。 确定要实现的一项功能或行为。
2. 小步实现。 做出能推动游戏进展的最小改动。
3. 确保集成点。 提供一个画布和 window.render_game_to_text，以便测试循环读取状态。
4. 添加 window.advanceTime(ms)。 强烈建议提供确定性步进钩子，让 Playwright 脚本能够可靠地推进帧；没有它，自动化测试可能会不稳定。
5. 初始化 progress.md。 如果 progress.md 已存在，先阅读，并确认顶部记录了原始用户提示（以 Original prompt: 为前缀）。同时记下前一位 Agent 留下的待办事项和建议。如果文件不存在，则创建该文件，并在追加更新前写入 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（安装默认值：{baseDir}/scripts/web_game_playwright_client.js）——基于 Playwright 的操作循环，支持虚拟时间步进、截图捕获和控制台错误缓冲。必须通过 --actions-file、--actions-json 或 --click 传入一组操作。

参考资料

• $WEB_GAME_ACTIONS（安装默认值：{baseDir}/references/action_payloads.json）——操作负载示例（键盘 + 鼠标，逐帧捕获）。请使用这些示例构建操作组。

适用场景

不适用场景