QtBird

A pixel bird desktop pet for Windows that walks, climbs, and hops along the edges of your screen.

Ported from Pocket-Bird (a browser extension) to a standalone Python/PyQt6 desktop application.

Features

• Edge walking — the bird walks along the bottom, climbs up the sides (rotated 90°), walks upside-down across the top, and descends the other side
• Falling — 50% chance to lose grip mid-climb and tumble down with gravity physics
• 24 bird species — each with a unique color palette applied to the same base sprite, randomly selected on each launch
• Idle behavior — the bird occasionally stops to rest before resuming its patrol
• System tray menu — right-click the tray icon to switch species, randomize, or quit
• Transparent overlay — click-through window that stays on top of everything

Species

Includes 14 common and 10 uncommon species:

Common: American Goldfinch, American Robin, Barn Swallow, Black-capped Chickadee, Blue Jay, Carolina Wren, Dark-eyed Junco, Eastern Bluebird, European Robin, House Finch, Mistletoebird, Red Cardinal, Rock Pigeon, Scarlet Robin, Shima Enaga, Tufted Titmouse

Uncommon: Cuban Tody, Elegant Euphonia, Painted Bunting, Pink Robin, Red Avadavat, Red Warbler, Spangled Cotinga, Violet-backed Starling

Installation

pip install -r requirements.txt

Requirements

• Python 3.10+
• PyQt6
• Pillow

Usage

Double-click run.bat, or from the command line:

python -m src.qtbird

Right-click the bird icon in the system tray to access the menu.

Project Structure

QtBird/
  run.bat                    # Windows launcher
  requirements.txt           # pip dependencies
  src/
    qtbird/
      main.py                # Entry point and system tray setup
      overlay.py             # Transparent fullscreen PyQt6 overlay
      behavior.py            # Edge-walking state machine
      birb.py                # Sprite layer assembly and animation driver
      animation.py           # Layer -> Frame -> Anim compositing pipeline
      sprites.py             # Sprite sheet loading via Pillow
      palette.py             # Color palette constants and fuzzy matching
      species.py             # 24 bird species color definitions
      gen_icon.py            # Tray icon generator from sprite sheet
      assets/
        birb.png             # Master sprite sheet (10 layers, 32x32 each)
        hats.png             # 11 hat variants (not yet wired up)
        feather.png          # Feather sprite (not yet wired up)

How It Works

Animation System

The sprite system is a direct port of Pocket-Bird's layer compositing engine:

1. Palette — each pixel in the sprite sheet maps to a named color slot (face, wing, belly, etc.) via hex-color lookup with fuzzy matching
2. Layers — individual sprite rows are extracted from the sheet (base pose, head-down, wings, tufts, hearts)
3. Frames — layers are composited together, with tag-based variants (e.g. tufted species get the tuft layer)
4. Animations — frames are sequenced with per-frame durations (hop, fly, heart, still)
5. Species — a color scheme dict maps palette slots to hex colors, recoloring the same base sprite into 24 distinct birds

Edge Walker

The behavior state machine drives the bird around all four screen edges:

Walking Bottom -> Climbing Side -> Walking Top -> Climbing Down -> Walking Bottom
                        |                              |
                        v                              v
                     Falling                        Falling
                        |                              |
                        v                              v
                   Landing -> Idle/Walk Bottom

At the midpoint of each climb, the bird has a 50% chance to fall. Falls use simple gravity physics (velocity += 0.4, velocity *= 0.98).

Credits

• Bird sprites and species data from Pocket-Bird by Ryan Mercado