Game Arena Python SDK

Build Python bots for Game Arena. Implement on_move(); the SDK handles authentication, matchmaking, game connections, and the turn protocol.

Requires Python 3.11+. Game rules and board formats live in the Bot Docs page of the Game Arena web app.

Install and prepare

pip install --upgrade game-ai-arena-sdk

Use SDK 0.7.0 or newer for domain-based arena configuration.

Create a bot in the web app and save its Bot ID and API key. The key may only be shown once.

Your first bot

This complete FlipFlop bot chooses a random legal move:

import random

from game_ai_arena_sdk import Bot, GameStateLoop, Move, start_continuous


class MyBot(Bot):
    async def on_move(self, state: GameStateLoop) -> Move:
        piece = random.choice(state.legal_moves)
        destination = random.choice(piece.valid_moves)
        return Move(from_pos=piece.pos, to_pos=destination)


bot = MyBot(bot_id="YOUR_BOT_ID", api_key="YOUR_API_KEY")

if __name__ == "__main__":
    start_continuous(bot)

python my_bot.py

start_continuous() verifies and displays the bot's registered game and arena before joining ranked matchmaking. Its compact live display shows the runner state, opponent, Bot Run record, and last committed result without flooding the terminal. Its commands are pause, resume, status, stop, help, display compact, and display verbose. Commands remain editable while games update the display. Stop and Ctrl-C finish any active game before disconnecting.

Adapt it for your game

Always choose from state.legal_moves, then preserve the fields required by that game:

# FlipFour
side = piece.name if piece.pos == "HAND" else None
return Move(from_pos=piece.pos, to_pos=destination, side=side)

# Amoeba
return Move(
    from_pos=piece.pos,
    to_pos=destination,
    splitting=piece.splitting,
)

Missing these fields is a common cause of INVALID_MOVE.

Build a better bot

The random bot only proves the connection works. A stronger bot should:

1. Parse state.board using its game's documented format.
2. Evaluate every legal action from state.my_side using heuristics, search, or a model.
3. Return the best action with its game-specific fields intact.
4. Run in Practice Mode before entering ranked play.

Keeping this logic in choose_move(state) -> Move separates bot strategy from SDK lifecycle code.

Execution modes

start*() functions block and suit ordinary scripts. run*() functions are coroutines for code that already uses asyncio.

start_continuous() detects the registered game and adds terminal controls. Compact display is the default; pass display="verbose" or switch modes while running. Redirected input or output automatically uses plain verbose output. Headless run_continuous() requires an explicit GameType and returns the final immutable RunnerStatus, including safe failure details when the runner fails.

Practice Mode connects directly to a room from the web app and does not affect rating:

from game_ai_arena_sdk import start_practice

start_practice(
    bot,
    room_id="ROOM_ID_FROM_PRACTICE_ARENA",
)

For custom operation, ContinuousRunner provides pause(), resume(), status(), stop(), and wait().

If phase visibility changes while the bot is queued, the continuous runner rejoins automatically on the same Bot Run and preserves whether it was paused. A switch to Blind removes an earlier rating from public status and the compact display even when the bot is already playing.

Core data

board is game-specific. legal_moves is the server-provided set of allowed actions. MatchFinishedResult is immutable and arrives after a continuous ranked result is committed; its rating is absent during phases that hide it.

Lifecycle hooks

Override only what you need. on_move() is the only required hook.

There is no on_error hook. Handle decision errors inside on_move() and SDK failures around the chosen entry point.

Errors and troubleshooting

Game-server protocol failures raise GameArenaProtocolError with code, message, and optional details. Continuous play fails closed after an uncertain failure instead of silently joining another game.

For game rules, coordinates, strategy, arena configuration, and deeper troubleshooting, open Bot Docs in the Game Arena web app.