🟡 Pac-Man Desktop

A modern, cross-platform recreation of the iconic arcade classic Pac-Man, engineered in C# (.NET 10) using Avalonia UI. Built with strict adherence to Clean Architecture, MVVM, and SOLID principles, this project demonstrates robust desktop software engineering, real-time 2D canvas rendering, and authentic arcade Ghost AI targeting mechanics.

---

📑 Table of Contents

• Features
  • Core Gameplay
  • Ghost AI Personalities
  • Audio & Visual Systems
• Architecture & Design Patterns
  • Layer Breakdown
  • Design Patterns Applied
• Project Structure
• Getting Started
  • Prerequisites
  • Building and Running
  • Custom Maze Configuration
• Controls & Keybindings
• License

---

✨ Features

🕹️ Core Gameplay

• Classic Arcade Dynamics: Smooth continuous grid movement with directional pre-buffering (NextDirection) for seamless turning at intersections.
• Side Tunnels & Wrap-Around: Seamless horizontal screen-wrap mechanics.
• Score & Scoring System: Real-time scoring for standard pellets (10 pts), power pellets (50 pts), bonus fruits (100–300 pts), and successive ghost captures (+200 pts).
• Life Management: 3 starting lives, respawn transitions, game over triggers, and victory conditions upon clearing the maze.
• Persistent High Scores: Top 5 scoreboard asynchronously saved to and loaded from scores.json.

👻 Authentic Ghost AI Personalities

Each of the four ghosts faithfully implements the original 1980 Namco arcade targeting logic using the Strategy Pattern:

Ghost	Character / Nickname	Targeting Behavior
Blinky	Shadow (Red)	Direct Chaser: Aggressively targets Pac-Man's exact tile coordinates.
Pinky	Speedy (Pink)	Ambusher: Predicts movement, targeting 4 tiles ahead of Pac-Man's current vector.
Inky	Bashful (Cyan)	Flanker / Complex Vector: Computes an offset vector between Blinky and 2 tiles ahead of Pac-Man, mirroring it for pincer attacks.
Clyde	Pokey (Orange)	Shy / Coward: Pursues Pac-Man when distance $\ge 8$ tiles; retreats to his home corner when within 8 tiles.

• Staggered Ghost House Release: Timed exit delays for Blinky (0s), Pinky (1.8s), Inky (4.8s), and Clyde (9s) with automatic base navigation.
• Frightened / Vulnerable Mode: Power pellets turn ghosts blue, reduce their speed by 50%, invert movement to pseudorandom navigation, and trigger warning flashing before returning to normal.
• Base Respawn: Eaten ghosts become eyes and navigate directly back to the ghost house to respawn.

🔊 Audio & Visual Systems

• Non-blocking Multiplatform Audio Engine: Background music, eating effects, frightened sirens, jumpscare sound, game-over, and victory tunes powered by native system audio runners (ffplay, pw-play, paplay, aplay, afplay, and PowerShell SoundPlayer).
• High-Performance 2D Canvas: 60 FPS rendering via Avalonia Canvas, supporting frame-by-frame mouth animations, dynamic sprite orientation, and flashing effects.
• Jumpscare Effect: Optional visual & auditory overlay triggered on ghost collision.

---

🏛️ Architecture & Design Patterns

The project follows Clean Architecture to maintain complete separation between domain entities, business logic, persistence mechanisms, and user interface components.

┌────────────────────────────────────────────────────────────────────────┐
│                        PRESENTATION LAYER                              │
│                    (Pacman.DesktopUI - MVVM)                           │
│   MainWindow.axaml  ◄───►  MainViewModel  ───►  PacmanBoardCanvas       │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ References
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        APPLICATION LAYER                               │
│                      (Pacman.Application)                              │
│   GameEngine (Facade)  ──►  GhostFactory  |  PlayerMovementHandler     │
│                        ──►  CollisionSystem | FrightenedModeManager    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ References
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          DOMAIN LAYER                                  │
│                          (Pacman.Core)                                 │
│   Board, Player, Ghost, Position, Direction, Enums, TileType           │
│   IGhostMovementStrategy & Strategies (Blinky, Pinky, Inky, Clyde)     │
└───────────────────────────────────▲────────────────────────────────────┘
                                    │ Implements domain abstractions
┌───────────────────────────────────┴────────────────────────────────────┐
│                      INFRASTRUCTURE LAYER                              │
│                    (Pacman.Infrastructure)                             │
│   JsonScoreRepository (JSON I/O)  |  SoundManager (Process Audio)      │
└────────────────────────────────────────────────────────────────────────┘

🧩 Layer Breakdown

1. Pacman.Core (Domain Layer)

   • Zero external dependencies (pure C#).
   • Houses domain entities (Player, Ghost, Board), immutable value objects (Position), state enumerations, and AI movement strategy interfaces.

2. Pacman.Application (Application / Use Cases)

   • Orchestrates the game loop via GameEngine (discrete tick cycle).
   • Manages subsystems: CollisionSystem, PlayerMovementHandler, FrightenedModeManager, and GhostFactory.

3. Pacman.Infrastructure (Infrastructure Layer)

   • Implements data persistence (JsonScoreRepository) using asynchronous System.Text.Json streaming.
   • Manages audio dispatching (SoundManager) across operating systems.

4. Pacman.DesktopUI (Presentation Layer)

   • Built on Avalonia UI 11/12 and CommunityToolkit.Mvvm.
   • Contains MainWindow.axaml, reactive MainViewModel, and custom graphics renderer PacmanBoardCanvas.

---

💡 Design Patterns Applied

Pattern	Implementation	Purpose
Strategy	IGhostMovementStrategy (Blinky, Pinky, Inky, Clyde)	Encapsulates unique pursuit algorithms interchangeability at runtime.
Factory Method	GhostFactory	Decouples ghost instantiation, strategy binding, and spawn positions.
Facade	GameEngine	Exposes a unified API (Tick(), Start(), Pause()) hiding subsystem complexity.
MVVM	MainViewModel + Avalonia Views	Enforces strict separation between UI presentation and business logic.
Dependency Inversion (DIP)	IScoreRepository, ISoundManager	Presentation and Application depend on abstractions rather than low-level details.

---

📁 Project Structure

pacman-desktop/
├── Pacman.slnx                     # Solution configuration
├── Assets/                         # Sprites, audio tracks, and maze definitions
│   ├── pacman-art/                 # Animated character and ghost sprites
│   ├── maze.txt                    # Default 28x31 classic arcade maze
│   ├── maze2.txt                   # Alternative custom maze layout
│   └── *.mp3                       # Sound effects & soundtrack
├── Pacman.Core/                    # Pure Domain Layer
│   ├── Board.cs                    # Grid representation & wrap-around arithmetic
│   ├── Position.cs                 # Readonly record struct with coordinate math
│   ├── Player.cs                   # Pac-Man state & score tracking
│   ├── Ghost.cs                    # Ghost entity & state definitions
│   └── GhostStrategies.cs          # Blinky, Pinky, Inky, Clyde AI algorithms
├── Pacman.Application/             # Application & Orchestration Layer
│   ├── GameEngine.cs               # Central game loop coordinator
│   ├── GhostFactory.cs             # Ghost creation & positioning factory
│   ├── PlayerMovementHandler.cs    # Buffer validation & grid movement
│   ├── CollisionSystem.cs          # Pac-Man / Ghost interaction resolutions
│   └── FrightenedModeManager.cs    # Timer-based vulnerability state machine
├── Pacman.Infrastructure/          # Persistence & Platform Services
│   ├── JsonScoreRepository.cs      # High score serialization (scores.json)
│   └── SoundManager.cs             # Native cross-platform audio player
└── Pacman.DesktopUI/               # Avalonia UI Presentation Layer
    ├── ViewModels/                 # MainViewModel (CommunityToolkit.Mvvm)
    ├── Views/                      # MainWindow.axaml & PacmanBoardCanvas
    └── appsettings.json            # Runtime maze selection & settings

---

🚀 Getting Started

Prerequisites

• .NET 10.0 SDK or later.
• OS: Linux (Ubuntu/Debian, Fedora, Arch, etc.), Windows 10/11, or macOS.

Building and Running

1. Clone the repository:

   git clone https://github.com/Patick-gu/Pacman.git
   cd Pacman

2. Restore dependencies:

   dotnet restore

3. Build the solution:

   dotnet build

4. Launch the game:

   dotnet run --project Pacman.DesktopUI

---

🗺️ Custom Maze Configuration

You can easily switch maps or supply your own custom maze text file by editing Pacman.DesktopUI/appsettings.json:

{
  "AppSettings": {
    "Title": "PACMAN",
    "MazePath": "Assets/maze.txt"
  }
}

Maze Legend Symbols:

• # : Wall
• * : Standard Pellet (Dot)
• O : Power Pellet
• P : Pac-Man Start Position
• - : Ghost House Gate
• : Empty Corridor / Wrap-Around Side Tunnel

---

🎮 Controls & Keybindings

Action	Primary Key	Alternative Key
Move Up	↑ (Up Arrow)	W
Move Down	↓ (Down Arrow)	S
Move Left	← (Left Arrow)	A
Move Right	→ (Right Arrow)	D
Pause / Resume	Space	-
Mute / Unmute Audio	M	-
Restart / Reload Game	F5	R
Return to Menu	Esc	-
Start Game (from Menu)	Enter	Space / Mouse Click

---

📄 License

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