155 lines
3.6 KiB
Markdown
155 lines
3.6 KiB
Markdown
# Development Guide
|
|
|
|
## Architecture
|
|
|
|
BlackRoad Pixel City follows a modular, object-oriented design:
|
|
|
|
```
|
|
src/
|
|
├── pixel_city.py # Main game loop and orchestration
|
|
├── entities/ # Game entities (sprites/objects)
|
|
│ ├── building.py # Building structures
|
|
│ ├── tree.py # Trees and vegetation
|
|
│ ├── npc.py # Non-player characters
|
|
│ └── pokemon.py # Pokemon sprites
|
|
└── utils/ # Utilities and configuration
|
|
├── colors.py # Color palette definitions
|
|
└── config.py # Game settings
|
|
```
|
|
|
|
## Adding New Features
|
|
|
|
### Adding a New Pokemon Species
|
|
|
|
1. Open `src/entities/pokemon.py`
|
|
2. Add color constants to `src/utils/colors.py`:
|
|
```python
|
|
EEVEE_BROWN = (205, 133, 63)
|
|
```
|
|
3. Create a new drawing method in the `Pokemon` class:
|
|
```python
|
|
def _draw_eevee(self, surface, hop_offset):
|
|
# Your drawing code here
|
|
pass
|
|
```
|
|
4. Add to the species check in `draw()` method
|
|
5. Spawn in `src/pixel_city.py`:
|
|
```python
|
|
Pokemon(x, y, "eevee")
|
|
```
|
|
|
|
### Adding New Building Types
|
|
|
|
1. Open `src/entities/building.py`
|
|
2. Add a new building type method:
|
|
```python
|
|
def _draw_gym_details(self, surface):
|
|
# Draw gym-specific features
|
|
pass
|
|
```
|
|
3. Add case to the `draw()` method
|
|
4. Instantiate in `pixel_city.py`:
|
|
```python
|
|
Building(x, y, width, height, color, "gym")
|
|
```
|
|
|
|
### Customizing Colors
|
|
|
|
Edit `src/utils/colors.py` to change the color scheme:
|
|
|
|
```python
|
|
GRASS_GREEN = (34, 139, 34) # Change to your preference
|
|
SKY_BLUE = (135, 206, 250)
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All game settings are in `src/utils/config.py`:
|
|
|
|
- `FPS`: Frame rate (default: 60)
|
|
- `SCREEN_WIDTH/HEIGHT`: Window dimensions
|
|
- `MAX_NPCS/MAX_POKEMON`: Entity limits
|
|
- `NPC_SPEED/POKEMON_SPEED`: Movement speeds
|
|
- `ENABLE_SHADOWS`: Toggle shadow rendering
|
|
- `SHOW_FPS`: Display FPS counter
|
|
|
|
## Testing
|
|
|
|
### Manual Testing
|
|
```bash
|
|
python src/pixel_city.py
|
|
```
|
|
|
|
### Performance Testing
|
|
Press `F` during gameplay to toggle FPS counter.
|
|
|
|
### Adding Entities
|
|
Press `SPACE` to spawn random Pokemon while running.
|
|
|
|
## Code Style
|
|
|
|
- Follow PEP 8 guidelines
|
|
- Use descriptive variable names
|
|
- Document classes and complex methods
|
|
- Keep methods focused and small
|
|
- Use type hints where helpful
|
|
|
|
## Common Tasks
|
|
|
|
### Adjusting Animation Speed
|
|
```python
|
|
# In config.py
|
|
POKEMON_HOP_SPEED = 0.3 # Lower = slower
|
|
WATER_ANIMATION_SPEED = 0.1
|
|
```
|
|
|
|
### Changing Movement Patterns
|
|
```python
|
|
# In npc.py or pokemon.py, adjust:
|
|
self.move_delay = random.randint(30, 90) # Frames between moves
|
|
```
|
|
|
|
### Adding Weather Effects
|
|
Create a new module `src/effects/weather.py`:
|
|
```python
|
|
class Rain:
|
|
def __init__(self):
|
|
self.drops = []
|
|
|
|
def update(self):
|
|
# Add raindrop logic
|
|
pass
|
|
|
|
def draw(self, surface):
|
|
# Draw raindrops
|
|
pass
|
|
```
|
|
|
|
## Debugging
|
|
|
|
- Enable FPS counter with `F` key
|
|
- Check console for Python errors
|
|
- Use print statements in update loops (sparingly)
|
|
- Verify pygame version: `python -c "import pygame; print(pygame.version.ver)"`
|
|
|
|
## Performance Tips
|
|
|
|
- Limit the number of entities (see MAX_* in config.py)
|
|
- Use dirty rect updating for large scenes
|
|
- Profile with cProfile if needed
|
|
- Reduce shadow rendering if slow (ENABLE_SHADOWS = False)
|
|
|
|
## Contributing
|
|
|
|
1. Create a feature branch
|
|
2. Make your changes
|
|
3. Test thoroughly
|
|
4. Update documentation
|
|
5. Submit PR with clear description
|
|
|
|
## Resources
|
|
|
|
- [Pygame Documentation](https://www.pygame.org/docs/)
|
|
- [Python Tutorial](https://docs.python.org/3/tutorial/)
|
|
- [Pixel Art Tutorials](https://www.pixilart.com/tutorials)
|