Overview#

This page follows one engine decision from input to output. Each stage has its own page, linked below. The AI supplies the judgment; see AI interface for details.

Glossary#

One decision, end to end#

game state -> prepare -> search -> decide -> command string

The runner normally calls the engine once per placed piece. Each call includes the full game state:

• the playfield, 10 cells wide and 22 rows tall, plus one row above it for incoming garbage (the engine's internal board is taller still; the rule layer declares it),
• the active piece with its position and rotation, in the runner's coordinates,
• the held piece and whether holding is currently allowed, plus whether 180-degree spins are allowed,
• the known preview, whose length sets how deep the search can look; when only one piece of the current bag is still unseen, the engine deduces it and looks one piece deeper (see Bag deduction),
• the match state: the back-to-back flag, the combo counter, the incoming attack, and the runner's combo table,
• the search knobs: how deep into the known preview to look, and how much search work to spend,

Before searching, the engine prepares the current state:

• It loads the playfield and the active piece's position.
• It adds the match state (combo, back-to-back, and incoming attack) to the running status.
• It deduces the last unseen piece of the current bag when only one is left, and adds it to the queue the search uses (see Bag deduction).
• It updates the caches, reusing the transposition tables as described in Transposition table, unless the call brings different AI parameters, in which case it clears them.

The beam search expands placements one depth at a time under a precomputed beam limit schedule. It scores candidates using cached evaluations and stops early if the whole beam agrees on the first placement. The move generator (movegen) supplies the reachable spots for each piece and identifies spin landings.

The decision is the best candidate from the deepest completed layer, traced back to its first placement. It specifies where the active piece should land, or whether to swap in the held piece first. The path generator turns that choice into a command string.

What comes out#

The engine returns one of three command strings:

• A movement path carries the active piece to the chosen landing, including any spin adjustments. The path may begin with a hold swap when the chosen placement uses the held piece. The runner executes the path, and the piece drops.
• The hold command is the hold input on its own. The engine answers this way only when the hold slot is empty, the known preview is empty, and holding is currently allowed: it swaps the current piece into hold, and the runner's next piece becomes active.
• A hard drop means the engine fell back to the simplest move: the search chose no placement, or the chosen landing had no input path. The piece drops straight down from where it is and locks.

Once the piece lands, the runner calls again with the updated state and the cycle repeats.

What the engine remembers between calls#

Each player has a separate engine instance, keyed by player ID, and calls for that player are handled one at a time. Between calls, the instance keeps:

• the transposition tables and predicted board, so previously evaluated positions can be reused when the prediction holds (see Transposition table),
• the runner's combo table, cached the first time it is used,
• the AI's current parameters. When a call brings different parameters, the engine clears the transposition tables and forgets the prediction.

With the same game state, a decision is reproducible. The search budget is a count rather than a time limit, and ties are always broken the same way.