CandyTetris
Tetris on the SugarCraft stack
SugarCraft runtime, SugarStyle for rounded borders + per-piece colors, uniform-shuffled 7-bag (injectable source for deterministic tests), ghost piece, hard drop, hold, level-driven gravity ramp, NES-style base scoring with modern Guideline bonuses. Full SRS wall-kicks via the Tetris Company Guideline tables, T-Spin detection via the center-diagonal 3-corner rule, Back-to-Back (1.5×) and combo bonuses, and perfect-clear detection (+5000 × (level+1)).
Install
Requires php-cli 8.3+ with ext-intl and ext-mbstring. Both are hard-required transitively by sugar-core, whose cell-width math segments through ICU — on a bare php-cli machine composer install is the step that refuses, naming sugar-core.
# As a Composer consumer (run from your own project):
composer require sugarcraft/candy-tetris
./vendor/bin/candy-tetris # single player
./vendor/bin/candy-tetris --vs # VS the computer
# From a monorepo clone (run from the candy-tetris/ library directory):
cd candy-tetris && composer install
./bin/candy-tetris # single player
./bin/candy-tetris --vs # VS the computer
# As a standalone binary: the rolling latest phar, no install
curl -LO https://github.com/detain/sugarcraft/releases/download/candy-tetris/latest/candy-tetris.phar
php candy-tetris.phar # single player
php candy-tetris.phar --vs # VS the computer
Quickstart
# From the candy-tetris/ library directory:
./bin/candy-tetris
./bin/candy-tetris --vs # VS the computer
Controls
The shipped default keys. The on-screen help card, the versus strip, the intro card's key line, the one-row sidebar pointer, the confirm prompts and the --help screen are all derived from this one table — a remap (via $XDG_CONFIG_HOME/candy-tetris/keys.json) shows up wherever the game teaches its own keys. The key reference h paints the full card over the frame from any posture, even a floor-sized terminal where the sidebar card cannot fit.
| Key | Action |
|---|---|
| ← / → | Move left / right |
| ↑ / x | Rotate clockwise |
| z | Rotate counter-cw |
| a | Rotate 180 |
| ↓ | Soft drop |
| Space | Hard drop |
| c | Hold piece |
| p | Pause / resume |
| h | Key reference — opens/closes the live card |
| r | New game (asks first during play, instant after game over) |
| q | Quit (asks first during play, instant on menus and after game over; Ctrl+C leaves in one press) |
Terminal contracts
- The frame — the full single-player frame is 40×33; the honest floor is 40×24. Between them the sidebar reflows by budget, not by scroll: the help card gives way first and a one-row key pointer (the live
hpress) replaces it, so a floor terminal never loses every key at once. Below the floor a resize notice paints instead and play freezes until the terminal is big enough again — rows, not columns, are what the notice waits for. - The duel — the VS board has one posture: 54×33, exact. There is no compact versus frame; anything smaller answers the resize notice.
- No TTY, no game — a launch with no terminal to play on (stdin or stdout a pipe or redirect, or
TERM=dumb) is refused before anything paints: one plain line on stderr, zero escape bytes, exit code 1. - No color, still playable —
NO_COLORandCLICOLOR=0re-render the whole frame with zero SGR; shape carries every fact color used to carry, and empty cells render as·so the grid stays readable. The escape hatchesCLICOLOR_FORCE=1andFORCE_COLORvouch for the terminal and skip the no-TTY refusal — under either one escapes are painted into a redirect as if the terminal were there.
What's in the box
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-color code per kind |
| Piece | rotated(delta) / moved(dx, dy) | Immutable transforms (withX/withY for placement) |
| Piece | rotationsWithKicks(delta) | Candidate positions in SRS kick order (naive first); board-free — callers filter with Board::fits() |
| Board | __construct(cells?) | 10-wide grid (4 hidden + 20 visible rows; dims fixed by class constants, not settable) |
| 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] — the literal wire type is array{0: Game, 1: ?\Closure} |
| 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, lastActionWasRotation) | Center-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) |
| Game | startWithLockDelay() | Seed a game with a custom lock-delay window (SRS QoL knob) |
| Game | addGarbageRows(count) | Push incoming garbage in from the bottom; versus mode's opponent channel |
| Tetromino | rgbColor() | The piece's 24-bit truecolor value as an int |
| Score | withDropPoints(points) | Add drop points to the score; lines and level stay put (the game feeds 1 per soft cell, 2 per hard cell) |
Demos.
VHS-recorded GIFs of the shipped tapes. Regenerated automatically on every push that touches the source.
Play
Full game with ghost piece, hard drop, level-driven gravity.
Hold
Piece hold and swap with the sidebar hold card.
VS Computer
Split-screen match against the built-in AI opponent.