Web Game Builder

/develop-web-game

Build games in small steps and validate every change. Treat each iteration as: implement -> act -> pause -> observe -> adjust. The user describes the game or pastes their existing HTML/JS; deliver a complete, playable single-file HTML game (or updated files) as a chat artifact, with testability hooks built in so behavior can be verified rather than assumed. For non-game interactive web experiences, use web-artifacts-builder.

Workflow

1. Pick a goal. Define a single feature or behavior to implement.
2. Implement small. Make the smallest change that moves the game forward.
3. Ensure integration points. Provide a single canvas and window.render_game_to_text so the game state can be read as text.
4. Add window.advanceTime(ms). Strongly prefer a deterministic step hook so frames can be advanced reliably; without it, automated or manual verification is flaky.
5. Track progress. For multi-session projects, keep a progress.md note (original prompt at top, prefixed Original prompt:, plus TODOs and gotchas) so the next session can pick up seamlessly. If one exists, read it first and never overwrite the original prompt.
6. Exercise the change. After each meaningful change, play through the affected interactions (or run the bundled Playwright client if a local environment is available -- see Scripts below) with short input bursts and intentional pauses.
7. Inspect state. Capture the render_game_to_text output (and screenshots when available) after each burst and confirm it matches what should be on screen.
8. 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. 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.
9. Check errors. Review console errors and fix the first new issue before continuing.
10. Reset between scenarios. Avoid cross-test state when validating distinct features.
11. Iterate with small deltas. Change one variable at a time (frames, inputs, timing, positions), then repeat until stable.

Test Checklist

Test any new features added for the request and any areas the logic changes could affect. Identify issues, fix them, and re-verify.

Examples of things to test:

• Primary movement/interaction inputs (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)

Treat what is actually rendered as the source of truth; if something is missing on screen, it is missing in the build. 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. 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 game can be advanced 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.

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.

Scripts (optional, local environments)

When the user is working in a local repo with Node available, this skill bundles an automated test loop:

• scripts/web_game_playwright_client.js -- Playwright-based action loop with virtual-time stepping, screenshot capture, and console error buffering. Pass an action burst via --actions-file, --actions-json, or --click.
• references/action_payloads.json -- example action payloads (keyboard + mouse, per-frame capture). Base actions on this file to avoid guessing keys.

Example command:

node scripts/web_game_playwright_client.js --url http://localhost:5173 --actions-file references/action_payloads.json --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 }
  ]
}

Prefer a local playwright dependency if the project already has it; otherwise check for npx before installing anything. After running, actually open and inspect the latest screenshots -- go beyond the start screen and capture gameplay covering all newly added features. If a headless/WebGL capture issue is suspected, rerun in headed mode. Fix and rerun in a tight loop until screenshots, text state, and controls all look correct and no regressions remain.

In pure chat contexts without a runtime, walk the user through the same loop: deliver the artifact, tell them exactly which interactions to try, and have them paste back the render_game_to_text output or console errors for the next iteration.

Usage

/develop-web-game $ARGUMENTS