All 22 apps

CandyTetris

Tetris on the SugarCraft stack

inspired by Broderick-Westrope/tetrigo game tetris srs 7-bag

CandyTetris code coverage

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.

KeyAction
← / →Move left / right
↑ / xRotate clockwise
zRotate counter-cw
aRotate 180
↓Soft drop
SpaceHard drop
cHold piece
pPause / resume
hKey reference — opens/closes the live card
rNew game (asks first during play, instant after game over)
qQuit (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 h press) 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_COLOR and CLICOLOR=0 re-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 hatches CLICOLOR_FORCE=1 and FORCE_COLOR vouch 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

SRS rotationFull Super Rotation System — kick tables from the Tetris Company Guideline lineage (the code cites tetris.fandom.com/wiki/SRS), two of them: J/L/S/T/Z and I piece. Each transition tries the naive rotation plus the table's five offsets — up to 6 candidates, first fit wins (the list's own first entry repeats the naive `(0, 0)`). The board y-axis is inverted exactly once, in Piece::rotationsWithKicks.
7-bag RNGUniform shuffle of the seven pieces; an injectable RNG closure makes tests and replays reproducible. 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 center: 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

Try the quickstart →

API

ClassMethodDescription
Tetrominocases() / color()Backed enum of the seven kinds; 256-color code per kind
Piecerotated(delta) / moved(dx, dy)Immutable transforms (withX/withY for placement)
PiecerotationsWithKicks(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)
Boardplace(piece)Lock a piece's cells into the grid
Boardfits(piece) / dropPiece(piece)Legality gate and resting-position query
BoardclearLines() / isPerfectClear()Clear completed rows; true iff the grid ends empty
Bagnext()Returns [Tetromino, advanced Bag] — value semantics
Bagpeek(n)Pure preview; mutates nothing and consumes no draws
ScorewithLines(count)New Score: NES base × (level+1), lines, level re-derived
Gamestart() / update(msg)TEA model: every message yields [Game, ?Cmd] — the literal wire type is array{0: Game, 1: ?\Closure}
SrsKickTablekicks(piece, from, to)Return kick offsets for a rotation transition
SrsKickTableallKicks(piece)Return all transition tables for a piece
Scoring\TSpindetect(board, piece, lastActionWasRotation)Center-diagonal 3-corner rule; returns TSpin(active, mini)
Scoring\TSpinT_SPIN_POINTS / T_SPIN_MINI_POINTSBase score constants (400 / 100, scaled by level+1)
GamestartWithLockDelay()Seed a game with a custom lock-delay window (SRS QoL knob)
GameaddGarbageRows(count)Push incoming garbage in from the bottom; versus mode's opponent channel
TetrominorgbColor()The piece's 24-bit truecolor value as an int
ScorewithDropPoints(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

Play

Full game with ghost piece, hard drop, level-driven gravity.
Hold demo

Hold

Piece hold and swap with the sidebar hold card.
VS computer

VS Computer

Split-screen match against the built-in AI opponent.
VS computer, simple

VS Computer (simple)

The versus match from its opening seconds — the same command as above, filmed shorter; there is no starting-level flag to set.