develop-web-game

Web ゲームを開発する

ゲームを小さなステップで構築し、変更のたびに検証します。各イテレーションを「実装 → 操作 → 一時停止 → 確認 → 調整」として進めます。

スキルのパス（一度設定）

export SKILLS_ROOT="${LOBSTERAI_SKILLS_ROOT:-${SKILLS_ROOT:-$HOME/Library/Application Support/LobsterAI/SKILLs}}"
export WEB_GAME_CLIENT="$SKILLS_ROOT/develop-web-game/scripts/web_game_playwright_client.js"
export WEB_GAME_ACTIONS="$SKILLS_ROOT/develop-web-game/references/action_payloads.json"

インストール済みのスキルは、$LOBSTERAI_SKILLS_ROOT / $SKILLS_ROOT から解決されます（本番環境のデフォルト：アプリの userData/SKILLs、macOS では通常 ~/Library/Application Support/LobsterAI/SKILLs）。

ワークフロー

1. 目標を決めます。 実装する機能または動作を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. 小さな差分で反復します。 変更する変数（フレーム、入力、タイミング、位置など）は一度に1つにして、安定するまで手順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 に切り替えないでください。クライアントスクリプトを使い続けてください。

スクリプト

• $WEB_GAME_CLIENT（インストール時のデフォルト：$SKILLS_ROOT/develop-web-game/scripts/web_game_playwright_client.js）— 仮想時間のステップ実行、スクリーンショットのキャプチャ、コンソールエラーのバッファリングに対応した、Playwright ベースのアクションループです。--actions-file、--actions-json、または --click でアクションバーストを渡す必要があります。

参考資料

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