How mishpajz-fit/bi-pa2-pacman works
<explanation>
Below is a step‑by‑step guide tailored to your Pacman terminal game project, showing how to represent its architecture in a system design diagram. We’ll break the project into logical components, show their relationships, and recommend diagramming conventions.
1. Identify the Project Type and Purpose
- Type: Single‑binary C++ game, playable in terminal, structured with a simplified Model‑View‑ViewModel (MVVM) approach.
- Purpose: Render a Pacman clone using ncurses, load/save maps and settings, manage game states and AI, and persist high scores.
2. Main Architectural Components
A. Model Layer (Game State & Logic)
• GameLogic/
– Board (grid, cells, teleportation)
– Entities (Player, Enemy base, Ghosts with AI modes)
– Game (orchestrates tick/update, collision)
• AppState (current lives, score, level)
• StateManager (tracks which UI or game state is active)
B. ViewModel & Controllers
• ViewControllers/
– MainMenuViewController (handles menu navigation)
– GameViewController (relays input to game logic, triggers updates)
– ViewController base (common input/output glue)
• Utilities/Contexts/
– GameControl, GameSettings, GameRecords, OptionMenu contexts (shared state buckets for VMs)
C. View Layer (Rendering)
• Views/
– LayoutView, LoadingView, LogoView, GameView, GameOverView
– SecondaryViews (OptionMenuView, SettingsView, GameDetailView)
– All use ncurses to draw to terminal
D. Persistence & Configuration
• Utilities/FileManagers/
– FileManager (generic I/O)
– BoardFileLoader (map parsing)
– GameSettingsRecordsFileLoader/Saver (load/save high scores & settings)
E. Infrastructure & Utilities
• Utilities/Timer (schedules game ticks)
• Utilities/NCColors (defines color pairs for ncurses)
• Structures/Transforms & Matrix (geometry helpers)
F. Entry Point
• main.cpp
– Bootstraps: parses args, initializes ncurses, loads config & map, enters main loop via StateManager
3. Component Interactions & Data Flow
- main.cpp → StateManager: start in MainMenu state
- MainMenuViewController ←→ Utilities/Contexts: read menu options
- Upon “Start Game”: GameViewController calls GameLogic::Game.update() each tick via Timer
- Game.update() manipulates Board & Entities → updates AppState (score, lives)
- GameRecordsContext & FileManagers: persist high‑score on game end
- ViewControllers push state to Views, which draw via ncurses
- Input from user flows from View → Controller → Model
4. Architectural Patterns & Design Principles
- MVVM‑inspired separation:
– Model: pure game logic, no UI code
– ViewModel/Controllers: mediate between UI & logic, hold contexts
– View: pure rendering, no logic
- Single responsibility: each FileManager handles one file type
- Dependency direction: high‑level controllers depend on lower‑level utilities, not vice versa
5. Diagramming Guidelines
a. Layout:
- Arrange in horizontal layers:
[Persistence & Config] → [Model Layer] → [Controllers/ViewModels] → [View Layer]
with main.cpp above orchestrating the flow.
b. Arrows:
- Use solid arrows for “calls/uses” relationships (e.g., GameViewController → Game.update())
- Use dashed arrows for “data flows” (e.g., User Input → MainMenuViewController)
c. Color‑Coding / Shapes:
- Blue rectangles: Model components (GameLogic, AppState)
- Green rectangles: Controllers/ViewModels (ViewControllers, Contexts)
- Yellow rectangles: Views (GameView, SecondaryViews)
- Gray cylinders or documents: FileManagers & Data (map.spac, settings.spac)
- Orange parallelogram: ncurses external library
d. Labels:
- Clearly label each box with component name
- On arrows, annotate the interaction (e.g., “loadMap()”, “render()”, “saveScore()”)
6. Tailoring for This Project
- Emphasize ncurses as the sole external dependency; show it as a library the Views link against.
- Show the GameLogic/Entities sub‑packages to illustrate how each ghost AI is a specialization of Enemy.
- Illustrate the StateManager as the finite‑state‑machine driving which controller/view pair is active.
- Include the examples/ and doc/ directories off to the side as “Examples & Documentation” artifacts.
7. Final Checklist For the Diagram
[ ] Main components boxed & labeled
[ ] Arrows with direction & annotations
[ ] Layers separated: Persistence → Model → Controllers → View → External
[ ] Color/shape legend distinguishing types
[ ] Notes on patterns (MVVM, single responsibility) included in a sidebar
By following this structure, your diagram will clearly show how the Pacman game is decomposed, how data and control flow through the system, and what key technologies and modules play a role.