API Examples

Game Protocol Sequence

Below is a sequence diagram showing the full communication flow between the Gamemaster VM and the four Bots. The diagram illustrates key events during a game:

1. Game Started Notification: all 4 bots are notified concurrently with their team, role, and board view. Spymasters see card types, guessers don’t.
2. Turn Cycle: the game alternates between a spymaster giving clues and their guesser making guesses. After one turn the next team gets to go.
3. Strike System: error handling where bots accumulate strikes for timeouts or invalid responses, potentially leading to disqualifications.
4. Game End Notification: when the game ends all bots receive a notification.

Bot Registration and Unregistration

The Python bot template uses an ASGI lifespan wrapper to handle registration on startup and unregistration on shutdown. This is triggered by signals from the ASGI server (e.g., Uvicorn) when the process starts or receives SIGTERM/SIGINT.

1. On startup: Bot reads team token, calls RegisterBot, stores bot_id
2. When running: Bot responds to game events (GameStarted, GiveClue, MakeGuess, GameEnded)
3. On hhutdown: Bot reads token, calls UnregisterBot, clears state

The unregistration puts the bot in an “unregistering” state where it completes any active games before the port is freed.