🎮 CandyTetris
Tetris on the SugarCraft stack
SugarCraft runtime, SugarStyle for rounded borders + per-piece colours, deterministic 7-bag RNG, ghost piece, hard drop, hold, level-driven gravity ramp, NES-style line-clear scoring. Full SRS wall-kicks via official Tetris Association tables, T-Spin detection via the centre-diagonal 3-corner rule, Back-to-Back (1.5×) and combo bonuses, and perfect-clear detection (+5000/level).
Install
composer require sugarcraft/candy-tetris
# or run the shipped binary from a clone:
composer install
./candy-tetris/bin/candy-tetris # single player
./candy-tetris/bin/candy-tetris --vs # VS the computerQuickstart
./bin/candy-tetris
# Controls
# ← / → Move left / right
# ↑ / x Rotate clockwise
# z Rotate counter-cw
# ↓ Soft drop
# Space Hard drop
# c Hold piece
# p Pause / resume
# r Restart after game over
# q QuitWhat's in the box
SRS rotationFull Super Rotation System — official Tetris Association kick tables for J/L/S/T/Z and I piece. Tries up to 5 offsets per rotation transition; the first that fits the board is used. The board y-axis is inverted exactly once, in Piece::rotationsWithKicks.
7-bag RNGDeterministic shuffle of the seven pieces; injectable RNG closure for reproducible tests. Value-semantic: next() returns the piece plus an advanced bag, peek() is a pure preview that consumes neither state nor draws.
Ghost pieceTranslucent preview at the hard-drop landing position.
Hard drop / holdSpace-bar drop; level-driven gravity speed-up at every 10 lines. Lock delay (500 ms window, 15-reset cap) in single player; VS boards lock on the grounding tick.
Line-clear scoringNES-style base points — 1 → 40, 2 → 100, 3 → 300, 4 → 1200 — multiplied by (level + 1); the T-Spin and B2B bonuses follow the modern Guideline.
T-Spin (3-corner rule)Guideline detection on the diagonals of the T's centre: 3+ filled corners (wall/floor count as filled) score a full T-Spin (400 × level+1); exactly 2 with one on the nub side score a Mini (100 × level+1); 2 back corners score nothing. A Mini clearing 2+ lines is promoted to full.
Back-to-Back (B2B)1.5× multiplier carried by consecutive difficult CLEARS (Tetris, or a full T-Spin that cleared lines). Resets on an ordinary 1–3 line clear; a clear-less lock — spin or quiet — leaves the chain untouched.
Combo counterConsecutive line clears add combo × 10 × (level+1) bonus points; resets to 0 on a zero-line lock.
Perfect clearClearing the full board awards +5000 × (level+1) bonus — detected via Board::isPerfectClear().
Pure-state classesTetromino, Piece, Board, Bag, Score, Game — immutable value semantics throughout, each individually testable without booting the runtime.
Source
- Source on GitHub
- Full README
- Originally inspired by tetrigo (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Tetromino | cases() / color() | Backed enum of the seven kinds; 256-colour code per kind |
| Piece | rotated(delta) / moved(dx, dy) | Immutable transforms (withX/withY for placement) |
| Piece | rotationsWithKicks(board, delta) | Candidate positions in SRS kick order (naive first) |
| Board | new(rows) | 10-wide grid (4 hidden + 20 visible rows; dims fixed) |
| Board | place(piece) | Lock a piece's cells into the grid |
| Board | fits(piece) / dropPiece(piece) | Legality gate and resting-position query |
| Board | clearLines() / isPerfectClear() | Clear completed rows; true iff the grid ends empty |
| Bag | next() | Returns [Tetromino, advanced Bag] — value semantics |
| Bag | peek(n) | Pure preview; mutates nothing and consumes no draws |
| Score | withLines(count) | New Score: NES base × (level+1), lines, level re-derived |
| Game | start() / update(msg) | TEA model: every message yields [Game, ?Cmd] |
| SrsKickTable | kicks(piece, from, to) | Return kick offsets for a rotation transition |
| SrsKickTable | allKicks(piece) | Return all transition tables for a piece |
| Scoring\TSpin | detect(board, piece, wasRotated) | Centre-diagonal 3-corner rule; returns TSpin(active, mini) |
| Scoring\TSpin | T_SPIN_POINTS / T_SPIN_MINI_POINTS | Base score constants (400 / 100, scaled by level+1) |
