# nugget8/three.js-ocean-scene architecture

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

- Interactive diagram: https://gitdiagram.com/nugget8/three.js-ocean-scene
- Repository: https://github.com/nugget8/three.js-ocean-scene

## Overview

##### Project Type & Purpose
- This is a specialized browser-based graphical demo built with Three.js.
- Its primary purpose is to showcase procedural skybox and ocean shaders, with an emphasis on performance for mobile devices.
- The project integrates custom shader programming, procedural generation (for stars, sea floor, etc.), and Three.js rendering as its core.

##### Key Components & Their Roles
- User Interface & Entry Point:
- The index.html serves as the entry point.
- It loads the main JavaScript (script.js) and CSS (style.css) that kick off scene rendering.
- Three.js Engine (Modules):
- The “modules/three” directory provides the Three.js library. This library is imported in the scripts to handle WebGL rendering.
- Scene Description:
- The “scene” directory contains files (e.g., Blocks.js, Ocean.js, SeaFloor.js, Skybox.js) that define the geometry and elements of the scene.
- Each file represents a distinct part of the scene such as the ocean, skybox elements, and terrain details.
- Materials & Shaders:
- The “materials” folder includes JavaScript files defining custom materials (OceanMaterial.js, SkyboxMaterial.js) which work in tandem with shader logic.
- The “shaders” folder holds multiple shader-related files (e.g., OceanShaders.js, SkyboxShader.js, UvShader.js, Settings.js) that provide the core visuals including gradients, glow effects for sun/moon, and water wave simulation.
- Scripting & Control:
- The “scripts” folder contains various modules (Control.js, Debug.js, Input.js, Scene.js, Time.js, UI.js) that handle the overall application flow, user input (including touch for mobile), debugging information, scene updating, and UI handling.
- These scripts coordinate the rendering loop, user interaction, and updates to the scene elements.
- Assets & Additional Resources:
- The “images” folder (and others like LICENSE) is used to support documentation and visual assets.
- The README and accompanying comments help explain shader techniques and procedural generation methods.

a. Core Components:
- Frontend / Browser UI: index.html & style.css.
- Rendering Engine: Three.js (modules/three).
- Scene Management: Scene files (scene folder) and application logic (scripts folder).
- Materials & Shaders: Custom materials (materials folder) and shader codes (shaders folder).
- Input & Control: Scripts managing control, input, and UI updates (Control.js, Input.js, UI.js).

b. Establish Data Flow & Interactions:
- The Browser loads the index.html, which embeds the main JavaScript (script.js) to initialize the Three.js engine.
- Three.js (from the modules subfolder) is imported into various scripts to render the scene.
- The scene management scripts (in “scene” and some “scripts” files) coordinate with shader materials and update the rendering (by linking ocean, skybox, sea floor, etc.).
- Shader files and materials “talk” to the GPU via WebGL calls (triggered by the runtime behavior in the scripts).
- Control and Input scripts process user actions and update scene parameters in real time.

c. Architectural Patterns & Technologies:
- Separation of concerns: Different directories for scene logic, shader/matieral definitions, rendering engine integration, and UI control.
- Procedural Content Generation: Usage of noise (for sea floor) and gradient-based procedural shaders (for skybox and water).
- Performance Optimizations: Mobile-targeted performance (e.g., limiting vertex count in the ocean geometry, tiling for sea floor, use of efficient materials).
- Use of modern JavaScript module imports to integrate Three.js and custom shaders.

- Components: Each major folder (e.g., “materials”, “scripts”, “scene”, “shaders”, “modules/three”) should be a node/component.
- Use Clear Labels: Label nodes such as “Browser/Frontend”, “3D Rendering Engine (Three.js)”, “Scene Objects”, “Shader Materials”, “Control & Input Handlers”.
- Detail Interaction: Annotate the data flow, such as “Imports Three.js Library”, “Sends rendering commands”, and “Processes user input”.

##### Instructing the Principal Software Engineer
- Technical stack:
- JavaScript modules & ES6 imports,
- Three.js as the rendering backbone,
- Custom shaders written in GLSL (with in-code examples in README for guidance).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Interface"
        UI_Index["index.html"]:::frontend
        UI_Style["style.css"]:::frontend
        UI_Script["script.js"]:::frontend
    end

    subgraph "Control & Scripting"
        Script_Control["Control.js"]:::script
        Script_Debug["Debug.js"]:::script
        Script_Input["Input.js"]:::script
        Script_Random["Random.js"]:::script
        Script_Scene["Scene.js"]:::script
        Script_Time["Time.js"]:::script
        Script_UI["UI.js"]:::script
    end

    subgraph "Scene Objects"
        Scene_Blocks["Blocks.js"]:::scene
        Scene_Ocean["Ocean.js"]:::scene
        Scene_SeaFloor["SeaFloor.js"]:::scene
        Scene_Skybox["Skybox.js"]:::scene
    end

    subgraph "Materials"
        Material_Ocean["OceanMaterial.js"]:::material
        Material_Skybox["SkyboxMaterial.js"]:::material
    end

    subgraph "Shaders"
        Shader_Ocean["OceanShaders.js"]:::shader
        Shader_Settings["Settings.js"]:::shader
        Shader_Skybox["SkyboxShader.js"]:::shader
        Shader_Uv["UvShader.js"]:::shader
    end

    subgraph "3D Rendering Engine"
        ThreeJS["Three.js Library"]:::engine
    end

    %% Connections from UI to Scripts
    UI_Index -->|"loads"| UI_Script
    UI_Script -->|"initializes"| Script_Scene
    Script_Control -->|"drives"| Script_Scene
    Script_Input -->|"drives"| Script_Scene
    Script_UI -->|"drives"| Script_Scene
    Script_Debug -->|"assists"| Script_Control

    %% Connections from Scripts to Scene Objects 
    Script_Scene -->|"updates"| Scene_Blocks
    Script_Scene -->|"updates"| Scene_Ocean
    Script_Scene -->|"updates"| Scene_SeaFloor
    Script_Scene -->|"updates"| Scene_Skybox

    %% Rendering relationships
    Scene_Blocks -->|"renderedBy"| ThreeJS
    Scene_Ocean -->|"renderedBy"| ThreeJS
    Scene_SeaFloor -->|"renderedBy"| ThreeJS
    Scene_Skybox -->|"renderedBy"| ThreeJS

    %% Materials and Shaders linking with Scene Objects
    Scene_Ocean -->|"applies"| Material_Ocean
    Scene_Ocean -->|"applies"| Shader_Ocean
    Scene_Skybox -->|"applies"| Material_Skybox
    Scene_Skybox -->|"applies"| Shader_Skybox

    %% Configuration of Shaders
    Script_Scene -->|"configures"| Shader_Settings
    Shader_Settings -->|"configures"| Shader_Ocean
    Shader_Settings -->|"configures"| Shader_Skybox
    Shader_Settings -->|"configures"| Shader_Uv

    %% Click Events
    click UI_Index "https://github.com/nugget8/three.js-ocean-scene/blob/main/index.html"
    click UI_Style "https://github.com/nugget8/three.js-ocean-scene/blob/main/style.css"
    click UI_Script "https://github.com/nugget8/three.js-ocean-scene/blob/main/script.js"
    click ThreeJS "https://github.com/nugget8/three.js-ocean-scene/blob/main/modules/three/build/three.module.js"
    click Scene_Blocks "https://github.com/nugget8/three.js-ocean-scene/blob/main/scene/Blocks.js"
    click Scene_Ocean "https://github.com/nugget8/three.js-ocean-scene/blob/main/scene/Ocean.js"
    click Scene_SeaFloor "https://github.com/nugget8/three.js-ocean-scene/blob/main/scene/SeaFloor.js"
    click Scene_Skybox "https://github.com/nugget8/three.js-ocean-scene/blob/main/scene/Skybox.js"
    click Material_Ocean "https://github.com/nugget8/three.js-ocean-scene/blob/main/materials/OceanMaterial.js"
    click Material_Skybox "https://github.com/nugget8/three.js-ocean-scene/blob/main/materials/SkyboxMaterial.js"
    click Shader_Ocean "https://github.com/nugget8/three.js-ocean-scene/blob/main/shaders/OceanShaders.js"
    click Shader_Settings "https://github.com/nugget8/three.js-ocean-scene/blob/main/shaders/Settings.js"
    click Shader_Skybox "https://github.com/nugget8/three.js-ocean-scene/blob/main/shaders/SkyboxShader.js"
    click Shader_Uv "https://github.com/nugget8/three.js-ocean-scene/blob/main/shaders/UvShader.js"
    click Script_Control "https://github.com/nugget8/three.js-ocean-scene/blob/main/scripts/Control.js"
    click Script_Debug "https://github.com/nugget8/three.js-ocean-scene/blob/main/scripts/Debug.js"
    click Script_Input "https://github.com/nugget8/three.js-ocean-scene/blob/main/scripts/Input.js"
    click Script_Random "https://github.com/nugget8/three.js-ocean-scene/blob/main/scripts/Random.js"
    click Script_Scene "https://github.com/nugget8/three.js-ocean-scene/blob/main/scripts/Scene.js"
    click Script_Time "https://github.com/nugget8/three.js-ocean-scene/blob/main/scripts/Time.js"
    click Script_UI "https://github.com/nugget8/three.js-ocean-scene/blob/main/scripts/UI.js"

    %% Styles
    classDef frontend fill:#a6cee3,stroke:#1f78b4,stroke-width:2px,color:#000;
    classDef script fill:#b2df8a,stroke:#33a02c,stroke-width:2px,color:#000;
    classDef scene fill:#ffcc99,stroke:#ff7f00,stroke-width:2px,color:#000;
    classDef material fill:#d9d2e9,stroke:#6a3d9a,stroke-width:2px,color:#000;
    classDef shader fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px,color:#000;
    classDef engine fill:#ccebc5,stroke:#006d2c,stroke-width:2px,color:#000;
```
