pokemon-player

Pokemon Player

pokemon-agent パッケージを使用し、ヘッドレスエミュレーションで Pokemon ゲームをプレイします。

使用するタイミング

• ユーザーが「ポケモンをプレイ」「ポケモンを始める」「ポケモンゲーム」と言った場合
• ユーザーが Pokemon Red、Blue、Yellow、FireRed などについて尋ねた場合
• ユーザーが AI による Pokemon のプレイを見たい場合
• ユーザーが ROM ファイル（.gb、.gbc、.gba）に言及した場合

起動手順

1. 初回セットアップ（クローン、venv、インストール）

GitHub にあるリポジトリは NousResearch/pokemon-agent です。クローンした後、 Python 3.10 以降の仮想環境をセットアップします。速度を優先して uv を使い、 venv を作成して pyboy エクストラとともにパッケージを編集可能モードで インストールしてください。uv が利用できない場合は、python -m venv と pip を 使用してください。

すでにチェックアウト済みのリポジトリ（例：venv の準備ができている ~/pokemon-agent）がある場合は、再クローンせずにそこへ cd して source .venv/bin/activate を実行してください。

ROM ファイルも必要です。ユーザーに ROM ファイルを尋ねてください（以前の セットアップで、チェックアウト内の roms/pokemon_red.gb にすでにある場合も あります）。 ROM ファイルをダウンロードまたは提供してはいけません。必ずユーザーに尋ねてください。

2. ゲームサーバーを起動する

venv を有効にした状態で pokemon-agent ディレクトリ内から、 --rom で ROM のパスを指定し、--port 9876 を付けて pokemon-agent serve を 実行します。& を付けてバックグラウンドで実行してください。 セーブ済みのゲームから再開するには、--load-state にセーブ名を指定します。 起動まで 4 秒待ち、その後 GET /health で確認してください。

3. ユーザーが見られるライブダッシュボードをセットアップする

localhost.run 経由で SSH リバーストンネルを使用し、ユーザーがブラウザーで ダッシュボードを見られるようにします。ssh で接続し、キーレスの localhost.run エンドポイントを使って、ローカルのポート 9876 をリモートの ポート 80 に転送します （ssh -R 80:localhost:9876 ssh://[email protected]）。出力を ログファイルにリダイレクトし、10 秒待ってから、ログ内の .lhr.life URL を grep で検索します。URL の末尾に /dashboard/ を付けてユーザーに伝えます。 トンネル URL は起動のたびに変わるため、再起動した場合は新しい URL を ユーザーに伝えてください。

セーブとロード

セーブするタイミング

• ゲームプレイを 15～20 ターン進めるごと
• ジムリーダーとのバトル、ライバルとの遭遇、危険なバトルの前は必ず
• 新しい町やダンジョンに入る前
• 確信が持てない操作を行う前

セーブ方法

POST /save にわかりやすい名前を指定します。例： before_brock、route1_start、mt_moon_entrance、got_cut

ロード方法

POST /load にセーブ名を指定します。

利用可能なセーブの一覧

GET /saves ですべてのセーブ状態を取得できます。

サーバー起動時のロード

サーバーの起動時に --load-state フラグを使用すると、セーブを自動でロードできます。 起動後に API 経由でロードするよりも高速です。

ゲームプレイのループ

ステップ 1：観察 — 状態を確認し、スクリーンショットを撮る

位置、HP、バトル、ダイアログを確認するには GET /state を使います。 GET /screenshot を使って ~/.hermes/cache/scratch/pokemon.png に保存し、 vision_analyze を使います。 必ず両方を実行してください。RAM の状態から数値がわかり、視覚情報から 空間を把握できます。

ステップ 2：状況を把握する

• 画面にダイアログやテキストがある → 進める
• バトル中 → 戦うか逃げる
• パーティーが傷ついている → ポケモンセンターへ向かう
• 目的地の近く → 慎重に移動する

ステップ 3：判断する

優先順位：ダイアログ > バトル > 回復 > ストーリーの目的 > トレーニング > 探索

ステップ 4：行動する — 最大 2～4 歩移動し、その後に再確認する

POST /action に短いアクションリスト（2～4 個。10～15 個ではありません）を 指定します。

ステップ 5：確認する — 移動のたびにスクリーンショットを撮る

スクリーンショットを撮り、vision_analyze を使って、意図した場所に 移動できたか確認します。これが最も重要なステップです。視覚情報がなければ、 必ず道に迷います。

ステップ 6：PKM: 接頭辞を付けて進行状況をメモリに記録する

ステップ 7：定期的にセーブする

アクション一覧

• press_a — 決定、話しかける、選択
• press_b — キャンセル、メニューを閉じる
• press_start — ゲームメニューを開く
• walk_up/down/left/right — 1 タイル移動する
• hold_b_N — N フレームの間 B を押し続ける（テキストを速く進めるときに使用）
• wait_60 — 約 1 秒待つ（60 フレーム）
• a_until_dialog_end — ダイアログが消えるまで A を繰り返し押す

実体験から得た重要なヒント

常にビジョンを活用する

• 移動を2〜4回行うごとにスクリーンショットを撮ります
• RAM の状態から位置と HP は分かりますが、周囲の様子は分かりません
• 崖、フェンス、看板、建物のドア、NPC はスクリーンショットでしか確認できません
• ビジョンモデルには「自分の1マス北には何がありますか？」のように具体的に質問します
• 行き詰まったら、適当に方向を試す前に必ずスクリーンショットを撮ります

ワープによる移動には追加の待ち時間が必要です

ドアや階段を通ると、マップの切り替え中に画面が暗転します。 切り替えが完了するまで必ず待ってください。ドアや階段でワープした後は、 wait_60 アクションを2〜3回追加します。待たないと位置情報が古いままとなり、 まだ元のマップにいると勘違いします。

建物から出るときの罠

建物から出ると、ドアの真正面に現れます。 北に進むと、すぐに建物の中へ戻ってしまいます。進みたい方向へ向かう前に、 必ず左右どちらかへ2マス移動してから進みます。

会話の操作

第1世代のテキストは、1文字ずつゆっくり表示されます。会話を速く進めるには、 B を120フレーム押し続けてから A を押します。必要に応じて繰り返してください。 B を押し続けると、テキストが最速で表示されます。その後、A を押して次の行へ進みます。 a_until_dialog_end アクションは RAM の会話フラグを確認しますが、このフラグでは すべてのテキスト状態を検出できるわけではありません。会話が止まったように見える場合は、 代わりに hold_b + press_a の手動操作を使い、スクリーンショットで確認してください。

崖は一方通行です

崖（小さな段差）は南へ飛び降りることしかできず、北へ登ることはできません。 北へ進んで崖に阻まれた場合は、左右どちらかへ進み、迂回できる隙間を探す必要があります。 ビジョンを使って、隙間がどちらの方向にあるか確認してください。ビジョンモデルには明示的に質問します。

ナビゲーション戦略

• 2〜4歩進んだらスクリーンショットを撮り、位置を確認します
• 新しいエリアに入ったら、すぐにスクリーンショットを撮って周囲を把握します
• ビジョンモデルに「目的地へはどちらへ進めばよいですか？」と質問します
• 3回以上試しても行き詰まったら、スクリーンショットを撮って状況を改めて評価します
• 移動を10〜15回連続で行わないでください。行き過ぎたり、行き詰まったりします

野生ポケモンとのバトルから逃げる

バトルメニューでは、RUN は右下にあります。初期カーソル位置（左上の FIGHT）から 選択するには、下を押してから右を押してカーソルを RUN に移動し、A を押します。 テキストやアニメーションを速く進めるには、hold_b を併用します。

バトル（FIGHT）

バトルメニューでは、FIGHT は左上（カーソルの初期位置）にあります。 A を押して技の選択画面に入り、もう一度 A を押して最初の技を使います。 その後、B を押し続けて攻撃のアニメーションやテキストを速く進めます。

バトル戦略

判断フロー

1. 捕まえたい？ → 弱らせてからモンスターボールを投げます
2. 必要のない野生ポケモン？ → RUN
3. タイプ相性が有利？ → 効果抜群の技を使います
4. 有利な相性がない？ → 最も威力の高いタイプ一致技を使います
5. HP が少ない？ → 交代するか、キズぐすりを使います

第1世代のタイプ相性（主な組み合わせ）

• みずはほのお、じめん、いわに強い
• ほのおはくさ、むし、こおりに強い
• くさはみず、じめん、いわに強い
• でんきはみず、ひこうに強い
• じめんはほのお、でんき、いわ、どくに強い
• エスパーはかくとう、どくに強い（第1世代では圧倒的に強力です！）

第1世代の特殊な仕様

• とくしゅの能力値は、特殊技の攻撃と防御の両方に使われます
• エスパータイプは強すぎます（ゴースト技にはバグがあります）
• 急所率はすばやさの能力値に基づきます
• まきつく／しめつけるは相手の行動を封じます
• きあいだめのバグ：急所率を上げるのではなく、下げてしまいます

メモリの規則

プレフィックス	用途	例
PKM:OBJECTIVE	現在の目標	トキワシティのフレンドリィショップでおとどけものを受け取る
PKM:MAP	ナビゲーション情報	トキワシティ：フレンドリィショップは北東
PKM:STRATEGY	バトル／チームの計画	カスミ戦の前にくさタイプが必要
PKM:PROGRESS	マイルストーンの記録	ライバルに勝利、トキワシティへ向かう
PKM:STUCK	行き詰まった状況	y=28 の崖は右へ進んで迂回
PKM:TEAM	チームのメモ	ゼニガメ Lv6、たいあたり＋しっぽをふる

進行の節目

• 最初のポケモンを選ぶ
• トキワマートから荷物を届け、ポケモン図鑑を受け取る
• グレーバッジ — タケシ（いわ）→ みず／くさタイプを使う
• ブルーバッジ — カスミ（みず）→ くさ／でんきタイプを使う
• オレンジバッジ — マチス（でんき）→ じめんタイプを使う
• レインボーバッジ — エリカ（くさ）→ ほのお／こおり／ひこうタイプを使う
• ピンクバッジ — キョウ（どく）→ じめん／エスパータイプを使う
• ゴールドバッジ — ナツメ（エスパー）→ 最も難しいジム
• クリムゾンバッジ — カツラ（ほのお）→ みず／じめんタイプを使う
• グリーンバッジ — サカキ（じめん）→ みず／くさ／こおりタイプを使う
• 四天王 → チャンピオン！

プレイの終了

1. POST /save 経由で、内容が分かる名前を付けてゲームをセーブします
2. PKM:PROGRESS を使ってメモリを更新します
3. ユーザーに「ゲームを [name] としてセーブしました！再開するには「play pokemon」と言ってください。」と伝えます
4. サーバーとトンネルのバックグラウンドプロセスを終了します

注意点

• ROM ファイルをダウンロードまたは提供してはいけません
• 画面を確認せずに4～5回を超える操作を送信しないでください
• 建物を出た後は、北へ進む前に必ず横へ移動してください
• ドアや階段によるワープの後は、必ず wait_60 x2-3 を追加してください
• RAM による会話の検出は信頼性が低いため、スクリーンショットで確認してください
• 危険な遭遇の前に必ずセーブしてください
• トンネルの URL は、再起動するたびに変わります