PokéArena

Submit your action for this turn AND get the result back. Returns the next fog-of-war view once it is your turn again, or terminal:true with the winner when the battle ends — so a turn costs one call, not two. If the action was illegal, `error` says why and names the legal actions, `ready` is still true and the turn is still yours: pick from the view and call act again. `ready:false` means the result had not arrived within wait_seconds (only possible against a slow human opponent); call wait to keep blocking.

Optional — start_battle's briefing already lists every legal species, so use this only to search a large roster or look something up mid-battle. Search the curated Pokédex by name substring. Returns lightweight matches (dex_no + name + types). The dataset is filtered to a subset — not every species is present. Call this first to discover what's available, then get_pokemon for the species you want to use in submit_team.

Optional — needed only for a species' full legal move list; the briefing already covers species, items and natures. Fetch full details for one species by dex_no, including its legal move list and ability slots. The move .id values and ability slugs returned here are exactly what submit_team expects (moves go in the picks[].moves array; the ability goes in the optional picks[].ability field — omit to default to abilities[0]).

Attach to an EXISTING battle on a separately running PokéArena arena — needs a battle_id someone already created and a gateway that is up. If you just want to play, use start_battle instead: it needs none of that. Use this only to face a human or another agent in a live arena. For a live vs-AI battle pass only battle_id; for pvp pass slot and join_token.

Cleanly close the WebSocket and release the session. If the battle is still in progress this is a forfeit. After this, join_battle can be called again.

Optional — start_battle's briefing already lists every legal item. List every held item a team may use, with a one-line description of what it does in this engine. Items are not species-restricted: any item here is legal on any Pokémon, one item per Pokémon. Use the .id values in the optional picks[].item field of submit_team.

Optional — start_battle's briefing already lists every nature and the same caps. List the 25 natures and the numeric team-building rules. Each nature raises one stat by 10% and lowers another by 10%; the five with no 'plus'/'minus' fields are neutral and change nothing. Also returns the battle level and the EV/IV caps submit_team enforces, so a spread can be planned against the real budget rather than an assumed one. Use a nature .id in the optional picks[].nature field of submit_team.

START HERE — this is the entry point for playing PokéArena. Starts a real 6v6 Pokémon battle against the built-in AI, running entirely inside this process: no server to run, no docker compose, no API key, no second player, no setup of any kind. The response includes a `briefing` listing every legal species, item and nature plus the format rules, so you can write a team straight away — you do NOT need find_pokemon / get_pokemon / list_items / list_natures first. Then: submit_team (a Showdown paste), then act repeatedly until it returns terminal:true. Three calls reach the first move. Optional: `seed` makes the battle exactly reproducible; `opponent` picks 'heuristic' (default) or 'expectimax'.

Submit your 6-Pokémon team during the picker (OPEN) phase. Required after start_battle or join_battle while phase is 'open'. Write the team in the `team` field as a Showdown paste — one block per Pokémon separated by blank lines, using display names, e.g. "Alakazam @ Life Orb / Ability: Synchronize / EVs: 252 SpA / 252 Spe / Timid Nature / - Psychic / - Recover" with each on its own line. Only the species line and one move are required per Pokémon. start_battle's `briefing` lists every legal species, item and nature, plus the clauses — note the Item Clause bans two Pokémon holding the same item, which standard competitive play allows. On rejection this returns accepted=false with a `report` naming EVERY problem at once, each with the legal alternatives, so one fix pass is enough. `report.warnings` flags choices that are legal but probably weaker than intended. (`picks` remains as a structured alternative if you already have that shape.)

Rarely needed: act already returns the next view, so the turn loop does not require this. Use it only to re-read the current fog-of-war state without acting.

Block until it's your turn, the battle ends, or the timeout elapses. You need this only for the FIRST turn (after submit_team) and to resume after an act that returned ready:false — act already returns the next view, so the steady-state loop is just act → act → act.