CandyFlappy
Flappy-Bird in your terminal
Physics-driven flap game — the bird's vertical motion is a SugarSpring projectile (gravity + an upward velocity kick on each tap), pipes scroll left at a fixed cell rate, collision is per-cell. Pure-state Game class; the renderer is a one-pass canvas fill.
Install
Pre-1.0 the package publishes a dev branch only, so pull it in explicitly as :@dev:
composer require sugarcraft/candy-flappy
Quickstart
# Monorepo clone — per-lib install, then the checked-in bin:
cd candy-flappy && composer install && ./bin/candy-flappy
# Composer install — the vendored console bin:
vendor/bin/candy-flappy
# Or download the standalone .phar release from GitHub and run it with php.
// Programmatic:
use SugarCraft\Core\Program;
use SugarCraft\Core\ProgramOptions;
use SugarCraft\Flappy\Game;
(new Program(Game::start(),
new ProgramOptions(useAltScreen: true)))->run();
What's in the box
Real physicsBird movement is a
Projectile with gravity vector. flap() rebuilds the projectile with an upward velocity kick — same trick the original flapioca uses, just expressed as projectile state.Pipe spawningA new pipe pair every
PIPE_EVERY ticks; the gap row is sampled from the injected PRNG so tests pin layouts deterministically.Tick-driven
Game::subscriptions() arms Subscriptions::withTick('game-tick', Game::TICK_SECONDS) — TICK_SECONDS is 1/Bird::TICKS_PER_SEC, exactly 1/30 s. Each tick advances physics, scrolls pipes and checks collision; the subscription goes empty on crash, on a too-small viewport, and under the NoTty refusal posture.Per-cell collisionBird's row is rounded to a cell index; collision = bird column matches a pipe column AND the row is outside the open gap.
Ready cardThe board opens frozen; the first flap starts the run.
r reseeds (mid-flight too); q / Esc / Ctrl+C quit — a qualifying mid-flight score is settled before the process exits.Score on passEvery tick that moves a pipe past the bird's column bumps the score.
Variable difficultyPipe gap shrinks from 6 cells down to 3 as score increases — every 5 points the gap narrows by 1 cell, making the game progressively harder.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by flapioca (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Game | init() | TEA init hook — returns null; the tick cadence rides subscriptions() |
| Game | start($rand, $configDir) | Build the ready board (world frozen until the first flap) |
| Game | update($msg) | TEA reducer: keys/ticks/resize/profile → [new Game, optional Cmd] |
| Game | view() | Full ANSI frame (delegates to Renderer::render) |
| Game | subscriptions() | 1/30 s tick subscription; empty when crashed or the terminal cannot play |
| Game | withHighScore($score) | New Game with $score merged into the records if it beats the best (no disk write) |
| Game | highScore() / highScores() | Current best / the kept top-ten record list |
| Game | settleOnExit() | Idempotent process-boundary high-score save (signal-death safety net) |
| Game | tickN($n) | Apply n physics ticks in sequence (deterministic test helper) |
| Bird | flap() / tick() | Projectile velocity kick + one physics step (on Bird, not Game) |
| Bird | row() | Bird y rounded to its playfield row index |
| Pipe | collides($col, $row) | Per-cell test against the open gap band of the pair |
| Pipe | tick() / isOffScreen() | Slide the pair one cell / whether it has left the field |
| PipeGenerator | gapHeightForScore($score) | Gap height for a score: starts at 6 cells, shrinks one every 5 points, floors at 3 |
| PipeGenerator | makePipe($score, $rand) | Spawn a pair; the gap shrinks 6→3 as score climbs |
| Renderer | render($game) | Compose a frame for any Game state (static) |
| Program | new($game, $options) / run() | sugar-core event loop; run() returns the final model |
Demos.
The demo below is VHS-recorded by CI: the .vhs/play.tape script drives ./bin/candy-flappy itself — not the examples/ scripts — and the workflow re-renders the GIF on pushes that touch it.