# shingzhanho/engg1330-project-24fall architecture

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

- Interactive diagram: https://gitdiagram.com/shingzhanho/engg1330-project-24fall
- Repository: https://github.com/shingzhanho/engg1330-project-24fall

## Overview

- The game’s core logic, contained within the speed_slide package, which includes game scenes, constants, I/O methods, and the game board logic.
- A text-based user interface (TUI) framework, in the tui package, that provides controls (like text labels, borders, formatted text) and scene management.

##### Main Components
a. Entry Point (main.py):
– This is the launching script that initializes the game.
b. Core Game Module (speed_slide):
– __game_consts.py: Contains runtime-configurable constants (screen dimensions, animation timing, debug flag, etc.).
– io.py: Manages input and simple sound (beep) functionality.
– game_scenes: A directory of modules implementing individual game scenes such as title, main game, help, about, game over, etc.
- Each scene (e.g., TitleScene, MainGameMenuScene, MainGameScene) is implemented as a subclass of the Scene class from the TUI framework.
- A specialised folder within game_scenes (customised_controls) contains custom UI components like the ScoreLabel.
– The game board logic (embedded within MainGameScene and the internal __GameBoard class) that manages board state, moves, and win-checking.
c. TUI Framework (tui):
– Contains core modules for UI rendering and interactions:
- Base scene and screen management (scene.py, screen.py).
- Controls and layout elements (controls folder, with components like control.py, border_tools, dialogue_window, and rich_format_text).
- Utilities for text formatting and transitions.

##### Mapping Relationships and Interactions
- The entry point (main.py) invokes the main() method provided in speed_slide/__init__.py.
- The speed_slide module depends on the tui framework to render its game scenes.
- Game scenes (title, main menu, game over, etc.) extend from tui.scene.Scene and thus inherit behavior defined in the TUI module.
- The __GameBoard (in MainGameScene) encapsulates board logic and interacts with player input (via io.py.safe_input) and uses internal methods (like slide() and find_adjacent()) to update the game state.
- Commands passed (e.g., debug commands like /pass-a, /pass-b, /fail) are handled in-game to change the flow or advance to different scenes.
- The tui module’s controls (e.g., ScoreLabel, TxtLabel) are used by scenes to render dynamic content (score display, messages).

##### Architectural Patterns and Design Principles
- Modularity: Separate packages for core game logic (speed_slide) and UI rendering (tui).
- Layered approach: The game’s business logic (board manipulation, scene transitions) is separated from its presentation layer (TUI controls, ASCII animations).
- Extensibility: The use of a TUI framework that provides a base Scene class enables the addition of new scenes or controls without altering the core logic significantly.
- Commandline Configuration: Command-line arguments (e.g., --debug, --graphics-mode) adjust runtime behaviour, hinting at runtime configurability.

##### Final Checklist for the Principal Software Engineer
– Clearly label every component (e.g., “Main Entry Point (main.py)”, “Game Scenes”, “Game Board Logic (__GameBoard)”, “TUI Framework”).
– Include annotations for command-line configuration and debug mode to illustrate how alternate behaviors are triggered at runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry Point
    A["Main Entry Point (main.py)"]:::entry
    B["Game Core Initialization (speed_slide/__init__.py)"]:::game
    A -->|"Initializes_game(main())"| B
    
    %% Game Core Components
    subgraph "SpeedSlide Game Core" 
        C["Game Constants (__game_consts.py)"]:::game
        D["Input/Output Management (io.py)"]:::game
        E["Game Scenes Container (speed_slide/game_scenes)"]:::game
        G["Custom Controls – Score Label (score_label.py)"]:::game

        B --> C
        B --> D
        B --> E
        B --> G
        
        %% Game Scenes Subgraph
        subgraph "Game Scenes"
            F1["Title Scene (title_scene.py)"]:::game
            F2["Main Game Menu Scene (main_game_menu_scene.py)"]:::game
            F3["Main Game Scene (with Game Board Logic) (main_game_scene.py)"]:::game
            F4["Help Scene (help_scene.py)"]:::game
            F5["About Scene (about_scene.py)"]:::game
            F6["Game Over Scene (game_over_scene.py)"]:::game
            subgraph "Additional Scenes"
                F7a["Game Level Title Scene (game_level_title_scene.py)"]:::game
                F7b["Goodbye Scene (goodbye_scene.py)"]:::game
                F7c["Level Summary Scene (level_summary_scene.py)"]:::game
            end
        end
        %% Link Game Scenes Container to its subcomponents
        E --> F1
        E --> F2
        E --> F3
        E --> F4
        E --> F5
        E --> F6
        E --> F7a
        E --> F7b
        E --> F7c

        %% Input flows into the main game scene for board updates
        D -->|"UserInput"| F3
    end

    %% TUI Framework Components
    subgraph "TUI Framework" 
        H["TUI Base Scene (scene.py)"]:::tui
        I["TUI Screen Management (screen.py)"]:::tui
        J["TUI Transitions (transitions.py)"]:::tui
        subgraph "UI Controls"
            K1["Base Control (control.py)"]:::control
            K2["Border Tools (__border_tools.py)"]:::control
            K3["Dialogue Window (dialogue_window.py)"]:::control
            K4["Rich Formatted Text (rich_format_text.py)"]:::control
            K5["Text Label (txt_label.py)"]:::control
        end
        L["TUI Text Formatting Utilities (text_formats.py)"]:::tui
    end

    %% Inheritance and Interaction between Game and TUI
    E -->|"Extends_Scene"| H
    F1 ---|"inherits"| H
    F2 ---|"inherits"| H
    F3 ---|"inherits"| H
    F4 ---|"inherits"| H
    F5 ---|"inherits"| H
    F6 ---|"inherits"| H
    F7a ---|"inherits"| H
    F7b ---|"inherits"| H
    F7c ---|"inherits"| H

    %% Game Scenes use UI Controls for rendering dynamic content
    E -->|"Renders_UI"| K1
    E -->|"Renders_UI"| K2
    E -->|"Renders_UI"| K3
    E -->|"Renders_UI"| K4
    E -->|"Renders_UI"| K5

    %% Styling Classes
    classDef entry fill:#FCE4EC,stroke:#AD1457,stroke-width:2px;
    classDef game fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px;
    classDef tui fill:#E8F5E9,stroke:#43A047,stroke-width:2px;
    classDef control fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px;

    %% Click Events
    click A "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/main.py"
    click B "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/__init__.py"
    click C "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/__game_consts.py"
    click D "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/io.py"
    click E "https://github.com/shingzhanho/engg1330-project-24fall/tree/master/speed_slide/game_scenes"
    click F1 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/title_scene.py"
    click F2 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/main_game_menu_scene.py"
    click F3 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/main_game_scene.py"
    click F4 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/help_scene.py"
    click F5 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/about_scene.py"
    click F6 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/game_over_scene.py"
    click F7a "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/game_level_title_scene.py"
    click F7b "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/goodbye_scene.py"
    click F7c "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/level_summary_scene.py"
    click G "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/speed_slide/game_scenes/customised_controls/score_label.py"
    click H "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/scene.py"
    click I "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/screen.py"
    click J "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/transitions.py"
    click K1 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/controls/control.py"
    click K2 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/controls/__border_tools.py"
    click K3 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/controls/dialogue_window.py"
    click K4 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/controls/rich_format_text.py"
    click K5 "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/controls/txt_label.py"
    click L "https://github.com/shingzhanho/engg1330-project-24fall/blob/master/tui/text_formats.py"
```
