Clumsy Bird

Flappy-style endless flyer with audio, score and restart.

▶ Run in browser

Upstream: https://github.com/ellisonleao/clumsy-bird

Licence: this port's own code is offered under GPL-3.0-or-later, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-0

Clumsy Bird (SimVX port)

SimVX port of ellisonleao/clumsy-bird, a MelonJS Flappy Bird clone: flap through pipe gaps, score per pipe passed, crash restarts.

Licensing: GPL-3.0-or-later (matching upstream code); all art is CC0 (Kenney Tappy Plane) or procedural, all audio synthesised. See ATTRIBUTION.md.

Run

uv run python examples/ports/clumsy_bird/main.py            # interactive
uv run python examples/ports/clumsy_bird/main.py --test     # headless capture
uv run simvx export web examples/ports/clumsy_bird/main.py -o /tmp/clumsy_bird.html

Controls

• Space / Left click: flap (also starts a run, and restarts after a crash)

• Esc: quit

What it shows

• One action, two devices: the root scene declares input_actions = {"flap": [Key.SPACE, MouseButton.LEFT], "quit": [Key.ESCAPE]}, so keyboard, mouse and touch share one code path. The scene tree registers the table at mount and again after every scene swap.

• Event-driven input: the flap is handled by @on_input(action="flap") rather than polled from on_fixed_update, so no tap is lost on a display that outruns the fixed tick rate.

• Coroutines: pipe spawning is a generator driven by start_coroutine and wait, not a hand-rolled timer field.

• Signals: the bird emits flapped and crashed, each pipe pair emits passed; the play scene connects them and keeps the score.

• AnimatedSprite2D: a three-frame flipbook drives the wing beat.

• Procedural audio: the wing, score, crash and looping theme are synthesised at load with AudioSynth, so the port ships no sound files.

• Anchored UI: the score readout, title card, bottom controls strip and game-over panel are Controls positioned with anchors and margins.

• Scene flow: the title screen and every restart are tree.change_scene swaps.

Source files

File	Summary	Lines
main.py	Clumsy Bird: Flappy-style endless flyer with audio, score and restart.	61
config.py	Shared constants and asset paths for Clumsy Bird.	45
nodes/__init__.py	Clumsy Bird scene nodes.	1
nodes/audio.py	Procedural audio: built on the engine’s AudioSynth API.	129
nodes/bird.py	Player bird: gravity, flap, rotation.	147
nodes/ground.py	Scrolling ground: two side-by-side ground sprites that loop, plus a	64
nodes/hud.py	Score HUD: anchored Label that displays the current score.	23
nodes/menu.py	MenuScene: the title screen shown before a run starts.	110
nodes/pipe.py	Pipe pair: top + bottom pipe sprites that scroll right to left and emit	88
nodes/play_scene.py	PlayScene: the active game: bird, pipes, ground, HUD, score, restart.	254

Source

#!/usr/bin/env python3
"""Clumsy Bird: Flappy-style endless flyer with audio, score and restart.

# /// simvx
# tags = ["port", "tier-0"]
# upstream = "https://github.com/ellisonleao/clumsy-bird"
# web = { width = 900, height = 600, responsive = false }
# ///

Run desktop:   uv run python examples/ports/clumsy_bird/main.py
Headless:      uv run python examples/ports/clumsy_bird/main.py --test
Web export:    uv run simvx export web examples/ports/clumsy_bird/main.py -o /tmp/clumsy_bird.html

Controls:
    Space / Click    Flap (also starts a run and restarts after a crash)
    Esc              Quit
"""

# /// script
# requires-python = ">=3.14"
# dependencies = ["simvx-core", "simvx-graphics", "numpy", "pillow"]
# ///

from __future__ import annotations

import sys
from pathlib import Path

_PORT_DIR = Path(__file__).resolve().parent
sys.path.insert(0, str(_PORT_DIR))

from config import HEIGHT, WIDTH  # noqa: E402
from nodes.menu import MenuScene  # noqa: E402
from nodes.play_scene import PlayScene  # noqa: E402

from simvx.graphics import App  # noqa: E402


def main():
    test_mode = "--test" in sys.argv
    app = App(width=WIDTH, height=HEIGHT, title="Clumsy Bird", visible=not test_mode)

    if test_mode:
        from simvx.graphics import save_png

        out = _PORT_DIR / "screenshots"
        out.mkdir(exist_ok=True)
        # A headless run gets no input, so boot straight into the play scene:
        # the captures then show the game rather than the title card.
        frames = app.run_headless(PlayScene(), frames=180, capture_frames=[60, 120, 179])
        for idx, n in enumerate([60, 120, 179]):
            save_png(frames[idx], out / f"frame_{n}.png")
        print(f"Wrote {len(frames)} screenshots to {out}")
        app.quit()
        return

    app.run(MenuScene())


if __name__ == "__main__":
    main()