Add README and revise distance metricHEADmaster

Added many inline comments for clarity.
Introduced initial version of README with gameplay details, controls, and AI logic.
Replaced Euclidean distance with Manhattan distance in standard_distance() to better
match grid-based movement without diagonal traversal.

1 files changed, 98 insertions, 0 deletions

diff --git a/README.md b/README.md
index 6e2db1a..116b66f 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,99 @@
+# Pac-Man (Console Version with `ncurses`)
+
+A terminal-based Pac-Man game written in C with `ncurses`.  It faithfully
+replicates the original ghost AI from the classic 1980 arcade game, including
+their behavioral modes, targeting rules, and unique pathfinding algorithms.
+
+<img src = "pacman.png" />
+
+This version contains one fixed level and implements core gameplay mechanics:
+Pac-Man movement, ghost AI, lives, energizers (power pellets), frightened mode,
+collision handling, and score tracking.
+
+## Features
+
+- **Classic Pac-Man logic** — core mechanics faithfully implemented
+- **Ghost behavior inspired by the original game** — based on *The Pac-Man Dossier*
+- **Mode switching** — scatter, chase, frightened
+- **Unique AI logic per ghost** — each ghost uses different rules and pathfinding
+- **Life system** — Pac-Man has limited lives
+- **Power pellets** — enable Pac-Man to eat ghosts in frightened mode
+- **Colored rendering** — `ncurses`-based graphics with different colors for each ghost and Pac-Man
+- **Directional movement logic** — buffered input for responsive turns
+- **Single static level** — pre-defined grid layout with maze walls and teleport tunnel
+- **Maze collision and coin collection** — walls, tunnels, and dot eating logic
+- **Pause support** — press spacebar to pause/resume the game
+
+## Technologies Used
+
+- **Language:** C (C99)
+- **Graphics:** `ncurses`
+- **Terminal:** ANSI-compatible
+- **Manual memory management**, no external libraries beyond `ncurses`
+
+## Controls
+
+- Arrow keys — Move Pac-Man
+- ESC — Quit the game
+- Spacebar - Pause
+
+## Ghost AI Logic
+
+Each ghost behaves differently depending on the current game mode:
+
+### Game Modes:
+
+- **Chase** — Ghosts pursue targets based on individual AI
+- **Scatter** — Ghosts retreat to their fixed corners
+- **Frightened** — Ghosts move randomly after Pac-Man eats a power pellet
+- **Returning** — Ghosts return to their house after being eaten
+
+### Algorithms Used
+
+- **BFS (Breadth-First Search)** — used for actual pathfinding on the map
+- **Manhattan Distance** — used for heuristic target evaluation
+- **Random Choice** — used when ghosts are frightened
+
+### Ghost Behaviors:
+
+#### Blinky (Red)
+- **Behavior:** Always targets Pac-Man's current tile in chase mode
+- **Algorithm:** BFS
+
+#### Pinky (Pink)
+- **Behavior:** Targets the tile 2 cells ahead of Pac-Man in his current direction
+- **Algorithm:** Manhattan distance
+
+#### Inky (Cyan)
+- **Behavior:**
+
+    1. Computes the tile two cells ahead of Pac-Man
+    2. Calculates a vector from Blinky's position to that tile
+    3. Doubles the vector to determine the target
+
+- **Algorithm:** Manhattan distance
+
+#### Clyde (Orange)
+- **Behavior:**
+
+    - If farther than 8 tiles from Pac-Man: behaves like Blinky (chases)
+    - If closer: retreats to scatter corner
+
+- **Algorithm:** Manhattan distance and BFS hybrid
+
+## Build Instructions
+
+Install `ncurses` (if needed):
+```bash
+sudo apt install libncurses5-dev libncursesw5-dev
+```
+Then:
+
+```bash
+git clone https://git.scratko.xyz/pacman
+cd pacman
+make
+./pacman
+
+```
 Windows version: <a href="https://scratko.xyz/games/pacman.exe" target="_blank">Download</a>