dbird leduftw
Use this command to install dbird:
winget install --id=leduftw.dbird -e A fully playable terminal recreation of the classic Flappy Bird game
Loading...
README
dbird
A fully playable terminal recreation of the classic Flappy Bird game.
Quick start
Requirements
- Rust 1.88 or newer — only for building from source
- An interactive terminal
The minimum terminal size is 36 columns by 20 rows. A window at least 36 rows tall is recommended for the fuller portrait view.
Download a prebuilt binary
Every release ships executables for macOS (Apple Silicon and Intel), Linux (x86_64 and arm64), and Windows (x86_64). Grab the archive for your platform from the latest release, extract it, and run dbird from a terminal — no Rust toolchain required. On Linux, audio uses ALSA (libasound2), which desktop distributions ship by default. If macOS Gatekeeper blocks a browser-downloaded binary, clear the quarantine flag with xattr -d com.apple.quarantine dbird.
Run from source
git clone https://github.com/leduftw/dbird.git
cd dbird
cargo run --release
Install
Install with a package manager:
cargo install dbird # crates.io, any platform with Rust
brew install leduftw/tap/dbird # Homebrew on macOS or Linux
winget install leduftw.dbird # Windows (pending winget-pkgs approval)
Or install the latest development version directly from GitHub:
cargo install --locked --git https://github.com/leduftw/dbird.git
dbird
Play
Controls
| Key | Action |
|---|---|
Enter | Start / retry |
Space, ↑, W, K, or Left Click | Flap during flight |
P | Pause or resume |
T | Cycle System / Light / Dark theme |
L | Show or refresh the global leaderboard in online mode |
Q, Esc, or Ctrl-C | Quit |
Pass through each pipe opening to score. Pipe speed, pipe spacing, opening size, and flight physics stay fixed for the entire run, just like the original game. Scores of 10, 20, 30, and 40 award Bronze, Silver, Gold, and Platinum medals respectively. If the terminal becomes too small, the round is safely suspended; enlarge it and resume when ready.
Retro-style sound effects accompany flaps, points, collisions, and result transitions. They were synthesized from scratch for dbird by assets/sounds/generate.py; provenance details are in assets/sounds/NOTICE.md.
The theme starts in System mode on every launch. On macOS and Windows it follows the current light or dark app appearance; press T to choose a daytime Light world, a nighttime Dark world, or return to System. The selection lasts for the current run, and --no-color remains the final override for terminal colors.
Offline and online play
Offline is the default and makes no network requests:
dbird
Online play is an explicit opt-in. Choose a public username with 3-16 ASCII letters, numbers, _, or -:
dbird --online BirdPlayer
The two modes keep independent best scores. Offline mode continues to use the local high-score file. Online mode uses the cloud score associated with that username; press L to see the global top ten and your rank. A private installation credential, the last confirmed cloud score, and any score awaiting retry are kept under dbird's local state directory. If the service is unreachable, gameplay continues and a new best is queued for the next online run.
Connectivity never selects a mode automatically. Internet availability can change during a run, and sending a public username and score should remain a deliberate choice.
The official leaderboard is hosted at dbird-leaderboard.leduftw.workers.dev and is configured automatically in normal builds. The Cloudflare Workers + D1 service lives in leaderboard/. Set DBIRD_LEADERBOARD_URL only to override the official service for local development or staging:
DBIRD_LEADERBOARD_URL=http://127.0.0.1:8787 \
cargo run --release -- --online BirdPlayer
See the leaderboard deployment guide for local development, deployment, cost notes, and the API's security boundary.
Options
--ascii use plain ASCII graphics
--no-color disable the color palette
--mute disable sound effects
--seed play the same deterministic course every round
--online opt in to the global leaderboard as this username
--reset-score clear the saved offline high score before starting
-h, --help show help
-V, --version show the version
High scores are stored outside the repository. On macOS the default is:
~/Library/Application Support/dbird/high-score.json
$XDG_STATE_HOME takes precedence when it is set. A missing or malformed score file never prevents the game from starting.
Develop
After cloning the repository, run the complete local check suite with:
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
The leaderboard service has its own checks:
cd leaderboard
npm ci
npm test
npx wrangler d1 migrations apply DB --local
npx wrangler deploy --dry-run
The physics and seeded pipe generation are independent from terminal rendering, so gameplay behavior can be tested without driving an interactive terminal.
License
dbird is released under the MIT License. The bundled sound effects are original works covered by the same terms; see assets/sounds/NOTICE.md.