The Flappy Bird loop, rebuilt properly — six modes, five power-ups, weather, a day/night cycle and a daily challenge that is the same for everyone who plays it. Plus a full Node.js backend for leaderboards that you never have to run.
Browser preview only. This compact demo captures the core flight loop; clone the project to play the complete iOS game.
Click, tap or press space · R restarts
Everything below runs on the device with no account, no network and no setup. The backend adds a social layer on top — it never gates the game.
Classic is the original tuning. The rest pull it in different directions — and Zen exists purely so you can practise a tricky gap without the run ending.
Every gap holds a coin. Collect it and your combo grows; skip one and it resets. The multiplier caps at ×8, which is enough to make a greedy run genuinely worth attempting.
17 achievements worth 910 points, lifetime stats down to how you died, and eight bird skins bought with coins you actually earned. All of it unlocks with no account and no network.
Classic, Endless, Time Attack, Hardcore, Zen and a deterministic daily challenge.
Shield, slow-motion, coin magnet, double points and shrink. Re-collecting extends rather than replaces.
A coin streak multiplies rewards up to ×8 and feeds a shop of eight bird skins.
Wind, rain and fog from the run seed; a world that cycles through night and dawn.
910 points, unlocked offline and reconciled later.
Square and triangle waves rendered to PCM at launch. No audio assets ship at all.
Reduce flashing, high contrast, VoiceOver labels and system Reduce Motion support.
Nothing here is hidden in a spreadsheet — the tuning lives in one
GameConfig file and is documented alongside the reasoning.
| Mode | Ramps | Power-ups | Lethal | Ranked | Start gap |
|---|---|---|---|---|---|
| 🐦 Classic | no | yes | yes | yes | 170 pt |
| ♾️ Endless | yes | yes | yes | yes | 170 pt |
| ⏱️ Time Attack | yes | yes | yes | yes | 180 pt |
| 💀 Hardcore | yes | no | yes | yes | 132 pt |
| 🧘 Zen | no | yes | no | no | 200 pt |
| 📅 Daily | yes | no | yes | yes | from seed |
| Power-up | Duration | Effect |
|---|---|---|
| 🛡 Shield | until used | Absorbs one lethal hit and bounces you clear. Two can be banked. |
| ⏳ Slow-Mo | 5 s | The whole world scrolls at 55 %. |
| 🧲 Magnet | 8 s | Pulls coins within 170 pt toward you. |
| ⭐️ Double | 10 s | Two points per pipe. |
| 🔻 Shrink | 8 s | 65 % size — hitbox included. |
| Pipes passed | Gap | Spawn every | Scroll | Pitch |
|---|---|---|---|---|
0 | 170 pt | 2.20 s | 0.0100 s/pt | 220 pt |
10 | 145 pt | 1.65 s | 0.0078 s/pt | 212 pt |
25 | 128 pt | 1.30 s | 0.0064 s/pt | 203 pt |
40+ | 126 pt | 1.25 s | 0.0062 s/pt | 202 pt |
118 pt and the reaction window never below
1.25 s — a long run stays hard but never becomes
impossible, and tests assert both across every mode. Past 25 pipes some
pairs start drifting vertically, with an amplitude that always fits
inside the gap.
| Weather | Chance | Effect |
|---|---|---|
| ☀️ Clear | 62 % | — |
| 🌬 Windy | 16 % | Lateral gusts that reverse every 2.4–4.8 s. |
| 🌧 Rain | 13 % | A constant downdraft, plus particles. |
| 🌫 Fog | 9 % | A translucent overlay. |
The app takes launch arguments to open any screen directly, so
make media regenerates all of this without anyone tapping
a simulator.
img/screens/gameplay.png — captured from the simulator
# Boots a simulator, installs the app and opens # every screen in turn. make media # Under the hood — the app cooperates: xcrun simctl launch booted com.hoangsonww.flappybird \ -screen shop -seed-demo xcrun simctl launch booted com.hoangsonww.flappybird \ -demo -mode hardcore
A complete Node.js + TypeScript API with accounts, ranked boards, achievement sync and a daily challenge. One command starts it — the game finds it on its own, and shrugs when it is not there.
Info.plist, then localhost:4000.protocol: "flappy-bird/1".:4000 would produce confusing
failures three screens later instead of one clear message.
422.# Postgres + API + migrations make up # 12 demo players so the board is not empty make seed make health {"status":"ok","driver":"postgres"}
cd backend npm install npm run dev # DB_DRIVER defaults to `memory`, so that # really is the whole setup. Same API, # same tests, no database.
curl -s localhost:4000/v1/meta/config { "service": "flappy-bird-backend", "protocol": "flappy-bird/1", "capabilities": ["scores.submit", …], "gameModes": ["classic", "endless", …] }
| Feature | Offline | With a backend |
|---|---|---|
| Play every mode | yes | yes |
| Scores, coins, skins | yes | yes |
| Achievements | yes | synced |
| Daily challenge | yes | ranked |
| Global leaderboards | no | yes |
| Friends board | no | yes |
| Cloud saves | no | yes |
Three choices shaped everything else. Each has an architecture decision record explaining the trade-off, including what it costs.
Requiring a server would make "install Docker" the first step of playing. Every online feature has an offline path, so the offline path never rots.
project.pbxproj is derived from the file tree with deterministic IDs. Adding a file is touch + make xcodegen, and two branches never conflict.
Postgres and in-memory behind the same contracts, with every test run against both. It has already caught a type-inference bug and a ranking difference.
INTEGER and a BIGINT column — which
Postgres refuses to type-infer, so every score submission returned 500 —
and tied players receiving different ranks in SQL while sharing a rank in
memory. Both would otherwise have shipped as "works on my machine".
You need Xcode. That is the whole dependency list for playing.
git clone https://github.com/hoangsonww/Flappy-Bird-Game.git cd Flappy-Bird-Game open "Flappy Bird.xcodeproj" # then ⌘R
make doctor # what you have, what it unlocks make run # build + launch in a simulator make demo # attract mode — it plays itself make test # 123 Swift unit tests make test-ui # 25 Swift UI tests
make bootstrap # hooks, dependencies, .env make up # Postgres + API in Docker make seed # demo players and runs make ci # the full local pipeline
No package manager, no dependency resolution, no generated files to fetch. The project opens and builds.
Everything saves locally — scores, coins, skins, achievements, and the daily challenge.
make upPostgres and the API start in Docker. Relaunch the game and it signs itself in as a guest.
Twenty-four guides and three decision records covering architecture, the API, the schema, CI and the security model.
Twenty-four guides with sixty-eight Mermaid diagrams, plus the decision records above.
Clone, run, add a file, open a pull request.
Every mode, power-up and number behind the feel.
How the two halves fit, with diagrams.
46 endpoints with request and response examples.
Schema, indexes and the ranking query, explained.
Tokens, fair play, and what is deliberately out of scope.
Scene graph, layer order, parallax and textures.
The flight model, collisions and the frame loop.
How a SpriteKit game reaches VoiceOver.
Discovery, sessions and the offline upload queue.
Logs, metrics, dashboards and what to watch.
No. Clone the repository, open it in Xcode and press ⌘R. Six modes, power-ups, weather, achievements and the daily challenge all work locally. The backend only adds accounts, leaderboards and cloud saves, and the game detects it automatically when it is running.
Xcode 16 or newer and an iOS 16+ simulator or device. The optional backend needs Docker, or Node.js 20+ and PostgreSQL 16 if you prefer to run it directly.
Yes, under the MIT licence. The game, the backend, the infrastructure and the documentation are all in the repository.
Its parameters are derived from a SHA-256 hash of the date, and the identical derivation runs in both Swift and TypeScript. A contract test pins four fixed dates against values produced by the server, so the two implementations cannot drift apart.
Yes. The landing page includes a complete playable demo written in JavaScript and Canvas, so you can try the loop in a browser before cloning anything.
That is genuinely the whole setup. The backend, the Docker stack and the CI are there when you want them — and invisible when you do not.