Ranked Matches
How to connect your bot to ranked play
Prerequisites
- Sign in to RiichiLab with your GitHub account.
- Create a bot on the Bots page and copy the token.
- Complete bot validation to activate the bot.
Connecting
Connect your bot via WebSocket to the ranked endpoint and send your bot token in the Authorization header:
wss://game.riichi.dev/ws/ranked Authorization: Bearer <your-token>
If the token is invalid or the bot is not active, the server closes the connection with an error:
{"error":"Token verification failed: Bot is inactive"}Game Flow
- Your bot joins the matchmaking queue.
- The server matches 4 bots with similar ratings (see Matchmaking).
- A full hanchan (East-South) game is played.
- After the game, ratings are updated based on final placement.
- The server sends
end_gameand the bot should disconnect.
Bot Limits
| Limit | Value |
|---|---|
| Bots per user (4-player) | 4 |
| Bots per user (3-player) | 3 |
| Bot name length | 32 characters max |
| Bot description length | 100 characters max |
Managing Your Bot
All bot management is done from the Bots page in the web UI.
| Action | Description |
|---|---|
| Activate | Re-enable a deactivated bot for ranked play. |
| Deactivate | Temporarily remove a bot from ranked play. Rating is preserved. |
| Regenerate Token | Issue a new token. The old token is immediately invalidated. |
Bots cannot be deleted — only deactivated. This preserves rating history and game records.
Error Handling
Timeout
Each request comes with a time budget: a 3-second grace per action plus a 15-second time bank per kyoku (time beyond the grace is deducted from the bank). If your bot does not respond by the deadline (grace + remaining bank), the server applies a default action (tsumogiri on draw, pass on claims) and the game continues normally. Timeouts are never penalized.
Disconnection
If the WebSocket connection drops, all remaining actions default automatically. The game still completes and the result counts toward your bot's rating.
Invalid Actions
If your bot sends an action that does not match any legal action in possible_actions, or a message the server cannot parse, the engine fires a chombo (mangan-equivalent penalty) and ends the round. The server reports the verdict for every reply via action_ack events. See the MJAI Protocol page for details.