🎮 Pac-Man AI Game (Amazon Q edition)

Retro AI-Powered Arcade Game Built with Python + PyGame + Amazon Q Developer CLI

Welcome to a neon-soaked, ghost-dodging, dot-chomping revival of the classic Pac-Man — fully rebuilt from scratch using AI-assisted development with the Amazon Q Developer CLI.

🔧 Built by Evelyn Hale | 80s Baby • Cloud Engineer in Progress • Challenge Participant🏁 Part of the Amazon Q Build Games Challenge – June 2025

✨ Features

🎨 Visual Effects

Neon Retro Aesthetic: Glowing sprites with authentic 80s arcade vibes
Directional Pac-Man: Face turns based on movement direction
Dynamic Lighting: Particle effects and neon glow throughout
Retro UI: Glowing text and authentic arcade-style interface

👻 Advanced AI System

5 Unique Ghost Behaviors:
- 🔴 Red Ghost: Aggressive direct chaser
- 🟠 Orange Ghost: Strategic patrol wanderer
- 🔵 Cyan Ghost: Predictive ambusher
- 🟣 Magenta Ghost: Secondary chaser
- 🟢 Green Ghost: Advanced ambusher
A Pathfinding*: Intelligent navigation around obstacles
Dynamic Difficulty: Faster, smarter ghosts for increased challenge

🎵 Retro Audio System

Chiptune Background Music: Authentic 8-bit style compositions
Dynamic Sound Effects: Blip, power-up, death, and victory sounds
Volume Controls: Separate controls for music and SFX
Generated Audio: Real-time waveform synthesis for authentic retro sound

🎯 Gameplay Features

3-Lives System: Classic arcade-style life management
Power Pellets: Temporary ghost vulnerability
Speed Boosts: Cyan star power-ups for enhanced movement
Score System: Points for dots, pellets, and ghost consumption
Debug Mode: Visualize AI pathfinding (Press 'P')

🚀 Installation

Prerequisites

Python 3.9 or higher
pip package manager

Setup

Clone the repository:

git clone https://github.com/yourusername/neon-pacman-ai.git
cd neon-pacman-ai

Install dependencies:
```
pip install pygame numpy
```
Run the game:
```
python main.py
```

🎮 Controls

Basic Controls

Arrow Keys: Move Pac-Man
SPACE: Start game / Restart when game over
ESC: Return to title screen

Audio Controls

M: Toggle sound on/off
+/-: Adjust master volume
1/2: Adjust music volume (down/up)
3/4: Adjust sound effects volume (down/up)

Debug Controls

P: Toggle pathfinding visualization

🏗️ Architecture

Core Components

`main.py`

Game loop and state management
Player input handling
Collision detection
UI rendering

`sprites.py`

Neon sprite generation
Directional Pac-Man sprites
Color-coded ghost sprites
Visual effects rendering

`retro_audio.py`

Chiptune music synthesis
Sound effect generation
Volume management
Audio mixing

`pathfinding.py`

A* pathfinding algorithm
Ghost navigation logic
Obstacle avoidance

`retro_effects.py`

Neon glow effects
Particle systems
Visual enhancement utilities

🤖 AI Ghost Behaviors

Chaser Ghosts (Red & Magenta)

def update_chaser_ai(self, maze, pacman):
    if self.frightened:
        self.flee_from_target(maze, (pacman.x, pacman.y))
    else:
        self.target_pos = (pacman.x, pacman.y)
        self.current_path = self.pathfinder.find_path(
            self.x, self.y, pacman.x, pacman.y, maze
        )

Ambusher Ghosts (Cyan & Green)

def calculate_ambush_position(self, maze, pacman):
    px, py = pacman.x, pacman.y
    dx, dy = pacman.direction
    
    # Try to ambush several steps ahead
    for distance in range(self.ambush_distance, 0, -1):
        ambush_x = px + dx * distance
        ambush_y = py + dy * distance
        # Validate position and return

Wanderer Ghost (Orange)

def update_wanderer_ai(self, maze, pacman):
    # Patrol between predefined points
    target_patrol = self.patrol_points[self.current_patrol_target]
    patrol_distance = abs(self.x - target_patrol[0]) + abs(self.y - target_patrol[1])
    
    if patrol_distance <= 2:
        # Move to next patrol point
        self.current_patrol_target = (self.current_patrol_target + 1) % len(self.patrol_points)

🎨 Visual Design

Neon Color Palette

NEON_COLORS = {
    'yellow': (255, 255, 0),    # Pac-Man
    'cyan': (0, 255, 255),      # Power effects
    'magenta': (255, 0, 255),   # UI elements
    'green': (0, 255, 0),       # Speed boosts
    'blue': (0, 100, 255),      # Frightened ghosts
    'white': (255, 255, 255)    # Highlights
}

Sprite Generation

Procedural Creation: All sprites generated programmatically
Glow Effects: Multi-layer alpha blending for neon appearance
Dynamic Sizing: Scalable sprite system
Color Variations: Ghost sprites with unique color schemes

🎵 Audio System

Music Synthesis

Chiptune Generation: Square, triangle, and sawtooth waves
ADSR Envelopes: Attack, Decay, Sustain, Release shaping
Multi-track Composition: Bass, melody, harmony, and percussion layers
Looping System: Seamless background music loops

Sound Effects

Dot Collection: Subtle blip sounds with harmonics
Power Pellet: Ascending arpeggio for triumph
Death Sound: Dramatic descending sweep with vibrato
Ghost Eaten: Rising frequency sweep
Speed Boost: Energetic sawtooth arpeggios

🔧 Configuration

Game Settings

# Grid and display settings
GRID_WIDTH = 25
GRID_HEIGHT = 19
GRID_SIZE = 30
WINDOW_WIDTH = GRID_WIDTH * GRID_SIZE
WINDOW_HEIGHT = GRID_HEIGHT * GRID_SIZE + 200

# Gameplay settings
POWER_DURATION = 100  # Frames
SPEED_BOOST_DURATION = 80  # Frames

Ghost AI Settings

# Ghost behavior parameters
move_delay = 6  # Frames between moves (lower = faster)
ambush_distance = 4  # Steps ahead for ambush calculation
path_update_delay = 15  # Frames between pathfinding updates

🐛 Debugging

Debug Mode Features

Pathfinding Visualization: See ghost AI decision-making
Target Indicators: Glowing circles show ghost destinations
Color-coded Paths: Different colors for each ghost's route
Performance Metrics: Frame rate and update timing

Enable Debug Mode

# Press 'P' during gameplay to toggle
self.show_path_debug = not self.show_path_debug

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/yourusername/neon-pacman-ai.git
cd neon-pacman-ai

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install pygame numpy

📝 License

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

🙏 Acknowledgments

Classic Pac-Man: Inspired by the original Namco arcade game
Pygame Community: For the excellent game development framework
Retro Gaming: Celebrating the golden age of arcade games
AI Pathfinding: A* algorithm implementation for intelligent ghost behavior

📊 Game Statistics

Lines of Code: ~1,500+
Ghost AI Behaviors: 5 unique types
Sound Effects: 7 procedurally generated
Music Tracks: 2 chiptune compositions
Sprite Variations: 20+ directional and state variants

🎯 Future Enhancements

Multiplayer Support: Local co-op gameplay
Level Editor: Create custom mazes
High Score System: Persistent leaderboards
Additional Power-ups: New gameplay mechanics
Mobile Support: Touch controls for mobile devices
Shader Effects: Advanced visual effects
AI Difficulty Levels: Adjustable ghost intelligence

**Made with ❤️ and lots of ☕ by Evelyn Hale **

Experience the nostalgia of classic arcade gaming with modern AI and stunning neon visuals!

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.gitignore		.gitignore
GITHUB_SETUP.md		GITHUB_SETUP.md
LICENSE		LICENSE
README.md		README.md
main.py		main.py
pathfinding.py		pathfinding.py
requirements.txt		requirements.txt
retro_audio.py		retro_audio.py
retro_effects.py		retro_effects.py
sound_manager.py		sound_manager.py
sprites.py		sprites.py

License

EHale24/pacman-amazon-q-edition

Folders and files

Latest commit

History

Repository files navigation