This activity has been created as part of the 42 curriculum by ehazizi, kkulloll.

Pacman

Description

This project is a recreation of the classic arcade game Pac-Man, built from scratch using Python and Pygame. The goal of this activity is to develop a complete, standalone 2D arcade game featuring dynamic grid-based movement, entity collision, level scaling, and rudimentary pathfinding AI for the ghost enemies.

Instructions

This game is designed to be highly portable. It can be run directly from the Python source code or built into a standalone executable.

Installation (Source)

Ensure you have Python 3.11+ installed on your system.

make install

This automatically installs the required dependencies (pygame, pydantic, pyinstaller).

Execution (Source)

To run the game directly from the source code using the default configuration file:

make run

Alternatively, run it manually:

python3 pac-man.py config.json

Packaging (Standalone)

You can build a standalone executable package that does not require a Python environment to run:

• Windows: make package (or run powershell -ExecutionPolicy Bypass -File package.ps1)
• Mac/Linux: make package (or run ./package.sh)

This generates a Pacman_Release.zip archive. Extract the ZIP and run launch_game.bat (Windows) or ./launch_game.sh (Mac/Linux).

Resources

• Pygame Documentation: The official Pygame Docs were used extensively for handling surface rendering, rect collisions, and event loops.
• Pathfinding Concepts: General research on grid-based pathfinding (BFS/A*) was referenced for implementing ghost AI mechanics.
• AI Usage: Artificial Intelligence (LLM) was used during this project to assist with refactoring code for PEP 257 docstring compliance, troubleshooting complex PyInstaller cross-platform packaging issues and diagnosing the maze generation algorithm which was causing the game to freeze on launch. AI was also used to suggest test cases for unit testing and for explaining pygame basic syntax, code examples, algorithms and specific parts of the code.

Configuration

The game is highly data-driven and parses a config.json file at launch.

Default Structure:

{
  "lives": 3,
  "level_max_time": 100,
  "size": [21, 21],
  "perfect": false
}

• lives: The number of lives Pac-Man starts with (default: 3).
• level_max_time: The time limit to clear a level (default: 100 seconds).
• size: The [width, height] of the generated maze. Must be odd numbers.
• perfect: If true, the maze has no loops. If false, loops are created.

Note: The configuration parser is heavily sanitized. If missing or invalid inputs are provided (e.g., negative lives or a grid size of 2), the game logs a warning and clamps the value to safe defaults to prevent crashes.

Highscore

The Highscore system is designed as a persistent local leaderboard. We implemented it using a straightforward JSON serialization approach (highscores.json). Why this approach? We chose a local JSON file over an SQLite database or binary file because it is lightweight, human-readable, easily distributable inside our standalone release packages, and perfectly handles the relatively small amount of data (Top 10 scores) with zero performance overhead.

Maze Generation

The game dynamically generates levels utilizing the assigned A-Maze-ing package. We pass the size and perfect arguments directly from the config into the generator. Optimization: Initially, the provided MazeGenerator utilized an Iterative Deepening Depth-First Search (IDDFS). On imperfect mazes containing loops, this caused an exponential time complexity explosion, freezing the game on launch. Because we were not allowed to modify the core algorithm directly, we resolved this by implementing a secondary FastMazeGenerator class in game.py that utilizes a highly optimized algorithm, allowing the game to load and skip levels instantly.

Implementation

The game is built entirely in Python using an Object-Oriented paradigm. The core loop runs at a fixed 60 FPS, utilizing Pygame's event queue to capture keyboard inputs. Movement is grid-based but interpolated smoothly using pixel coordinates and a base_speed that scales automatically upon leveling up. Ghost pathing utilizes dynamic target tile calculation based on Pac-Man's current position and the Ghost's current state (e.g., frightened, chasing, returning).

General Software Architecture

The architecture is strictly modular, separating the game state from the entity logic to allow concurrent development without conflicts.

• pac-man.py: The main entry point. Handles CLI arguments and passes them to the game loop.
• game.py: The core engine. Manages the Pygame window, the main while loop, rendering the dynamically generated maze, checking win/loss states, and transitioning levels.
• player.py: Contains the Player (Pac-Man) class, handling input reading, movement interpolation, and wall collisions.
• ghosts.py: Contains the Ghost base class and specific logic for AI pathing and behavioral states.
• items.py: Manages consumables like standard Pacgums and Super Pacgums.
• config.py: A robust parser utilizing Pydantic to validate and clamp inputs from config.json.
• highscore_system.py: Handles the reading, sorting, and writing of player scores to the persistent JSON leaderboard.

Project Management

We adopted an iterative, sprint-based approach to divide work horizontally across architectural layers. Enrik handled the player controller, pacgum consumption logic, configuration parsing, highscore system and UI, while Kristjan engineered the ghost AI, super pacgum & fruit consumption logic, level transitions, cross-platform packaging, and visual assets.

For a complete breakdown of our workflow, risk analysis, timeline, and QA acceptance testing, please refer to our dedicated Project Management Directory.