# masonicgit/pacman architecture

> Architecture diagram of the GitHub repository masonicgit/pacman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/masonicgit/pacman
- Repository: https://github.com/masonicgit/pacman

## Overview

##### Project type and purpose
- This is a single-page, front-end–only HTML5/JavaScript game (no persistent back-end).
- Purpose: faithfully recreate Pac-Man (and variants), including procedural map generation, accuracy modes, practice/learn modes, and sound.

##### File structure
Top-level areas:
- build.sh, package.json, .eslintrc.json, next.config.js
– Build environment: Node/npm (linting, packaging), simple bash script to concatenate source.
- src/
– Core game engine (Actor.js, Ghost.js, Map.js, game.js, renderers.js, input.js, sound.js, main.js, etc.).
- sprites/, sounds/, font/
– Static asset directories (sprite atlases, audio files, fonts).
- fruit/, mapgen/, randturn/, promo/
– Research & experimental tools: fruit-path analysis, procedural maze generators, random-turn statistics, promotional/demo pages.
- index.html / debug.html / pacman.js
– Entry points:
- debug.html loads individual src/*.js for development
- index.html loads bundled pacman.js for production
- doc/, issues/, BACKLOG
– Documentation, design notes, reverse-engineering artifacts

##### README for insights
- Confirms the static front-end nature: “all javascript source files are located in the ‘src/’ directory,” “build.sh concatenates into pacman.js,” “index.html uses pacman.js.”
- Describes game modes (Learn, Practice, Cookie-Man procedural maps), controls, confirmed platforms.
- Details design goals: accuracy to original arcade physics, ghost AI, timing.

##### Main components and relationships
a. Build & Deployment (offline toolchain)
- Node/npm environment (package.json)
- build.sh script
- Outputs pacman.js
- Static asset bundling

b. Static File Server (could be GitHub Pages, any HTTP server)
- Serves index.html, pacman.js, sprites/, sounds/, font/

c. Client (Browser)
- HTML5 Canvas + DOM (index.html)
- pacman.js game logic
- Canvas renderer (renderers.js)
- Input module (keyboard, touch)
- Audio module (sound.js)
- Asset loader (sprites, sounds, fonts)
- Game loop / state manager (main.js, executive.js, states.js)
- Generator (mapgen.js for Cookie-Man mode; experimental code in mapgen/ dir)
- UI overlays (menus, HUD, cutscenes)

d. External Resources
- Reverse-engineering docs (doc/disasm/)—used offline, not at runtime
- Experimental tools (fruit/, randturn/)—offline utilities

##### Architectural patterns & design principles
- Modular JavaScript: each concern in its own module (Actor, Ghost, Map, Renderer, Input, Sound).
- Single Event Loop: canonical game loop handles input → update → render.
- Asset Separation: clear directories for sprites, sounds, fonts.
- Build vs. Runtime separation: debug vs. production bundles.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        Build_sh["build.sh"]:::buildDef
        Package_json["package.json"]:::buildDef
        Eslint[".eslintrc.json"]:::buildDef
        Pacman_bundle["pacman.js"]:::buildDef
        Build_sh -->|"runs"| Pacman_bundle
        Package_json -->|"defines deps"| Pacman_bundle
        Eslint -->|"lint rules"| Pacman_bundle
    end

    %% Static File Host
    subgraph "Static File Host"
        direction TB
        Index_html["index.html"]:::hostDef
        Debug_html["debug.html"]:::hostDef
        Sprites_dir["sprites/"]:::assetDef
        Sounds_dir["sounds/"]:::assetDef
        Font_dir["font/"]:::assetDef
    end

    %% Offline R&D Tools
    subgraph "Offline R&D Tools"
        direction TB
        Fruit_tool["fruit/"]:::offlineDef
        Mapgen_tools["mapgen/"]:::offlineDef
        Randturn["randturn/"]:::offlineDef
        Promo["promo/"]:::offlineDef
        Disasm["doc/disasm/"]:::offlineDef
    end

    %% Browser Client
    subgraph "Browser Client" 
        direction TB
        subgraph "Asset Loader"
            direction TB
            Atlas_js["src/atlas.js"]:::clientDef
            Sprites_js["src/sprites.js"]:::clientDef
        end
        subgraph "Input Manager"
            direction TB
            Input_js["src/input.js"]:::clientDef
        end
        subgraph "Game Loop / State Manager"
            direction TB
            Main_js["src/main.js"]:::clientDef
            Executive_js["src/executive.js"]:::clientDef
            States_js["src/states.js"]:::clientDef
        end
        subgraph "Game Engine Core"
            direction TB
            Game_js["src/game.js"]:::clientDef
            Actor_js["src/Actor.js"]:::clientDef
            Ghost_js["src/Ghost.js"]:::clientDef
            Map_js["src/Map.js"]:::clientDef
            Player_js["src/Player.js"]:::clientDef
            Fruit_js["src/fruit.js"]:::clientDef
            Direction_js["src/direction.js"]:::clientDef
            Energizer_js["src/energizer.js"]:::clientDef
            GalagaStars_js["src/galagaStars.js"]:::clientDef
            GhostCommander_js["src/ghostCommander.js"]:::clientDef
            GhostReleaser_js["src/ghostReleaser.js"]:::clientDef
            ElroyTimer_js["src/elroyTimer.js"]:::clientDef
            Maps_js["src/maps.js"]:::clientDef
            Random_js["src/random.js"]:::clientDef
            Targets_js["src/targets.js"]:::clientDef
        end
        subgraph "Renderer (Canvas)"
            direction TB
            Renderers_js["src/renderers.js"]:::clientDef
        end
        subgraph "Audio Engine"
            direction TB
            Sound_js["src/sound.js"]:::clientDef
        end
        subgraph "UI Layer"
            direction TB
            Menu_js["src/Menu.js"]:::clientDef
            InGameMenu_js["src/inGameMenu.js"]:::clientDef
            HUD_js["src/hud.js"]:::clientDef
            Cutscenes_js["src/cutscenes.js"]:::clientDef
            Button_js["src/Button.js"]:::clientDef
        end
        subgraph "Procedural Map Generation"
            direction TB
            Mapgen_js["src/mapgen.js"]:::clientDef
        end
    end

    %% Connections
    Pacman_bundle -->|"deployed to"| Index_html
    Pacman_bundle -->|"deployed to"| Debug_html
    Index_html -->|"HTTP GET pacman.js"| Atlas_js
    Debug_html -->|"HTTP GET modules"| Atlas_js

    Index_html -->|"HTTP GET assets"| Sprites_dir
    Index_html -->|"HTTP GET assets"| Sounds_dir
    Index_html -->|"HTTP GET assets"| Font_dir

    Sprites_dir -->|"serves"| Atlas_js
    Sounds_dir -->|"serves"| Sound_js
    Font_dir -->|"serves"| Menu_js

    Atlas_js -->|"loads sprites"| Renderers_js
    Sprites_js -->|"loads atlas"| Renderers_js

    Input_js -->|"user input"| Main_js
    Main_js -->|"controls flow"| Executive_js
    Executive_js -->|"manages states"| States_js
    States_js -->|"updates"| Game_js

    Game_js -->|"updates actors"| Actor_js
    Game_js -->|"updates ghosts"| Ghost_js
    Game_js -->|"generates map"| Map_js
    Mapgen_js -->|"procedural maps"| Map_js

    Game_js -->|"triggers audio"| Sound_js
    Game_js -->|"triggers render"| Renderers_js

    Renderers_js -->|"draw on canvas"| Menu_js
    Sound_js -->|"play sound"| HUD_js

    Menu_js -->|"UI events"| Main_js
    InGameMenu_js -->|"UI events"| Main_js
    HUD_js -->|"display state"| Main_js
    Cutscenes_js -->|"display cinematic"| Main_js
    Button_js -->|"UI control"| Main_js

    %% Offline tools connections (dashed)
    Fruit_tool -.->|"analysis"| Fruit_js
    Mapgen_tools -.->|"experiments"| Mapgen_js
    Randturn -.->|"stats"| Random_js
    Promo -.->|"demos"| Index_html
    Disasm -.->|"reference"| Game_js

    %% Click Events
    click Build_sh "https://github.com/masonicgit/pacman/blob/master/build.sh"
    click Package_json "https://github.com/masonicgit/pacman/blob/master/package.json"
    click Eslint "https://github.com/masonicgit/pacman/blob/master/.eslintrc.json"
    click Pacman_bundle "https://github.com/masonicgit/pacman/blob/master/pacman.js"
    click Index_html "https://github.com/masonicgit/pacman/blob/master/index.html"
    click Debug_html "https://github.com/masonicgit/pacman/blob/master/debug.html"
    click Sprites_dir "https://github.com/masonicgit/pacman/tree/master/sprites/"
    click Sounds_dir "https://github.com/masonicgit/pacman/tree/master/sounds/"
    click Font_dir "https://github.com/masonicgit/pacman/tree/master/font/"
    click Atlas_js "https://github.com/masonicgit/pacman/blob/master/src/atlas.js"
    click Sprites_js "https://github.com/masonicgit/pacman/blob/master/src/sprites.js"
    click Input_js "https://github.com/masonicgit/pacman/blob/master/src/input.js"
    click Main_js "https://github.com/masonicgit/pacman/blob/master/src/main.js"
    click Executive_js "https://github.com/masonicgit/pacman/blob/master/src/executive.js"
    click States_js "https://github.com/masonicgit/pacman/blob/master/src/states.js"
    click Game_js "https://github.com/masonicgit/pacman/blob/master/src/game.js"
    click Actor_js "https://github.com/masonicgit/pacman/blob/master/src/Actor.js"
    click Ghost_js "https://github.com/masonicgit/pacman/blob/master/src/Ghost.js"
    click Map_js "https://github.com/masonicgit/pacman/blob/master/src/Map.js"
    click Player_js "https://github.com/masonicgit/pacman/blob/master/src/Player.js"
    click Fruit_js "https://github.com/masonicgit/pacman/blob/master/src/fruit.js"
    click Direction_js "https://github.com/masonicgit/pacman/blob/master/src/direction.js"
    click Energizer_js "https://github.com/masonicgit/pacman/blob/master/src/energizer.js"
    click GalagaStars_js "https://github.com/masonicgit/pacman/blob/master/src/galagaStars.js"
    click GhostCommander_js "https://github.com/masonicgit/pacman/blob/master/src/ghostCommander.js"
    click GhostReleaser_js "https://github.com/masonicgit/pacman/blob/master/src/ghostReleaser.js"
    click ElroyTimer_js "https://github.com/masonicgit/pacman/blob/master/src/elroyTimer.js"
    click Maps_js "https://github.com/masonicgit/pacman/blob/master/src/maps.js"
    click Random_js "https://github.com/masonicgit/pacman/blob/master/src/random.js"
    click Targets_js "https://github.com/masonicgit/pacman/blob/master/src/targets.js"
    click Renderers_js "https://github.com/masonicgit/pacman/blob/master/src/renderers.js"
    click Sound_js "https://github.com/masonicgit/pacman/blob/master/src/sound.js"
    click Menu_js "https://github.com/masonicgit/pacman/blob/master/src/Menu.js"
    click InGameMenu_js "https://github.com/masonicgit/pacman/blob/master/src/inGameMenu.js"
    click HUD_js "https://github.com/masonicgit/pacman/blob/master/src/hud.js"
    click Cutscenes_js "https://github.com/masonicgit/pacman/blob/master/src/cutscenes.js"
    click Button_js "https://github.com/masonicgit/pacman/blob/master/src/Button.js"
    click Mapgen_js "https://github.com/masonicgit/pacman/blob/master/src/mapgen.js"
    click Mapgen_tools "https://github.com/masonicgit/pacman/tree/master/mapgen/"
    click Fruit_tool "https://github.com/masonicgit/pacman/tree/master/fruit/"
    click Randturn "https://github.com/masonicgit/pacman/tree/master/randturn/"
    click Promo "https://github.com/masonicgit/pacman/tree/master/promo/"
    click Disasm "https://github.com/masonicgit/pacman/tree/master/doc/disasm/"

    %% Styles
    classDef buildDef fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef hostDef fill:#E8E9EB,stroke:#5E6C84,color:#1B1F23;
    classDef assetDef fill:#F5F5F5,stroke:#CCCCCC,color:#333333;
    classDef clientDef fill:#E6FFED,stroke:#28A745,color:#22863A;
    classDef offlineDef fill:none,stroke:#D73A49,color:#D73A49,stroke-dasharray: 5 5;
```
