# seblague/fluid-sim architecture

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

- Interactive diagram: https://gitdiagram.com/seblague/fluid-sim
- Repository: https://github.com/seblague/fluid-sim

## Overview

##### Main Components
- Simulation Engine:
- This is largely found under the Assets/Scripts/Simulation and Assets/Scripts/Sim2D directories. It contains compute shaders (HLSL files), computation logic (FluidSim.compute, FluidMaths3D.hlsl, FluidSim2D.compute, etc.) and classes such as FluidSim.cs and FluidSim2D.cs. These manage the actual fluid behavior simulation.
- Rendering Pipeline:
- Helper Utilities:
- The Assets/Scripts/Helpers folder contains utilities like ComputeHelper, GPU Sort (including count sort and scan mechanisms), and Spatial Hash (with modules for both 2D and 3D). These libraries underpin both simulation and rendering processes for performance and organization.
- Demo and Scene Integration:
- The Assets/Scenes directory holds multiple Unity scene files that illustrate different simulation and rendering setups. This is where the user interacts with the simulation (selecting a demo scene like Fluid MarchingCubes or Fluid Particles) and ties together all components.
- Unity Core & Project Framework:
- The standard Unity project structure (including ProjectSettings, Packages, and Assets) indicates that these systems are integrated into Unity’s game loop, messaging, and rendering pipeline.

##### Relationships and Data Flow
- User/Scene Level:
- At the highest level, Unity scenes (from Assets/Scenes) are the entry points. They instantiate and drive the simulation and rendering components.
- Simulation Flow:
- Spawner components (e.g., Spawner2D.cs, Spawner3D.cs) initiate the fluid simulation. The simulation engine computes fluid dynamics using compute shaders and simulation mathematics.
- Data processing modules (using GPU sorts, spatial hashing) supply optimized, preprocessed data for visualization.
- Rendering Flow:
- The rendering subsystem takes the simulation output and converts it into visual geometry or effects. Different rendering components (e.g., marching cubes for fluid surfaces, screen space shaders for particle thickness and depth smoothing, raymarching for volumetric effects) process this data.
- Helper Interaction:
- Helper utilities act as shared libraries used by both the simulation engine and the rendering pipeline to optimize processing, manage data structures, and perform GPU computations.
- Integration:

##### Architectural Patterns
- Modular Design:
- Data-Driven & Compute-Intensive:
- With multiple compute shader integrations, it is important to show how compute tasks (like sorting and spatial hashing) support both simulation and rendering.
- Integration with Unity:
- That the entire system is integrated into Unity’s architecture – scenes set up the testing environments that instantiate simulation and rendering components, linking them via Unity’s MonoBehaviour scripts.

##### Final Advice
- Component is labeled with its corresponding folder or script names where applicable, making it easier to trace in the directory structure.
- Directional data flows so that it’s evident how an event starting in a scene cascades into simulation updates and finally into rendered output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UA("Unity Application"):::unity

    subgraph "Scene Controller"
        SC("Demo & Scene Integration"):::scene
    end

    subgraph "Simulation Engine"
        direction TB
        SE3("Fluid Simulation Engine (3D)"):::simulation
        CS3("Compute Shaders & Fluid Math (3D)"):::compute
        SE2("Fluid Simulation Engine (2D)"):::simulation
        CS2("Compute Shaders & Fluid Math (2D)"):::compute
        SE3 -->|"uses"| CS3
        SE2 -->|"uses"| CS2
    end

    subgraph "Rendering Pipeline"
        direction TB
        RP_MC("Rendering Pipeline - Marching Cubes"):::rendering
        RP_RM("Rendering Pipeline - Raymarching"):::rendering
        RP_PT("Rendering Pipeline - Particles"):::rendering
        RP_SS("Rendering Pipeline - ScreenSpaceEffects"):::rendering
        RP_F("Rendering Pipeline - Foam"):::rendering
    end

    subgraph "Helper Utilities"
        direction TB
        HCH("Helper Utilities - Compute Helper"):::helper
        HGS("Helper Utilities - GPU Sorting"):::helper
        HSH("Helper Utilities - Spatial Hashing"):::helper
    end

    %% Data Flow Connections
    UA --> SC
    SC -->|"initializes"| SE3
    SC -->|"initializes"| SE2
    SE3 -->|"simulationData"| RP_MC
    SE3 -->|"simulationData"| RP_RM
    SE3 -->|"simulationData"| RP_PT
    SE3 -->|"simulationData"| RP_SS
    SE3 -->|"simulationData"| RP_F
    SE2 -->|"simulationData"| RP_MC
    SE2 -->|"simulationData"| RP_RM
    SE2 -->|"simulationData"| RP_PT
    SE2 -->|"simulationData"| RP_SS
    SE2 -->|"simulationData"| RP_F

    %% Bidirectional interactions with Helper Utilities
    HCH ---|"supports"| SE3
    HCH ---|"supports"| SE2
    HCH ---|"supports"| RP_MC
    HCH ---|"supports"| RP_RM
    HCH ---|"supports"| RP_PT
    HCH ---|"supports"| RP_SS
    HCH ---|"supports"| RP_F

    HGS ---|"optimizes"| SE3
    HGS ---|"optimizes"| SE2
    HGS ---|"optimizes"| RP_MC
    HGS ---|"optimizes"| RP_RM
    HGS ---|"optimizes"| RP_PT
    HGS ---|"optimizes"| RP_SS
    HGS ---|"optimizes"| RP_F

    HSH ---|"aids"| SE3
    HSH ---|"aids"| SE2
    HSH ---|"aids"| RP_MC
    HSH ---|"aids"| RP_RM
    HSH ---|"aids"| RP_PT
    HSH ---|"aids"| RP_SS
    HSH ---|"aids"| RP_F

    %% Styling Classes
    classDef unity fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef scene fill:#aed6f1,stroke:#5dade2,stroke-width:2px;
    classDef simulation fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef compute fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef rendering fill:#d4efdf,stroke:#27ae60,stroke-width:2px;
    classDef helper fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;

    %% Click Events
    click SE3 "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Simulation"
    click SE2 "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Sim2D"
    click CS3 "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Simulation/Compute"
    click CS2 "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Sim2D/Compute"
    click RP_MC "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Rendering/Marching Cubes"
    click RP_RM "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Rendering/Raymarch"
    click RP_PT "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Rendering/Particles"
    click RP_SS "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Rendering/ScreenSpace"
    click RP_F "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Rendering/Foam"
    click HCH "https://github.com/seblague/fluid-sim/blob/main/Assets/Scripts/Helpers/ComputeHelper.cs"
    click HGS "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Helpers/GPU Sort"
    click HSH "https://github.com/seblague/fluid-sim/tree/main/Assets/Scripts/Helpers/SpatialHash"
    click SC "https://github.com/seblague/fluid-sim/tree/main/Assets/Scenes"
```
