# j-c7/universal-sky architecture

> Architecture diagram of the GitHub repository j-c7/universal-sky, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/j-c7/universal-sky
- Repository: https://github.com/j-c7/universal-sky

## Overview

##### Main Components
- Plugin Core: At the top level, include the essential plugin configuration and main entry point:
- plugin.cfg: This defines the plugin’s configuration for Godot.
- plugin.gd: Likely the main script that initializes or manages the plugin integration with Godot.

- Assets Module: Represent the assets folder which holds:

- Source Code Modules (under src):
- Common Utilities:
- Located in src/common (usky_math.gd and usky_util.gd). These utilities likely perform mathematical operations and utility functions used throughout the plugin.

- Sky Module: This is the core of the plugin and contains multiple sub-components:
a. Celestial Bodies:
- Located in src/sky/celestials. Includes separate scripts for 3D representations of various celestial objects such as:
- usky_celestial_body_3d.gd (a general celestial body),
- usky_moon_3d.gd (dedicated moon logic),
- usky_sun_3d.gd (dedicated sun logic).

b. Materials:
- Under src/sky/material. Contains a base material script and a standard material script, indicating an inheritance or extension pattern for managing sky-related materials.

c. Shaders:
- This is divided into further sections:
- Shared Shader Libraries (src/sky/shaders/library):
- Sky-Specific Shaders (under src/sky/shaders/sky):
- Contains common shader snippets for deep space, the moon, the sun, and variable definitions.
- A specialized branch (standard-sky) for default atmospheric and sky rendering effects (standard atmosphere and sky shaders).

d. Sky Manager:
- Located in src/sky/sky-manager (usky3d.gd), which likely coordinates the overall sky system—integrating celestial bodies, materials, and shaders to produce the final visual output.

##### Relationships and Interactions
- The Plugin Core (plugin.gd and plugin.cfg) loads and initializes the entire system when integrated into a Godot project.
- The Common Utilities are shared across the sky module to perform underlying computations (like positioning or timing).
- The Sky Manager acts as the orchestrator, connecting:
- Celestial Bodies (which use the Common Utilities to calculate positions and movements),
- Materials (which define how the sky is rendered), and
- Shaders (which are used to generate the visual effects).
- Shaders pull in the library files to ensure consistency and reusability across different sky effects.

##### Architectural Patterns and Design Principles
- Modular Design: The project is well divided into discrete modules, each with its own responsibility (assets, common utilities, celestial bodies, materials, shaders, and management).
- Separation of Concerns: By isolating shader libraries from higher-level sky management and having separate scripts for each celestial body, the design maintains clarity and ease of maintenance.
- Reusability: Common utilities and shader libraries are designed for reuse across multiple parts of the plugin.
- Extensibility: The clear separation between base and standard materials, as well as distinct shader directories, suggests that the plugin is built to be extended (e.g., adding new celestial bodies or different sky effects).

## Diagram (Mermaid)

```mermaid
flowchart TB
    PC["Plugin Core (plugin.cfg, plugin.gd)"]:::core
    A["Assets Module (Textures, Icons)"]:::assets
    CU["Common Utilities (usky_math.gd, usky_util.gd)"]:::utils
    SM["Sky Manager (usky3d.gd)"]:::manager

    subgraph "Sky Module"
        CB["Celestial Bodies (3D Scripts)"]:::module
        M["Materials (Base & Standard)"]:::module
        S["Shaders"]:::shader
    end

    subgraph "Shader Subsystem"
        SL["Shader Libraries"]:::subshader
        SS["Sky-Specific Shaders"]:::subshader
        CS["Common Shaders"]:::subshader
        STS["Standard Sky Shaders"]:::subshader
    end

    PC -->|"initializes"| SM
    SM -->|"orchestrates"| CB
    SM -->|"orchestrates"| M
    SM -->|"orchestrates"| S
    CU -->|"provides_calculations"| CB
    M -->|"uses_textures"| A
    S -->|"uses_textures"| A
    S -->|"includes"| SL
    S -->|"includes"| SS
    SS -->|"contains"| CS
    SS -->|"contains"| STS

    click PC "https://github.com/j-c7/universal-sky/blob/main/plugin.cfg"
    click PC "https://github.com/j-c7/universal-sky/blob/main/plugin.gd"
    click A "https://github.com/j-c7/universal-sky/tree/main/assets"
    click CU "https://github.com/j-c7/universal-sky/blob/main/src/common/usky_math.gd"
    click CU "https://github.com/j-c7/universal-sky/blob/main/src/common/usky_util.gd"
    click CB "https://github.com/j-c7/universal-sky/blob/main/src/sky/celestials/usky_celestial_body_3d.gd"
    click CB "https://github.com/j-c7/universal-sky/blob/main/src/sky/celestials/usky_moon_3d.gd"
    click CB "https://github.com/j-c7/universal-sky/blob/main/src/sky/celestials/usky_sun_3d.gd"
    click M "https://github.com/j-c7/universal-sky/blob/main/src/sky/material/usky_material_base.gd"
    click M "https://github.com/j-c7/universal-sky/blob/main/src/sky/material/usky_standard_material.gd"
    click SL "https://github.com/j-c7/universal-sky/tree/main/src/sky/shaders/library"
    click SS "https://github.com/j-c7/universal-sky/tree/main/src/sky/shaders/sky/common"
    click STS "https://github.com/j-c7/universal-sky/blob/main/src/sky/shaders/sky/standard-sky/usky_standard_atmosphere.gdshaderinc"
    click STS "https://github.com/j-c7/universal-sky/blob/main/src/sky/shaders/sky/standard-sky/usky_standard_sky.gdshader"
    click SM "https://github.com/j-c7/universal-sky/blob/main/src/sky/sky-manager/usky3d.gd"

    classDef core fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef assets fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef utils fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef manager fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef module fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef shader fill:#e0ffff,stroke:#333,stroke-width:2px;
    classDef subshader fill:#daf7a6,stroke:#333,stroke-width:2px;
```
