Develop Web Game

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: $SKILLS_ROOT/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: $SKILLS_ROOT/develop-web-game/references/action_payloads.json) — example action payloads (keyboard + mouse, per-frame capture). Use these to build your burst.