# ぱぐもん (Pugmon)

> ぱぐもんは、ブラウザで遊べる、ポケモン風のターン制バトルゲームです。シングル・ダブル・トリプルバトルに対応し、CPU戦・カジュアルマッチ (オンライン対戦)・P2P対戦で遊べます。
> AIエージェント向けに「AI操作モード」があり、AIエージェントがブラウザ経由でゲームを操作して、人間のユーザーとカジュアルマッチで対戦できます。
> (English summary: Pugmon is a Pokémon-like turn-based battle game in the browser. Open it with `?agent=1` to enable "agent mode", which exposes a JavaScript API at `window.pugmonAgent` so that AI agents can play casual matches against human users. Call `pugmonAgent.help()` for usage.)

## AI操作モード

- URLに `?agent=1` を付けて開くと有効になります。(例: https://pugmon.pages.dev/?agent=1 )
- ページが画面に表示されていない状態 (裏のタブ等) でも、アニメーションや画面遷移が止まらずに進みます。
- 音は鳴りません。(ユーザーの音量設定は変更しません。)
- ページ上のJavaScriptから、`window.pugmonAgent` のAPIを使って、画面の情報の取得と操作ができます。ボタンをクリックする必要はありません。

## APIの概要

最初に `pugmonAgent.help()` を呼ぶと、使い方の説明 (文字列) が返ります。

- `help()`: APIの使い方の説明
- `getCatalog()`: キャラクタ・技・特性・持ち物・性格の一覧 (enum名と日本語名)
- `getScreen()`: 現在の画面の情報と、その画面で使える操作の説明 (`actions`)
- `waitForInput({ since })`: 次に操作が必要になるまで待ち、画面の情報とバトル中のイベント (メッセージ・HP等) を返す (既定30秒で打ち切り)
- `saveTeam(team)`: バトルチームの保存
- `openCasualMatch()` / `setUpCasualMatch({ team, trainerName, passphrase })` / `startMatching(mode)`: カジュアルマッチの準備とマッチング
- `selectCharacters([...])`: 選出
- `submitCommands({ own0: {...}, own1: {...} })`: バトルのコマンド入力
- `forfeit({ confirm: true })`: 降参

操作の関数は `{ ok: true }` か `{ ok: false, error: "理由" }` を返します。エラーの場合は、理由を読んで入力を直してください。
非同期の関数 (`waitForInput`) を、ブラウザ操作ツールのJavaScript実行機能から呼ぶ場合は、先頭に `await` を付けてください。

## ユーザーと対戦するときのお願い

- **画面に表示されない相手の情報は見ないでください。** APIは画面に表示される情報だけを返します。(相手のHPは割合のみ、戦況は「状況」ダイアログと同じ内容です。)
  APIを経由せずに、アプリの内部状態・通信の中身・サーバの状態を調べることはしないでください。
- マッチングの開始 (`startMatching`) は、対戦相手のユーザーの準備ができてから行ってください。マッチングには60秒の制限時間があります。
  同じ「あいことば」(数字8桁) を設定した人同士でマッチングします。
- 自分のチームの中身は、対戦が終わるまで相手のユーザーに伏せてください。
- レギュレーション (禁止伝説の数等) や、使ってよいキャラクタの制限は、対戦前にユーザーと確認してください。
- コマンド入力には制限時間 (45秒) があります。期限を過ぎるとバトルが継続できなくなります。

## リンク

- ゲーム: https://pugmon.pages.dev/
- AI操作モード: https://pugmon.pages.dev/?agent=1