# shingzhanho/engg1340-project-25spring architecture

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

- Interactive diagram: https://gitdiagram.com/shingzhanho/engg1340-project-25spring
- Repository: https://github.com/shingzhanho/engg1340-project-25spring

## Overview

##### Project Type & Purpose
- SHOOT! is a C++ console-based shooting game with:
- Core game logic (entities, arena, event handling)
- UI layer (FTXUI-based rendering)
- Utility modules (logging, file I/O, map parsing)
- Multithreading for game ticks and logging (pthread)

##### High-Level Components
A. Executable (“main”)
B. Core Layer (namespace core)
1. Game
2. Arena & ArenaReader
3. Entity hierarchy (Entity ← Player, Monster, Bullet, Collectible, etc.)
4. EventHandler hierarchy (EventHandler ← TickRefreshHandler, InputHandler, SpawnHandler, etc.)
5. GameOptions, Leaderboard
C. UI Layer (namespace ui + FTXUI)
1. game_ui_renderer, render_option, common UI widgets
2. game_level_ui, game_score_ui, leaderboard_ui
D. Util Layer (namespace util)
1. log (logger), file utilities
E. Resources
1. Files (res/default_maps & res/sample_maps)
2. Leaderboard storage files
F. External Services & Libraries
1. FTXUI (console GUI)
2. pthread (threading)

##### Namespaces & Class Dependencies
- Inside core:
- ArenaReader has a dependency on file I/O to build an Arena.
- Game composes Arena and one or more EventHandlers, and depends on GameOptions and Leaderboard.
- In ui:
- UI screens (game_level_ui, game_score_ui, leaderboard_ui) depend on Game and GameUIRenderer.
- In util:
- Log provides logging services to Core (Arena, Game, EventHandlers) and UI.
- File operations (map loading, leaderboard saving) depend on util::log and standard I/O.

##### Relationships & Data Flows
- Main → instantiates Game
- Game → initializes Arena, EventHandlers, UI screens
- EventHandlers → invoke methods on Arena (spawn, move, collision)
- Arena → updates Entities and notifies EventHandlers
- UI → polls Game state each frame (via Game and Arena) and renders via FTXUI
- Util::log ← subscribed by Core/UI to write logs
- Reader → reads map file → provides initial Arena state
- Leaderboard ↔ file system for score persistence

##### Architectural Patterns & Design Principles
- Namespace modularity: core vs ui vs util
- Abstract base classes + inheritance for Entities and EventHandlers (polymorphism)
- Single Responsibility:
- Arena manages state
- EventHandler executes actions
- Game orchestrates lifecycle
- UI renders and handles input
- Dependency injection: GameOptions and map path passed into Game/ArenaReader
- Thread safety: Arena uses mutexes for multithreaded tick refresh and logging

##### Mandatory Elements
- Clear labels for each component and namespace

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Layer (namespace core)"
        direction TB
        Entity["Entity (abstract)"]:::core
        Player["Player"]:::core
        Monster["Monster"]:::core
        Troll["Troll"]:::core
        Boss["Boss"]:::core
        Bullet["Bullet"]:::core
        Collectible["Collectible"]:::core

        EventHandler["EventHandler (abstract)"]:::core
        TickHandler["TickRefreshHandler"]:::core
        InputHandler["UserInputEventHandler"]:::core
        SpawnHandler["SpawnHandler"]:::core

        Arena["Arena"]:::core
        ArenaReader["ArenaReader"]:::core
        Game["Game"]:::core
        GameOptions["GameOptions"]:::core
        Leaderboard["Leaderboard"]:::core
        Point["Point"]:::core
    end

    %% UI Layer
    subgraph "UI Layer (namespace ui + FTXUI)"
        direction TB
        CommonUI["common UI widgets"]:::ui
        GameUI["GameUIRenderer"]:::ui
        RenderOpt["RenderOption"]:::ui
        LevelUI["game_level_ui"]:::ui
        ScoreUI["game_score_ui"]:::ui
        LeaderboardUI["leaderboard_ui"]:::ui
    end

    %% Util Layer
    subgraph "Util Layer (namespace util)"
        direction TB
        Log["Log (logger)"]:::util
    end

    %% Resources
    subgraph "Resources"
        direction TB
        DefaultMaps["res/default_maps"]:::external
        SampleMaps["res/sample_maps"]:::external
        LeaderFiles["Leaderboard files"]:::external
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        FTXUI["FTXUI"]:::external
        PThread["pthread"]:::external
    end

    %% Inheritance
    Entity -->|«inherits»| Player
    Entity -->|«inherits»| Monster
    Entity -->|«inherits»| Troll
    Entity -->|«inherits»| Boss
    Entity -->|«inherits»| Bullet
    Entity -->|«inherits»| Collectible

    EventHandler -->|«inherits»| TickHandler
    EventHandler -->|«inherits»| InputHandler
    EventHandler -->|«inherits»| SpawnHandler

    %% Composition & Aggregation
    Game -->|"1 uses *"| EventHandler
    Game -->|"1 composes 1"| Arena
    Arena -->|"aggregates *"| Entity

    %% Dependencies
    ArenaReader ---|reads map| DefaultMaps
    ArenaReader ---|uses| Log
    GameOptions ---|injected into| Game
    Leaderboard ---|persists to| LeaderFiles
    Game ---|depends on| GameOptions
    Game ---|depends on| Leaderboard
    Game ---|uses| ArenaReader

    GameUI ---|depends on| Entity
    GameUI ---|depends on| Arena
    LevelUI ---|depends on| Game
    LevelUI ---|renders via| GameUI
    ScoreUI ---|depends on| Game
    ScoreUI ---|renders via| GameUI
    LeaderboardUI ---|depends on| Leaderboard
    LeaderboardUI ---|renders via| GameUI

    %% Core & Util
    Game ---|logs to| Log
    Arena ---|logs to| Log
    EventHandler ---|logs to| Log
    CommonUI ---|logs to| Log

    %% External deps
    CommonUI ---|uses| FTXUI
    GameUI ---|uses| FTXUI
    Log ---|uses| PThread
    Game ---|uses| PThread
    Arena ---|uses| PThread

    %% Main Executable
    Main["main (src/main.cpp)"]:::core
    Main -->|"instantiates"| Game
    Main ---|reads default maps| DefaultMaps

    %% Click Events
    click Main "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/src/main.cpp"

    click Game "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/game.hpp"
    click Arena "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/arena.hpp"
    click ArenaReader "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/arena_reader.hpp"
    click Entity "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/entity.hpp"
    click Point "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/point.hpp"
    click EventHandler "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/event_handler.hpp"
    click GameOptions "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/game_options.hpp"
    click Leaderboard "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/core/leaderboard.hpp"

    click CommonUI "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/ui/common.hpp"
    click GameUI "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/ui/game_ui_renderer.hpp"
    click RenderOpt "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/ui/render_option.hpp"
    click LevelUI "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/src/game_level_ui.hpp"
    click ScoreUI "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/src/game_score_ui.hpp"
    click LeaderboardUI "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/src/leaderboard_ui.hpp"

    click Log "https://github.com/shingzhanho/engg1340-project-25spring/blob/master/include/util/log.hpp"
    click DefaultMaps "https://github.com/shingzhanho/engg1340-project-25spring/tree/master/res/default_maps"
    click SampleMaps "https://github.com/shingzhanho/engg1340-project-25spring/tree/master/res/sample_maps"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef ui fill:#d4edda,stroke:#155724,color:#155724;
    classDef util fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:none,stroke:#6c757d,stroke-dasharray: 5 5,color:#6c757d;
```
