网页游戏开发指南：小步快跑迭代与自动化测试实践

develop-web-game by openai/skills

597 周安装量

15,300 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/openai/skills --skill develop-web-game

开发自动化测试

🇨🇳中文介绍

开发网页游戏

以小步快跑的方式构建游戏，并验证每一次变更。将每次迭代视为：实现 → 执行 → 暂停 → 观察 → 调整。

技能路径（一次性设置）

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）。

工作流程

设定目标。 定义一个要实现的单一功能或行为。
小步实现。 做出能推动游戏进展的最小变更。
确保集成点。 提供一个单一的 canvas 和 window.render_game_to_text 函数，以便测试循环可以读取状态。
添加 window.advanceTime(ms)。 强烈建议提供一个确定性的步进钩子，以便 Playwright 脚本能够可靠地推进帧；如果没有它，自动化测试可能会不稳定。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

需要审查的测试产物

Playwright 运行的最新截图。
最新的 render_game_to_text JSON 输出。
控制台错误日志（在继续之前修复第一个新错误）。运行 Playwright 脚本后，你必须实际打开并目视检查最新的截图，而不仅仅是生成它们。确保屏幕上应该可见的所有内容都实际可见。超越开始屏幕，捕获涵盖所有新添加功能的游戏截图。将截图视为真相来源；如果缺少某些东西，那就是构建中确实缺少。如果你怀疑是无头模式/WebGL 捕获问题，请以有头模式重新运行 Playwright 脚本并重新检查。修复并在紧密循环中重新运行，直到截图和文本状态看起来正确。一旦修复得到验证，重新测试所有重要的交互和控件，确认它们正常工作，并确保你的更改没有引入回归问题。如果引入了，修复它们并循环重新运行所有内容，直到交互、文本状态和控件都按预期工作。在测试控件时要彻底；损坏的游戏是不可接受的。

建议使用一个居中对齐于窗口的 canvas。

保持屏幕上的文字最少；在开始/菜单屏幕上显示控件，而不是在游戏过程中叠加显示。
除非设计需要，避免使用过于黑暗的场景。使关键元素易于看清。
在 canvas 本身上绘制背景，而不是依赖 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 退出全屏。
当全屏切换时，调整 canvas/渲染的大小，以便视觉效果和输入映射保持正确。

如果 progress.md 文件不存在，则创建它，并随着你的进展追加 TODO、笔记、注意事项和未完成事项，以便另一个代理可以无缝接手。如果 progress.md 文件已存在，请首先读取它，包括顶部的原始用户提示（你可能正在继续另一个代理的工作）。不要覆盖原始提示；保留它。在完成每个有意义的工作块（添加功能、发现错误、运行测试或做出决策）后更新 progress.md。在你的工作结束时，在 progress.md 中为下一个代理留下 TODO 和建议。

Playwright 先决条件

如果项目已有本地 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）—— 示例动作有效载荷（键盘 + 鼠标，每帧捕获）。使用这些来构建你的动作序列。

🇺🇸English

Develop Web Game

Build games in small steps and validate every change. Treat each iteration as: implement → act → pause → observe → adjust.

Skill paths (set once)

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"

User-scoped skills install under $CODEX_HOME/skills (default: ~/.codex/skills).

Workflow

Pick a goal. Define a single feature or behavior to implement.
Implement small. Make the smallest change that moves the game forward.
Ensure integration points. Provide a single canvas and window.render_game_to_text so the test loop can read state.
Addwindow.advanceTime(ms). Strongly prefer a deterministic step hook so the Playwright script can advance frames reliably; without it, automated tests can be flaky.
Initialize progress.md. If progress.md exists, read it first and confirm the original user prompt is recorded at the top (prefix with Original prompt:). Also note any TODOs and suggestions left by the previous agent. If missing, create it and write Original prompt: <prompt> at the top before appending updates.
Verify Playwright availability. Ensure playwright is available (local dependency or global install). If unsure, check npx first.
Run the Playwright test script. You must run $WEB_GAME_CLIENT after each meaningful change; do not invent a new client unless required.
Use the payload reference. Base actions on $WEB_GAME_ACTIONS to avoid guessing keys.
Inspect state. Capture screenshots and text state after each burst.
Inspect screenshots. Open the latest screenshot, verify expected visuals, fix any issues, and rerun the script. Repeat until correct.
Verify controls and state (multi-step focus). Exhaustively exercise all important interactions. For each, think through the full multi-step sequence it implies (cause → intermediate states → outcome) and verify the entire chain works end-to-end. Confirm render_game_to_text reflects the same state shown on screen. If anything is off, fix and rerun. Examples of important interactions: move, jump, shoot/attack, interact/use, select/confirm/cancel in menus, pause/resume, restart, and any special abilities or puzzle actions defined by the request. Multi-step examples: shooting an enemy should reduce its health; when health reaches 0 it should disappear and update the score; collecting a key should unlock a door and allow level progression.
Check errors. Review console errors and fix the first new issue before continuing.
Reset between scenarios. Avoid cross-test state when validating distinct features.
Iterate with small deltas. Change one variable at a time (frames, inputs, timing, positions), then repeat steps 7–13 until stable.

Example command (actions required):

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

Example actions (inline 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 }
  ]
}

Test Checklist

Test any new features added for the request and any areas your logic changes could affect. Identify issues, fix them, and re-run the tests to confirm they’re resolved.

Examples of things to test:

Primary movement/interaction inputs (e.g., move, jump, shoot, confirm/select).
Win/lose or success/fail transitions.
Score/health/resource changes.
Boundary conditions (collisions, walls, screen edges).
Menu/pause/start flow if present.
Any special actions tied to the request (powerups, combos, abilities, puzzles, timers).

Test Artifacts to Review

Latest screenshots from the Playwright run.
Latest render_game_to_text JSON output.
Console error logs (fix the first new error before continuing). You must actually open and visually inspect the latest screenshots after running the Playwright script, not just generate them. Ensure everything that should be visible on screen is actually visible. Go beyond the start screen and capture gameplay screenshots that cover all newly added features. Treat the screenshots as the source of truth; if something is missing, it is missing in the build. If you suspect a headless/WebGL capture issue, rerun the Playwright script in headed mode and re-check. Fix and rerun in a tight loop until the screenshots and text state look correct. Once fixes are verified, re-test all important interactions and controls, confirm they work, and ensure your changes did not introduce regressions. If they did, fix them and rerun everything in a loop until interactions, text state, and controls all work as expected. Be exhaustive in testing controls; broken games are not acceptable.

Core Game Guidelines

Canvas + Layout

Prefer a single canvas centered in the window.

Visuals

Keep on-screen text minimal; show controls on a start/menu screen rather than overlaying them during play.
Avoid overly dark scenes unless the design calls for it. Make key elements easy to see.
Draw the background on the canvas itself instead of relying on CSS backgrounds.

Text State Output (render_game_to_text)

Expose a window.render_game_to_text function that returns a concise JSON string representing the current game state. The text should include enough information to play the game without visuals.

Minimal pattern:

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;

Keep the payload succinct and biased toward on-screen/interactive elements. Prefer current, visible entities over full history. Include a clear coordinate system note (origin and axis directions), and encode all player-relevant state: player position/velocity, active obstacles/enemies, collectibles, timers/cooldowns, score, and any mode/state flags needed to make correct decisions. Avoid large histories; only include what's currently relevant and visible.

Time Stepping Hook

Provide a deterministic time-stepping hook so the Playwright client can advance the game in controlled increments. Expose window.advanceTime(ms) (or a thin wrapper that forwards to your game update loop) and have the game loop use it when present. The Playwright test script uses this hook to step frames deterministically during automated testing.

Minimal pattern:

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

Fullscreen Toggle

Use a single key (prefer f) to toggle fullscreen on/off.
Allow Esc to exit fullscreen.
When fullscreen toggles, resize the canvas/rendering so visuals and input mapping stay correct.

Progress Tracking

Create a progress.md file if it doesn't exist, and append TODOs, notes, gotchas, and loose ends as you go so another agent can pick up seamlessly. If a progress.md file already exists, read it first, including the original user prompt at the top (you may be continuing another agent's work). Do not overwrite the original prompt; preserve it. Update progress.md after each meaningful chunk of work (feature added, bug found, test run, or decision made). At the end of your work, leave TODOs and suggestions for the next agent in progress.md.

Playwright Prerequisites

Prefer a local playwright dependency if the project already has it.
If unsure whether Playwright is available, check for npx:
```
command -v npx >/dev/null 2>&1
```
If npx is missing, install Node/npm and then install Playwright globally:
```
npm install -g @playwright/mcp@latest
```
Do not switch to @playwright/test unless explicitly asked; stick to the client script.

Scripts

$WEB_GAME_CLIENT (installed default: $CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js) — Playwright-based action loop with virtual-time stepping, screenshot capture, and console error buffering. You must pass an action burst via --actions-file, --actions-json, or --click.

References

$WEB_GAME_ACTIONS (installed default: $CODEX_HOME/skills/develop-web-game/references/action_payloads.json) — example action payloads (keyboard + mouse, per-frame capture). Use these to build your burst.

Weekly Installs

566

Repository

openai/skills

GitHub Stars

15.1K

First Seen

Feb 1, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex500

opencode487

gemini-cli479

github-copilot459

kimi-cli436

amp433

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

136,300 周安装