From TetrisWiki
Jump to navigation Jump to search

TETR.IO map format

Ambox stub.png
This section is a work in progress. (posted Wed 14 Jul 2021)
It will be fully realized within the week, I swear. ZaptorZap (talk) 02:51, 20 July 2021 (UTC)

The purpose of this format is simple: allow the end-user to define a custom playfield, as opposed to an empty one, before gameplay. This playfield is normally one which is created to test a variety of case scenarios which may be otherwise difficult and time consuming to test legitimately with regular TETR.IO mechanics. Such case scenarios may include:

  1. Testing the various kick tables, such as SRS, and their interactions with board states.
  2. Testing the top out mechanic and its interaction with the initial rotation system and/or initial hold system.
  3. Testing whether or not TETR.IO can handle unexpected line clears, such as T-Spin Mini Quads, or line clears consisting of 5 or more rows cleared at once.

Because of these reasons, the proprietary TETR.IO map format has likely existed as long as TETR.IO itself. Despite this estimated age however, use of the custom map systems were limited to the developer[note 1], that is, until the ZEN mode update released. This is due to the simple fact that ZEN progress is stored clientside, and this progress includes board state.

Technical explanation of the format

TETR.IO maps consist of the following characters exclusively:

Letter/symbol Description
_ Empty playfield cell
z Z block
l L block
o O block
s S block
i I block
j J block
t T block
# Garbage block
@ "Dark garbage" block[note 2]
? Queue override wildcard

These characters are then used in a text string 400 characters in length. This is due to the TETR.IO playfield itself containing 400 cells: 10 columns across and 40 rows tall. Maps are defined starting from the very top of a TETR.IO playfield, at row 40, column 1, and defined column by column: left to right; row by row: top to bottom. If an map of invalid length is specified, such as a map with only 3 characters in it, or a map with 407 cells defined, the map simply will not load, creating an empty field. If a map of correct length is defined, and it includes invalid characters, such as the letter "m", then TETR.IO will will continuously run into undefined behavior errors, fail to render the board, and run at an increasingly slow framerate.

Queue override wildcard

The queue override wildcard ("?") is added at the end of the 400 character map data and consists exclusively of the seven pieces. If invalid characters, such as the letter "v" or the symbol "#" are entered, TETR.IO will simply skip over the invalid data and continue to parse the rest of queue data. Queue data may be practically infinitely defined, as the specific limits of queue data have not been researched. After queue data has been used up, TETR.IO will revert to the chosen random generator(by default, this is the 7 BAG generation scheme) as if the first piece randomly generated was the first piece randomly generated.[note 3]

In addition to the next queue data, you may furthermore define one singular held piece by adding a secondary "?" symbol[note 4]. Once again, this held piece may only be one of the seven pieces. If you define an invalid piece, such as the "@" symbol, or a letter "q", the game will act as though invalid map data was defined(slowdown / failure to render the board / undefined errors). If a user attempts to hold with this invalid piece, however, TETR.IO will irreversibly crash.

Accessing/importing your created maps

External links: where to create a TETR.IO map with straightforward tools


  1. Before the ZEN mode update, players had one chance to play with a custom map. Custom maps were defined in QUICK PLAY during April Fools' 2020.
  2. Dark garbage is garbage which cannot be cleared. Any row with dark garbage on it is rendered unclearable due to this property of the block. It was officially used during the April Fools' 2020 celebration.
  3. With this limitation, you may not create maps which start with half a bag and have the game randomly generate the rest of the queue, for example.
  4. You may define an empty next queue+a custom held piece by simply adding two question marks at the end of map data, and then adding your specified piece. If you add three question marks, the third question mark will mark the end of map data, and any characters afterwards will simply not be parsed