# TetrAIs 3D Rules Specification

This document describes the scoring and progression rules implemented by `src/game/TetraisEngine.js` and `src/game/constants.js`.

## Clear Units

A lock can clear complete horizontal layers (Y), X-axis lines, Z-axis lines, and a perpendicular X/Z clear. The score-clear count is:

`min(12, Y layers + X lines + Z lines + 2 * perpendicular-clear flag)`

The perpendicular-clear flag is either 0 or 1 for a lock, regardless of how many intersecting lines were removed. Z-axis lines and perpendicular X/Z clears are enabled above depth 6 (depth 7-10); at depths 1-6, only X-axis lines clear.

## Base Score

Base score is `100 * simultaneous clear units`, at every grid depth: 1 line = 100 points, 4 lines together = 400 points, up to 1,200 points for 12 units.

| Clear units | Base points at any depth |
| ---: | ---: |
| 1 | 100 |
| 2 | 200 |
| 3 | 300 |
| 4 | 400 |
| 5 | 500 |
| 6 | 600 |
| 7 | 700 |
| 8 | 800 |
| 9 | 900 |
| 10 | 1,000 |
| 11 | 1,100 |
| 12 | 1,200 |
| 0 | 0 |

## Multipliers

The final score for a lock is `100 * simultaneous clear units * difficulty multiplier * bonus multiplier`. Grid depth does not change scoring. No score is added for a zero-unit clear. Before any earned challenge bonus, one clear unit is worth 100 points on Easy, 150 on Medium, and 200 on Hard.

| Difficulty | Difficulty multiplier |
| --- | ---: |
| Easy | 1x |
| Medium | 1.5x |
| Hard | 2x |

The bonus multiplier is 1x unless an active bonus challenge is completed on that lock. A completed challenge uses its displayed reward: 5x, 10x, or 15x. The reward multiplies the score for that clearing lock only.

## Bonus Challenges

Challenges are selected from the depth-eligible challenge list, with reward and duration selected from their configured lists. Challenges are considered after a scoring event when the previously accumulated clear count is a non-zero multiple of three and that milestone has not already triggered. A challenge is completed by a later lock that satisfies its named line-clear condition before its countdown expires.

In deterministic simulation, challenge time advances by fixed-step simulation time, not wall-clock time. The interactive game retains its real-time countdown.

## Other End Conditions

The piece counter increments on each lock and is reduced by five for each counted clear unit (the piece-counter clear count treats the perpendicular flag as one). It is clamped to 0..25. Reaching 25 locks, or occupying any cell in the top layer before a new piece spawns, ends the game. Piece-counter units are separate from score-clear units.