Feature/random gen dragons

QUICK_REFERENCE.md

@@ -0,0 +1,267 @@
+# Dragon Gene System - Quick Reference
+
+## For Players
+
+### What Are Gene-Based Dragons?
+Gene-based dragons are unique, procedurally-generated dragons. Each one has:
+- Unique combination of 5 body parts (wings, tail, body, horns, head)
+- Unique color tint
+- Unique stats based on genetics
+- A unique "seed" that can recreate the exact same dragon
+
+### How to Get One
+1. Buy an egg from the shop
+2. Go to Eggs screen and click until it hatches
+3. Name your dragon
+4. You now have a unique gene-based dragon!
+
+### Growth Stages
+- **Egg**: Looks like an egg 🥚
+- **Hatched**: Shows your unique dragon design immediately 🐉
+- The dragon still grows internally (gets stronger) but visually shows its full design once hatched
+
+---
+
+## For Developers
+
+### Create a Gene-Based Dragon
+
+```python
+from src.dragon import Dragon
+
+# Random dragon
+dragon = Dragon.create_gene_based("Sparkle")
+
+# Specific dragon from seed
+dragon = Dragon.create_gene_based("Blaze", seed="fire_dragon_123")
+
+# Get the seed
+print(dragon.genotype_seed)  # Share this to recreate dragon!
+```
+
+### Check Dragon Type
+
+```python
+if dragon.is_gene_based():
+    print(f"Gene dragon with seed: {dragon.genotype_seed}")
+    print(f"Color: {dragon.genotype.color}")
+    print(f"Genes: {dragon.genotype.genes}")
+else:
+    print(f"Legacy dragon: {dragon.dragon_type}")
+```
+
+### Render a Dragon
+
+```python
+from src.sprite_manager import SpriteManager
+
+sprite_manager = SpriteManager()
+
+# Automatic - works for both gene and legacy dragons
+sprite = sprite_manager.get_dragon_sprite(dragon)
+
+# With enchantments
+sprite = sprite_manager.get_dragon_with_enchantments(dragon=dragon)
+```
+
+### Access Genotype Info
+
+```python
+if dragon.genotype:
+    print(dragon.genotype.get_description())
+    # Shows: seed, color, genes, stats
+
+    # Access individual properties
+    print(f"Speed: {dragon.genotype.stats.speed}")
+    print(f"Strength: {dragon.genotype.stats.strength}")
+    print(f"Wings variant: {dragon.genotype.genes['wings']}")
+```
+
+---
+
+## For Artists
+
+### Add New Gene Variants
+
+1. Create PNG file (64x64 recommended, RGBA format)
+2. Name it: `{part} {number}.png`
+3. Put in: `assets/sprites/dragon-genes/`
+4. Restart game - automatically detected!
+
+**Example:**
+```bash
+# Add 4th wing variant
+cp "assets/sprites/dragon-genes/wings 1.png" "assets/sprites/dragon-genes/wings 4.png"
+# Edit wings 4.png in your image editor
+# Save and restart game
+```
+
+### Add New Body Part
+
+1. Create PNG files: `scales 1.png`, `scales 2.png`, etc.
+2. Put in `assets/sprites/dragon-genes/`
+3. Edit `src/dragon_gene_system.py`:
+   ```python
+   RENDER_ORDER = ['wings', 'tail', 'body', 'scales', 'horn', 'head']
+   ```
+4. (Optional) Update `_generate_stats()` to make scales affect stats
+5. Restart game
+
+### File Requirements
+- Format: PNG with transparency (RGBA)
+- Size: Any size (64x64 recommended for consistency)
+- Naming: Must follow `{part} {number}.png` format with space
+- Color: Can be any color (will be tinted in-game)
+
+---
+
+## Testing
+
+### Run Tests
+
+```bash
+# Comprehensive test suite
+python test_gene_system_simple.py
+
+# Interactive visualizer (press ←/→ to switch dragons)
+python test_gene_dragons.py
+
+# Stage progression test (press SPACE to cycle stages)
+python test_dragon_stages.py
+```
+
+### Test Specific Seed
+
+```python
+# Always produces same dragon
+dragon = Dragon.create_gene_based("Test", seed="test_seed_123")
+```
+
+---
+
+## Common Tasks
+
+### Get Dragon Info
+```python
+print(dragon)  # "Sparkle (Gene-based elder)"
+print(dragon.genotype_seed)  # "645d50b93ea471bee714c"
+print(dragon.speed, dragon.strength, dragon.rarity)  # Game stats
+```
+
+### Save/Load Dragons
+```python
+# Save
+data = dragon.to_dict()
+# data includes genotype and seed automatically
+
+# Load
+dragon = Dragon.from_dict(data)
+# Genotype restored, appearance identical
+```
+
+### Initialize Gene System
+```python
+from src.dragon_gene_system import initialize_gene_system
+
+# At game startup
+initialize_gene_system()
+# Loads all gene sprites from assets/sprites/dragon-genes/
+```
+
+### Manual Genotype Creation
+```python
+from src.dragon_gene_system import get_gene_system
+
+system = get_gene_system()
+genotype = system.generate_from_seed("custom_seed")
+
+# Access genotype properties
+print(genotype.color)  # (199, 122, 145)
+print(genotype.genes)  # {'wings': 2, 'tail': 1, ...}
+print(genotype.stats)  # DragonStats(speed=65.8, ...)
+```
+
+---
+
+## File Locations
+
+```
+DragonRider/
+├── src/
+│   ├── dragon_gene_system.py      # Core gene system
+│   ├── dragon.py                  # Dragon class (updated)
+│   ├── sprite_manager.py          # Rendering (updated)
+│   └── game_state.py              # Hatching (updated)
+├── assets/
+│   └── sprites/
+│       └── dragon-genes/          # ← PUT GENE PNG FILES HERE
+│           ├── wings 1.png
+│           ├── tail 1.png
+│           └── ...
+├── docs/
+│   ├── DRAGON_GENES.md            # Full documentation
+│   └── GENE_SYSTEM_ARCHITECTURE.md # Technical details
+└── test_gene_system_simple.py     # Test suite
+```
+
+---
+
+## Troubleshooting
+
+### Gene System Won't Load
+```
+⚠ Failed to load dragon gene system
+```
+**Fix:** Check `assets/sprites/dragon-genes/` exists and contains PNG files
+
+### Dragons Look Wrong
+**Fix:** Verify PNG files are RGBA format with transparency
+
+### Same Seed = Different Dragons
+**Fix:** Don't modify gene files after creating dragons
+
+### Egg Shows as Dragon
+**Fix:** Already fixed! Eggs now show as egg sprite.
+
+---
+
+## Statistics
+
+- **Total Gene Parts**: 5 (wings, tail, body, horn, head)
+- **Variants Per Part**: 3 (customizable)
+- **Total Base Combinations**: 243 (3^5)
+- **With Color Variations**: 4,076,863,488
+- **Generation Speed**: < 1ms per dragon
+- **Deterministic**: Yes (same seed = same dragon)
+
+---
+
+## Quick Command Reference
+
+```bash
+# Test the system
+python test_gene_system_simple.py
+
+# Visualize dragons
+python test_gene_dragons.py
+
+# Run the game
+python run_game.py
+
+# Add new gene variant (example)
+cp "assets/sprites/dragon-genes/wings 1.png" \
+   "assets/sprites/dragon-genes/wings 4.png"
+```
+
+---
+
+## Need More Info?
+
+- **Full Docs**: `docs/DRAGON_GENES.md`
+- **Architecture**: `docs/GENE_SYSTEM_ARCHITECTURE.md`
+- **Testing Guide**: `TESTING_GENE_SYSTEM.md`
+- **Implementation Summary**: `DRAGON_GENE_SYSTEM_SUMMARY.md`
+
+---
+
+**TL;DR**: Gene-based dragons are unique, seed-based, procedurally-generated dragons with modular body parts and stats. Eggs show as eggs, hatched dragons show full design. Add genes by adding PNG files. It's magic! ✨🐉