Ferris 🦀

A Pac-Man-inspired game built with Rust and the Bevy game engine. Guide the crab (Ferris) through mazes, eat pellets, avoid ghosts, and collect bonus lives!

🎮 Features

• Classic Pac-Man Gameplay: Navigate mazes, eat pellets, and avoid ghosts
• Multiple Levels: Progress through increasingly challenging levels
• Ghost AI: Intelligent ghost behaviors with scatter/chase modes and frightened states
• Power Pellets: Temporarily turn ghosts vulnerable for points
• Bonus Life System: Collect soda cans for extra lives
• Smooth Controls: Responsive movement with grid-based navigation
• Visual Effects: Neon aesthetics with particle effects and animations
• Sound Ready: Framework prepared for audio integration

🚀 Installation

Prerequisites

• Rust: Install Rust from rustup.rs
• Cargo: Comes with Rust installation

Clone and Build

# Clone the repository
git clone https://github.com/yourusername/ferris.git
cd ferris

# Build the game
cargo build --release

# Run the game
cargo run --release

System Requirements

• OS: Linux, Windows, macOS
• Graphics: OpenGL compatible GPU
• Memory: 256MB RAM minimum
• Storage: ~50MB for game assets

🎯 How to Play

Controls

• Arrow Keys or WASD: Move Ferris
• Space or Enter: Restart game (on game over screen)

Objective

• Eat all pellets in the maze to advance to the next level
• Avoid ghosts - they'll send you back to the start!
• Collect power pellets to turn ghosts blue and edible
• Grab soda cans for bonus lives
• Reach the highest level possible!

Game Mechanics

• Lives: Start with 1 life, collect bonus cans for more
• Levels: 4 levels total, then game completion
• Ghost Modes:
  • Scatter: Ghosts move to corners
  • Chase: Ghosts pursue Ferris
  • Frightened: Ghosts turn blue and flee (after eating power pellets)
• Scoring: Points for pellets, ghosts, and bonuses

🏗️ Project Structure

ferris/
├── src/
│   ├── main.rs              # Game entry point and Bevy app setup
│   ├── game_state.rs        # Core game logic, states, and UI
│   ├── f_config.rs          # Game constants and configuration
│   ├── f_enemies/           # Ghost AI and behavior
│   │   ├── ai.rs           # Ghost targeting algorithms
│   │   ├── components.rs   # Ghost entity components
│   │   ├── config.rs       # Ghost configuration
│   │   └── movement.rs     # Ghost movement logic
│   ├── f_layout/           # Maze and pellet systems
│   │   ├── f_map.rs        # Maze generation
│   │   ├── f_pellet.rs     # Pellet spawning and effects
│   │   ├── f_setup.rs      # Initial game setup
│   │   └── f_tile.rs       # Tile rendering
│   └── ferris/             # Player systems
│       ├── ferris.rs       # Player entity
│       └── movement.rs     # Player movement
├── assets/                  # Game assets
│   ├── ferris.png          # Player sprite
│   ├── life.png            # Life icon
│   ├── fonts/              # Game fonts
│   └── [other assets]      # Additional graphics
├── Cargo.toml               # Rust dependencies
└── README.md               # This file

🛠️ Development

Building for Development

# Debug build
cargo build

# Run in debug mode
cargo run

Testing

cargo test

Code Quality

# Check code
cargo check

# Format code
cargo fmt

# Lint code
cargo clippy

🎨 Assets

The game uses the following assets:

• ferris.png: Player character sprite
• life.png: Life/bonus can icon
• FiraSans-Bold.ttf: UI font
• Custom maze graphics and effects

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Areas for Contribution

• Audio Integration: Add sound effects and background music
• New Levels: Design additional maze layouts
• Power-ups: Implement new game mechanics
• UI Improvements: Enhance menus and HUD
• Bug Fixes: Help squash those pesky ghost circling bugs
• Performance: Optimize rendering and AI

📝 Known Issues

• Ghost circling behavior above the gate (especially when multiple ghosts are close)
• Audio system not yet implemented

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the classic Pac-Man game
• Built with the amazing Bevy game engine
• Rust community for the fantastic ecosystem
• Original Pac-Man developers for the timeless gameplay

🎉 Have Fun!

Enjoy playing Ferris! If you find any bugs or have suggestions, please open an issue or submit a pull request. Happy gaming! 🦀