Dragon Idle Game

A cross-platform dragon-raising idle game with minigames built in Python using Pygame.

Features

• Raise dragons from eggs to fully mature dragons
• 10 dragon types: 5 common types + 5 legendary variants!
• Multiple dragon types with sprite-based system
• Idle game mechanics: time-based growth, feeding, and petting
• Rename your dragons to personalize them
• Dragon stats system: Speed, Strength, and Rarity (0-100 scale)
• Legendary dragons with superior stats and 2x sell value
• Dragon Pen: View all dragons, their stats, and sell dragons for coins
• Stats influence minigames (strength affects jump height in Flappy Dragon)
• Equipment system: Collect and equip helmets, saddles, and armor on dragons
• 15 unique items across 5 rarity tiers (Common to Legendary)
• Flappy Bird-style minigame to earn new dragon eggs (with legendary drops!)
• Background music with shuffle playback and mute button
• Save/load functionality
• Cross-platform support (macOS, Windows, Linux)

Installation

Option 1: Nix (Recommended for Reproducible Builds) 🔄

For reproducible, consistent builds across all systems:

# Install Nix with flakes enabled
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# Install dependencies and run
make install
make dev

# Or build executable
make build

See docs/NIX_BUILD.md for comprehensive Nix documentation.

Option 2: Traditional Python Installation

1. Install Python 3.8 or higher

2. Install dependencies:

   With UV (Recommended - Much Faster! ⚡)

   # Install UV
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies
   uv pip install -r requirements.txt

   With pip (Traditional)

   pip install -r requirements.txt

   See UV_SETUP.md for more details on using UV.

Running the Game

python run_game.py

Building for Distribution

Using Nix (Recommended)

For reproducible builds with all dependencies included:

# Standard build
make build
# or
./build-nix.sh

# Clean build from scratch
make build-clean
# or
./build-nix.sh --clean

# Build and test
make build-test
# or
./build-nix.sh --test

See docs/NIX_BUILD.md for complete Nix build documentation.

Traditional Build

To create executable distributions using your system Python:

# Automatic build (detects UV or pip automatically)
python build.py
# or
./build.sh   # macOS/Linux
build.bat    # Windows

This creates platform-specific packages:

• Windows: DragonIdleGame-windows.zip
• macOS: DragonIdleGame-macos.zip
• Linux: DragonIdleGame-linux.tar.gz

See BUILD.md for detailed build instructions.

Running Tests

pytest tests/

Adding Custom Music

To add your own background music:

1. Place MP3, OGG, or WAV files in the assets/songs/ folder
2. The game will automatically detect and shuffle all music files
3. Use the mute button (🔊/🔇) in the navigation panel to toggle music on/off

Dragon Stats System

Each dragon has three stats that range from 0-100:

• Speed: Affects minigame performance and future features
• Strength: Influences jump height in Flappy Dragon (weaker dragons need more flaps)
• Rarity: Determines the dragon's sell value (configurable in constants.py)

Stats are randomly assigned when dragons hatch, making each dragon unique!

Configuring Dragon Sell Prices

You can adjust dragon sell prices in src/utils/constants.py:

• DRAGON_SELL_BASE: Price for 0 rarity dragons (default: 50 coins)
• DRAGON_SELL_MAX: Price for 100 rarity dragons (default: 400 coins)

Sell prices scale linearly based on rarity between these values.

Dragon Pen

Access the Dragon Pen from the navigation menu to:

• View all your dragons in one place
• See detailed stats for each dragon (Speed, Strength, Rarity)
• Sell dragons for coins based on their rarity
• Manage your dragon collection (Note: You cannot sell your last dragon!)

Equipment System

Customize your dragons with cosmetic equipment! Access the Equipment screen from the navigation menu to:

• Equip Items: Outfit your dragons with helmets, saddles, and armor
• Manage Inventory: Store collected items in your inventory
• Switch Dragons: Equip different items on each dragon
• Item Rarities:
  • Common (25 coins)
  • Uncommon (50 coins)
  • Rare (100 coins)
  • Epic (200 coins)
  • Legendary (500 coins)

Available Items

• Helmets: Iron Helmet, Steel Helmet, Golden Crown, Diamond Crown, Ancient Dragon Crown
• Saddles: Leather Saddle, Padded Saddle, Royal Saddle, Enchanted Saddle, Legendary Dragon Saddle
• Armor: Iron Armor, Steel Armor, Golden Armor, Diamond Armor, Ancient Dragon Scales

How to Use

1. Click "Equipment" in the navigation menu
2. Select a dragon using the arrow buttons
3. Click an equipment slot (Helmet, Saddle, or Armor)
4. Choose an item from your inventory to equip
5. Click an equipped item to unequip it back to your inventory

New players start with a generous equipment pack for testing and getting started:

• 2x Iron Helmet (Common)
• 2x Leather Saddle (Common)
• 2x Iron Armor (Common)
• 1x Steel Helmet (Uncommon)
• 1x Padded Saddle (Uncommon)
• 1x Steel Armor (Uncommon)
• 1x Golden Crown (Rare)

This gives you plenty of items to experiment with the equipment system right away!

Visual Equipment Display

Equipped items are now visually displayed on your dragons! Each item has a unique sprite that appears overlayed on the dragon:

• Helmets: Displayed on the dragon's head area
• Saddles: Shown on the dragon's back
• Armor: Covers the dragon's body with protective plating
• Rarity Colors: Items are color-coded by rarity (Gray=Common, Green=Uncommon, Blue=Rare, Purple=Epic, Gold=Legendary)

Equipment sprites are automatically generated and stored in assets/sprites/equipment/. You can replace these with custom artwork if desired!

Dragon Types

The game features 10 unique dragon types - 5 common types and 5 legendary variants!

Common Dragon Types

• 🔥 Fire Dragons (Red): Flame patterns, fierce and aggressive
• ❄️ Ice Dragons (Blue): Snowflake patterns, crystalline features
• 🌲 Forest Dragons (Green): Leaf decorations, natural look
• ⚡ Storm Dragons (Purple): Lightning bolt patterns, electric style
• 🌑 Shadow Dragons (Dark Gray): Mysterious swirls, ethereal appearance

Legendary Dragon Types (RARE!)

These powerful variants are extremely difficult to obtain but have much better stats:

• 🔥🔥 Inferno Dragons (Bright Orange): Upgraded Fire - Intense flame spirals, glowing appearance
• ❄️❄️ Glacier Dragons (Cyan): Upgraded Ice - Crystal formations, brilliant white glow
• 🌲🌲 Ancient Dragons (Emerald): Upgraded Forest - Ancient runes, primordial magic
• ⚡⚡ Thunder Dragons (Electric Purple): Upgraded Storm - Electric arcs, lightning aura
• 🌑🌑 Void Dragons (Deep Purple): Upgraded Shadow - Void energy, cosmic power

Legendary Dragon Features

• Superior Stats: 70-100 range for Speed/Strength (vs 10-100 for common)
• Higher Rarity: 80-100 rarity range (vs 0-100 for common)
• Double Value: Sell for 2x the coins of common dragons!
• Unique Visuals: Glow effects and enhanced sprite details
• Very Rare: Only 5% drop chance from eggs!

How to Obtain Legendary Dragons

1. Minigame Rewards: 5% chance when earning eggs from Flappy Dragon (50+ obstacles)
2. Shop Purchase: Buy legendary eggs for 1,000 coins (vs 100 for common)
3. Luck: Small chance from any shop egg purchase

Dragon Sprites

All dragon sprites are now pixel art generated for each dragon type and growth stage!

Growth Stages

Each dragon type progresses through 5 distinct visual stages:

1. Egg (48x48): Type-specific patterns and decorations
2. Hatchling (64x64): Cute baby dragon with big eyes and tiny wings
3. Juvenile (80x80): Growing dragon with developing features
4. Adult (96x96): Powerful mature dragon with large wings and horns
5. Elder (112x112): Massive ancient dragon with crown-like horns and majestic appearance

All 50 dragon sprites (10 types × 5 stages) are stored in assets/sprites/dragons/.

Legendary dragons feature:

• Unique egg patterns (flame spirals, crystals, runes, electric arcs, void energy)
• Glowing particles around the dragon
• More vibrant colors
• Enhanced details on elder forms

Sprite Pipeline

The game uses a two-stage sprite pipeline with pixelmapping:

1. Generate raw sprites (Python) → assets/sprites_raw/
2. Convert to pixelmapped (spritefusion) → assets/sprites/

Complete Pipeline (Recommended)

To regenerate all sprites with pixelmapping:

./generate_all_sprites.sh

This runs the full pipeline:

• Generates raw dragon and equipment sprites
• Builds spritefusion (Rust pixelmapping tool)
• Converts all sprites to pixelmapped format
• Outputs final game-ready sprites to assets/sprites/

Manual Generation

To generate raw sprites only (without conversion):

python -m src.dragon_sprite_generator  # → assets/sprites_raw/dragons/
python -m src.equipment_sprite_generator  # → assets/sprites_raw/equipment/

Then convert using:

./convert_sprites.sh  # Converts raw → final using spritefusion

One-Time Migration

To convert existing sprites to pixelmapped format:

./convert_existing_sprites.sh  # Backs up and converts current sprites

See SPRITE_PIPELINE.md for complete documentation.

Project Structure

• src/ - Core game code
  • dragon.py - Dragon class with stats and growth mechanics
  • game_state.py - Game state management
  • save_system.py - Save/load functionality
  • idle_game.py - Main idle game scene
  • dragon_pen.py - Dragon Pen scene for viewing and selling dragons
  • equipment_screen.py - Equipment management screen
  • item.py - Item system and database
  • music_manager.py - Background music system
  • minigames/ - Minigame implementations
• assets/ - Game assets
  • sprites/ - Dragon and UI sprites
  • songs/ - Background music files
• tests/ - Unit tests