This version of the documentation is currently up-to-date for version 6.2.0 of TETR.IO (commit id e326977, March 16, 2022, 10:54 PM UTC).
This documentation is not finished. If you wish to contribute, pull requests are welcome.
This repository is dedicated to documenting the network protocol used by TETR.IO, as well as any other information that may be useful when developing a bot for TETR.IO. This is not the only way to develop a bot for TETR.IO—one may also directly interface with or modify the official TETR.IO client, in which case the information in this documentation is largely irrelevant. This documentation is primarily for standalone bots which run without using the official TETR.IO client, but extra non-bot information may be available for elements that could be useful to interface with programmatically and are not in violation of TETR.IO's rules.
Running a bot on a user account is a violation of TETR.IO's community rules and will result in your account being terminated. To run a bot, you must acquire a bot account (e.g.). To get one, message osk on Discord with a short outline of your bot's intended functionality (or email them, but they do not check emails as frequently). osk's contact info can be found here.
Bots can:
- Join public custom games.
- Join private custom games, given the room id.
- Create their own custom games.
- Use the social system.
Bots cannot:
- Play singleplayer modes.
- Join Quick Play.
- Play in Tetra League.
When venturing to create a bot, I highly recommend using a language which is either dynamic/duck typed (e.g. JavaScript/TypeScript or Python) or one which supports dynamic/duck typing in some form (e.g. C# via dynamic). Do not use a single monolith class to represent every message type. This will cause only pain and suffering. Trust me on this one.
The first and most important thing to do when creating a bot is to make it nontrivial to use unauthorized. This is good practice in general, but especially if your code is open-source it is critical to make sure that it's not easy for anyone without knowledge of code to enter their own user token into the bot and run it on their account. The best way to do this is to make an API call to the users/me API endpoint and refuse to run if the user's role is anything other than "bot".
Once you're done with that, the core of a TETR.IO bot is interfacing with the Ribbon system.
- Misc
- Network fundamentals
- Guides
- Game mechanics
- Ribbon messages
- Client
- Server
Hi! I'm Poyo. I wrote (most of) this documentation. I am not affiliated with TETR.IO or osk. All data here has been gathered via analyzing code and testing responsibly. Use this documentation at your own risk. Please enjoy! ❤