Rule layer#

The AI has two parts: judgment, which scores boards and candidates, and the rule layer, which answers questions about the ruleset. The rule layer is the source of truth. The engine and the judgment adapt to it, not the other way around. Each answer uses the game state at the time of the question, as described in AI interface.

Glossary#

The board#

The rule layer declares the board type, which serves as the canonical definition. The engine uses it to get the board's width and height rather than setting its own. The AI's judgment and movegen must use the same board and ruleset types; a mismatch fails to compile when the engine passes its board to either.

In the ruleset these docs describe, the board is 10 cells wide and 24 rows tall.

A ruleset can also declare a visible height: the row above which a piece that locks counts as topping out. The match layer asks for it when the ruleset provides it.

The ruleset#

The ruleset declares its mino types and rotation system. The ruleset these docs describe is deliberately simplified: its tetromino set and SRS rotation system with kicks come from the movement library fast-reachability, rather than the rule layer. A ruleset that needs different pieces or kicks defines them in the rule layer instead.

What the engine asks#

The engine asks one question:

• It asks for the absolute entry spot for a piece. This spot is the same in every situation. In the ruleset these docs describe, it is unrotated and sits near the top, just left of center. The AI starts from this suggestion and adjusts it to match the real game's entry behavior.

The ruleset also declares the bag: the full mino set drawn in shuffled order to fill each player's piece queue. In the ruleset these docs describe, that means all seven tetrominoes. The match simulation uses that draw (see Match API).