AI interface#

The engine manages each decision: it expands placements, maintains caches, and chooses a move. The AI is the pluggable part that supplies the judgment. For every call, the engine passes along the current game state, so the AI responds to the position and search depth at hand rather than to the game as a whole.

Glossary#

Shared engine vocabulary (board, roof, placement, depth, horizon, hold, status, search budget) is defined in the Glossary. This page adds what is specific to the AI interface:

Where the engine calls in#

engine setup:    give the AI its configuration
each decision:   ask where each piece enters
                 evaluate each new board
                 score each candidate
                 read the peak and spread for the beam schedule

The built-in AI supports these interactions; the behavior, not the method names, defines the contract. During setup, the engine passes the AI its configuration. For each decision, the beam schedule reads the configured peak and spread (see Beam search).

Where a piece enters#

The AI helps choose the entry spot for every piece that enters during the search. The engine first asks the rule layer for a suggested spawn, then passes the AI:

• the piece that is entering,
• how many lines the placement before it cleared,
• the suggested spawn,
• whether the piece enters by hold swap,
• the board it enters on,
• the status carried to this node.

The AI returns the entry spot that the search uses.

The engine asks about each piece entry at every node. This includes the hold branch of the current decision, and the next piece at each child node (from either the queue or hold). Two paths can ask about the same piece at different depths and get different answers because each path has its own board and history. The runner can ask the engine for the same entry information when placing pieces itself. A hold-swap path starts from the entry spot returned by the AI, so the runner's replay matches the search.

Rulesets use that freedom. In tetr.io, for example, the entry spot moves up if the piece would collide with the stack at spawn or if the previous placement cleared lines, but only when the game's clutch option is on. An AI for that ruleset checks the board for a collision, reads the line-clear count, and knows from its configuration whether clutch is on. The engine provides those three pieces of information when the piece enters the search.

Gravity is another example. The suggested spawn is absolute, but by the time the engine finishes searching and the runner starts the move, the AI's answer determines the piece's actual y coordinate at entry.

An AI whose ruleset makes no entry adjustments returns the suggested spawn unchanged.

The evaluation#

The engine evaluates each new position once. The evaluation receives:

• the resulting board, in the engine's row form (one value per row, a bit set for each occupied cell) or as the rule layer's board type, whichever the AI provides an evaluation for,
• the board's roof,
• the environment, so an AI may look at the pieces still to come and at what the hold slot will hold.

What the evaluation measures is up to the AI. Typical examples include board-shape features such as bumpiness and aggregate height. An AI whose pieces behave differently depending on what follows them can read the queue as well. The engine caches each result under a key made from the board, its roof, and the piece that will be in hold (see Transposition table), so candidates that reach the same key share one evaluation.

The context step#

Context scoring runs for every candidate placement. It takes:

• the landing (see Movegen),
• the cached evaluation,
• the line clears the placement made,
• the board and its roof,
• the depth the placement is made at,
• the status carried from the parent node,
• the environment.

It returns the child's status, a running assessment used to rank candidates and carry match state forward, including line clears, combo, and back-to-back. Rewards can reflect events from the placement, such as a back-to-back chain, a combo, a spin, or whether a piece like the I was used or saved for later. These examples show what the inputs make it possible to judge. Which signals a particular AI uses is up to that AI.

Splitting evaluation into these two stages is what makes the first one cacheable. The Transposition table page explains the split in detail.

When the AI declares a fixed list of priority pieces, the environment also carries, for each one, how many pieces away it sits in the known preview.

The rule layer#

The rule layer answers what belongs to the ruleset rather than to judgment: the absolute entry spot, the bag randomizer, and the board and ruleset types the rule layer shares with movegen. It has its own page: Rule layer.

Optional hooks#

Most of the interface is optional. The engine detects which parts an AI provides and works with any subset of them:

• The evaluation may take the board in either form, and it may take the environment or leave it out.
• The context step may likewise be written with or without the environment.
• A custom board hash can replace the built-in one.
• A conversion from the board to the engine's row form can replace the built-in one.
• The AI can declare priority pieces, which the environment then reports distances for.
• The AI can fingerprint the state it carries, which lets the search collapse duplicate arrivals (see Beam search).
• The AI can evaluate several boards at once instead of one at a time.
• The AI can prepare state at the start of a search and at the root of a decision.