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: という接頭辞付きで記録されていることを確認します。あわせて、前のエージェントが残した 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）

現在のゲーム状態を表す簡潔な JSON 文字列を返す window.render_game_to_text 関数を公開してください。このテキストには、映像がなくてもゲームをプレイするのに十分な情報を含めてください。

最小限のパターン:

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、メモ、注意点、未解決事項を追記してください。別のエージェントがスムーズに引き継げるようにするためです。 progress.md ファイルが既に存在する場合は、まず、先頭にある元のユーザープロンプトを含めて読んでください（別のエージェントの作業を引き継いでいる可能性があります）。元のプロンプトは上書きせず、そのまま保持してください。 意味のある作業のまとまり（機能の追加、バグの発見、テストの実行、判断の決定）ごとに progress.md を更新してください。 作業の最後に、次のエージェント向けの TODO と提案を progress.md に残してください。

Playwright の前提条件

• プロジェクトに playwright の依存関係が既にある場合は、ローカルのものを優先してください。
• Playwright が利用可能かどうか不明な場合は、npx の有無を確認してください:

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

• npx が見つからない場合は、Node／npm をインストールしてから、Playwright をグローバルにインストールしてください:

  npm install -g @playwright/mcp@latest
  

• 明示的に求められない限り、@playwright/test に切り替えないでください。クライアントスクリプトを使い続けてください。

Scripts

• $WEB_GAME_CLIENT（インストール時のデフォルト: $CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js）— 仮想時間ステッピング、スクリーンショットのキャプチャ、コンソールエラーのバッファリングを備えた Playwright ベースのアクションループです。--actions-file、--actions-json、--click のいずれかでアクションバーストを渡す必要があります。

References

• $WEB_GAME_ACTIONS（インストール時のデフォルト: $CODEX_HOME/skills/develop-web-game/references/action_payloads.json）— キーボードとマウスの操作、フレームごとのキャプチャを含むアクションペイロードの例です。これらを使ってアクションバーストを作成してください。