Pac-Man in Python

A Python Pac-Man game with split UI and simulation layers.

Description

This project is a Python implementation of Pac-Man built with a split architecture:

• src/: UI, screen flow, config parsing, highscore management
• game/: world simulation, entities, movement, collisions, scoring

The goal is to provide a playable game with robust config handling, persistent highscores, and a maintainable object-oriented codebase.

Instructions

Requirements

• Python 3.10
• make

Install

make install

What this does (from Makefile):

• creates .venv
• installs requirements.txt
• installs mazegenerator-2.0.1-py3-none-any.whl

Run

make run

Equivalent command used by the Makefile:

.venv/bin/python3.10 pac-man.py config.json

The program expects exactly one .json config argument:

.venv/bin/python3.10 pac-man.py <config.json>

Debug / Lint / Clean

make debug
make lint
make clean

Controls during gameplay:

• move: arrows / WASD / IJKL
• pause/resume: SPACE or ESC

Configuration

Config is loaded from JSON with comment stripping support:

• full-line #
• full-line //
• block comments /* ... */

Unknown keys are ignored with warnings. Invalid/missing values fall back to defaults.

Supported keys and defaults

Key	Default	Rule	Notes
highscore_file	highscores.json	must be a string ending in .json	file path for persistent scores
lives	3	integer >= 1	starting lives
width	19	integer, then clamped to 14..23	maze width in cells
height	21	integer, then clamped to 14..23	maze height in cells
seed	42	integer >= 0	maze generation seed
pts_pacgum	10	integer >= 0	score for pacgum
pts_super	50	integer >= 0	score for super pacgum
pts_ghost	200	integer >= 0	score for ghost while vulnerable
max_time	90	integer >= 1	timer shown in HUD

Example config.json:

{
    "highscore_file": "highscores.json",
    "lives": 3,
    "width": 15,
    "height": 15,
    "seed": 42,
    "pts_pacgum": 10,
    "pts_super": 50,
    "pts_ghost": 200,
    "max_time": 10
}

Highscore

Highscores are persisted in JSON via src/highscore.py.

Behavior:

• entries are validated on load (name and score constraints)
• invalid entries are skipped with warnings
• scores are sorted descending
• top-10 logic keeps ties at rank 10
• file read/write errors are handled without crashing

Validation rules:

• name: max 10 chars, [A-Za-z0-9 ], non-empty after trim
• score: non-negative integer

Design choice rationale:

• JSON is simple, transparent, and easy to verify during review
• strict validation keeps corrupted files from crashing runtime

Maze Generation

Maze generation is wrapped in game/MazeGen.py and uses the assigned external package (mazegenerator).

Implementation details:

• MazeGen inherits MazeGenerator
• perfect=False is passed to the generator
• output is converted to a NumPy array used by World
• generation is seeded from config (seed)

Install source:

• mazegenerator-2.0.1-py3-none-any.whl (installed by make install)

Implementation

Technical summary of the current implementation:

• entrypoint: pac-man.py
• rendering/input: OpenCV (cv2)
• text rendering: Pillow
• screen flow/state machine: transitions (src/screen_factory.py)
• game loop owner: ScreenManager
• game simulation: World + entities (Player, Ghost, pacgums)
• cheat code detection: buffered keyboard sequence matching (src/constants.py)

Current gameplay behavior in code:

• game ends when lives reach 0 and transitions to save/game-over flow
• HUD shows timer (max_time), but timer expiry is not currently used as a transition condition

General Software Architecture

High-level module relationships:

pac-man.py
    ├─ load_config() -> Config + warnings
    ├─ HighscoreManager.load()
    └─ ScreenManager
            └─ ScreenFactory (state machine)
                    ├─ Menu / Help / Highscore / Pause / Cheat / Save / GameOver
                    └─ GameScreen
                            └─ World (game/)
                                    ├─ MazeGen
                                    ├─ Player
                                    ├─ Ghost x4
                                    └─ Edibles (PacGum / SuperPacGum)

For more details, see:

• project_management/architecture.md

Project Management

Project management artifacts are in:

• project_management/

Briefly:

• work split by layer (game/ vs src/)
• incremental integration and smoke tests with make run
• architecture/process notes tracked in:
  • project_management/architecture.md
  • project_management/project_management.md

Resources

Classic references:

• Python documentation: https://docs.python.org/3/
• OpenCV (Python): https://docs.opencv.org/
• Pillow: https://pillow.readthedocs.io/
• transitions state machine: https://github.com/pytransitions/transitions

AI usage in this project:

• Tool used: GitHub Copilot
• Used for: targeted refactoring suggestions, documentation drafting, and consistency checks
• Human-owned parts: architecture decisions, gameplay behavior choices, final code/document review, and validation against project requirements