# BlackRoad Pixel City 🎮⚡

**Now with Full Pokemon RPG Mechanics!**

A vibrant pixel-art Pokemon-themed RPG where you explore, battle, and catch Pokemon! Built with Python and Pygame.

![Version](https://img.shields.io/badge/version-2.1.0-blue)
![Python](https://img.shields.io/badge/python-3.8+-green)
![Pygame](https://img.shields.io/badge/pygame-2.0+-orange)
![License](https://img.shields.io/badge/license-MIT-brightgreen)

## ✨ NEW in v2.1 - Pokemon Game Features!

- 🎮 **Player Control** - Walk around as a Pokemon trainer
- 🌿 **Tall Grass Encounters** - Find wild Pokemon in grass
- ⚔️ **Battle System** - Fight and catch Pokemon
- 📖 **Pokedex** - Track seen and caught Pokemon
- 👥 **Pokemon Team** - Build your team of 6
- 💬 **Dialog System** - Pokemon-style conversations
- 🏥 **Interactive Buildings** - Visit Pokemon Center & shops
- 🎭 **NPC Interactions** - Talk to trainers and citizens

## 🚀 Quick Start

```bash
cd blackroad-pixel-city
./run.sh
```

## 🎮 Controls

| Key | Action |
|-----|--------|
| **WASD / Arrow Keys** | Move player |
| **SPACE / ENTER** | Interact / Advance dialog |
| **P** | View Pokedex |
| **T** | View team |
| **F** | Toggle FPS |
| **ESC** | Exit |

## 🎯 How to Play

1. **Move** around the city with WASD or arrow keys
2. **Walk through tall grass** to encounter wild Pokemon
3. **Battle** - Choose FIGHT to catch or RUN to escape
4. **Catch Pokemon** to fill your Pokedex
5. **Talk to NPCs** by pressing SPACE near them
6. **Visit Pokemon Center** to heal your team
7. **Explore** and catch 'em all!

## ✨ Full Feature List

### City Features
- 7 buildings (houses, Pokemon Center, Poke Mart)
- 4 tall grass patches for encounters
- 12 swaying trees
- Animated water pond
- Roads with crosswalks
- Wild Pokemon roaming

### Pokemon Features
- 6 Pokemon species (Pikachu, Bulbasaur, Charmander, Squirtle, Rattata, Pidgey)
- Pokedex tracking system
- Team management (up to 6 Pokemon)
- Wild encounters with variable rates
- Battle UI with menu
- Catch mechanics

### NPCs & Interactions
- Trainers ready to battle
- Citizens with helpful tips
- Pokemon Center healing
- Poke Mart shopping
- Dialog system

## 📁 Project Structure

```
blackroad-pixel-city/
├── src/
│   ├── pixel_city.py          # Main game with RPG mechanics
│   ├── entities/
│   │   ├── player.py          # Player character
│   │   ├── grass.py           # Tall grass & encounters
│   │   ├── ui.py              # Dialog & battle UI
│   │   ├── pokemon.py         # Pokemon sprites
│   │   ├── npc.py            # NPCs
│   │   ├── building.py       # Buildings
│   │   └── tree.py           # Trees
│   └── utils/
│       ├── colors.py         # Color palette
│       └── config.py         # Settings
├── docs/                      # Documentation
└── README.md                 # This file
```

## 🎯 Roadmap

- [x] Player movement
- [x] Wild encounters
- [x] Battle system
- [x] Pokedex tracking
- [x] Dialog system
- [ ] Move selection in battles
- [ ] HP and leveling system
- [ ] Pokemon evolution
- [ ] Trainer battles
- [ ] Inventory/Bag system
- [ ] More Pokemon species
- [ ] Gyms and badges
- [ ] Save/Load system
- [ ] Multiple maps

## 📝 Documentation

- [POKEMON_FEATURES.md](POKEMON_FEATURES.md) - Complete Pokemon mechanics guide
- [DEVELOPMENT.md](docs/DEVELOPMENT.md) - Developer guide
- [FEATURES.md](docs/FEATURES.md) - All features
- [QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) - Quick reference

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📝 License

MIT License - see [LICENSE](LICENSE) file.

## 🎨 Credits

- Inspired by Pokemon Red/Blue/Yellow
- Built with ❤️ using Python and Pygame
- Part of the BlackRoad OS ecosystem

## 🔗 Links

- [BlackRoad OS](https://blackroad.io)
- [Report Issues](https://github.com/blackroad-os/blackroad-pixel-city/issues)

---

**Start your Pokemon adventure today!** ⚡🎮✨

Made with 🎮 by BlackRoad OS