🡄 Previous

Next 🡆

Contents > Introduction


TetrominoScript (TS) is a language that provides a concise way to express where to put the pieces. It compiles to IL.

TS refers to each of the nineteen distinct tetromino orientations with a mnemonic consisting of the tetromino type concatenated with the first letter of “down”, “left”, “up”, “right”, “horizontal”, “vertical”, or nothing for the O-tetromino:

Mnemonic Table

TS specifies locations relative to the center block of each tetromino.

TS has three instruction types. The first directs the agent to hard drop a tetromino. It consists of the tetromino's mnemonic, m, and the hard drop's column index, xh:

m xh

It commands the agent to:

  1. Discard tetrominoes until the randomizer spawns the one specified by m's type.
  2. Rotate the tetromino into m's orientation.
  3. Shift the tetromino to column xh.
  4. Hard drop the tetromino.

The example below demonstrates this instructions type.

td 1
jd 5
zh 9
o 13
sh 16
ld 20
ih 25

The program instructs the agent to produce the following.


The second instruction type directs the agent to perform a semihard drop followed by a hard drop in a different column. It consists of the tetromino’s mnemonic, m, the semihard drop’s column index, xs, the semihard drop's row index, ys, and the hard drop's column index, xh:

m xs ys xh

It commands the agent to:

  1. Discard tetrominoes until the randomizer spawns the one specified by m's type.
  2. Rotate the tetromino into m's orientation.
  3. Shift the tetromino to column xs.
  4. Semihard drop the tetromino to row ys.
  5. Shift the tetromino to column xh.
  6. Hard drop the tetromino.

If a gravity drop occurs after step 4, but before step 5 finishes, the agent will misplace the piece. To avert that possibility, the agent times a semihard drop to coincide with a gravity drop. How it does that depends on the Tetris implementation. For instance, if the agent emulates a semihard drop with a finite number of soft drops, then it will let a gravity drop serve as the final soft drop. That maximizes the time to shift from column xs to column xh. The strategy works as long as the distance between the columns does not exceed the maximum shift achievable in the period between gravity drops.

The following code demonstrates the second instruction type.

td 1 15 2
jd 1 15 2
zh 1 15 2
o 1 15 2
sh 1 15 2
ld 1 15 2
ih 1 15 2

Those are the instructions for the structure below.


The third instruction directs the agent to build a previously defined structure. It consists of the structure's name, s, and the coordinates of where to build it, x and y:

s x y

The TS compiler replaces the instruction with the contents of s’s program, such that the column and row arguments of n’s instructions are incremented by x and y, respectively. The compiler recursively repeats that process until all what remains are instructions of the first and second types. To ensure the process finishes, the compiler does not permit circular dependencies.

The following code demonstrates the third instruction type by referencing the prior examples.

example1 3 0
example2 14 2

The compiler expands those instructions, offsetting the column and row indices per the provided coordinates:

# example1 3 0
td 4
jd 8
zh 12
o 16
sh 19
ld 23
ih 28

# example2 14 2
td 15 17 16
jd 15 17 16
zh 15 17 16
o 15 17 16
sh 15 17 16
ld 15 17 16
ih 15 17 16

Line comments begin with # and end with newline, as demonstrated by lines 1 and 10. TS does not support block comments.

The code above instructs the agent to create the structure below.


An output node is a segment of a structure’s surface. An input node is a segment of the foundation on which a structure is built.

TS provides directives for declaring input and output nodes:

in n x0 y0 x1 y1 … xN−1 yN−1

out n x0 y0 x1 y1 … xN−1 yN−1

The node type, in or out, is followed by the node name, n. The successive coordinates, xi yi, refer to the lower-cells of the node's vertically-adjacent pairs. Each coordinate is either a single integer or a range of integers, min..max.

The example below declares five input nodes.

in a 0 0
in b 2..4 0
in c 6 0
in d 7 0
in e 9..10 0 12..13 0

Node a is a single pair. Node b is a horizontal line consisting of three pairs. Nodes c and d are adjoining, single pairs. Node e is disjoint. They are illustrated below, where nodes a, b, c, d, and e are set to 0, 1, 0, 1, and 0, respectively.


🡄 Previous

Next 🡆