# fracali/terrain_generation_threejs architecture

> Architecture diagram of the GitHub repository fracali/terrain_generation_threejs, 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/fracali/terrain_generation_threejs
- Repository: https://github.com/fracali/terrain_generation_threejs

## Overview

##### Main Components
- Frontend / Rendering Engine: The project uses Three.js for 3D rendering. This layer is initiated in the index.html and index.js files.
- Application Core: The Application.ts file is the central entry point that sets up the scene, initializes rendering, and wires up all other components.
- Camera Handling: The Camera.ts module defines the virtual camera’s behavior including its movement along the z-axis.
- World Generation: Contained in the world folder, components like World.ts, TerrainNoise.ts, Floor.ts, and Sky.ts define how the scene is built and how the infinite terrain effect is generated.
- Lighting: The lights folder with DirLight.ts and HemiLight.ts shows that the scene’s illumination is managed with multiple light sources.
- Materials and Shaders: The terrain_mat.ts in the materials folder (and the shader files under src/shaders/sky) indicate custom shaders and material definitions, especially for the sky and terrain.
- Instancing and Objects: The objects subfolder under world contains modules (Tree.ts, TreeTrunk.ts) that represent models used for scenery; these are loaded once and then reused via the Instancing.ts utility.
- Utilities: Various helper modules (EventEmitter.ts, FPSCounter.ts, Sizes.ts, Time.ts, map.ts) provide cross-cutting functionalities like event management, performance monitoring, and handling frame/time updates.
- Assets: The assets folder contains all the external resources – textures, models (FBX/GLB), and additional resources, which are used by the application to construct the 3D environment.
- Build and Configuration: Files like package.json, tsconfig.json, vite.config.js, and related assets indicate that the project is built as a modern frontend application using TypeScript and a bundler (Vite).

##### Relationships and Interactions
- The index.html and index.js serve the static content and bootstrap the Three.js scene.
- Application.ts, as the core module, instantiates the Camera, World, Lights, Materials, and utility modules to compose the scene.
- The World module uses TerrainNoise to generate heightmaps dynamically. It then passes these values to both the geometry of the Floor and the camera position logic.
- Instancing.ts is employed to manage multiple instances of objects (like Tree and TreeTrunk) so that models are loaded once and rendered efficiently in many places.
- Shader files in src/shaders/sky provide custom rendering logic for the sky element, which is linked with Sky.ts.
- Utility modules provide services throughout the application ensuring consistent update loops and event-driven communication.
- Assets (models, textures) are loaded and mapped to corresponding scene objects, with resources arranged under the assets directory to support the rendering and visual effects.

##### Architectural Patterns and Design Principles
- Modularization: The project is segmented into clear modules (world, lights, materials, utils) that encapsulate specific concerns.
- Separation of Concerns: There is a clear distinction between different elements (e.g., visual rendering with shaders, scene management in Application.ts, and procedural terrain generation in TerrainNoise.ts).
- Efficiency through Instancing: Reusing 3D models via instancing improves rendering performance, an important architectural decision.
- Event-Driven Updates: Use of an EventEmitter and FPSCounter supports real-time updates and performance monitoring.
- Declarative Configuration: With Vite and TypeScript configuration files, the project is built using a modern frontend tooling approach.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend / Entry Point
    subgraph "Frontend / Entry Point"
        indexHTML["index.html"]:::frontend
        indexJS["index.js"]:::frontend
    end

    %% Application Core
    appCore["Application Core (Application.ts)"]:::core

    %% Camera Handling
    camera["Camera (Camera.ts)"]:::camera

    %% World Generation
    subgraph "World Generation"
        worldSetup["World Setup (World.ts)"]:::world
        terrainNoise["Procedural Terrain (TerrainNoise.ts)"]:::world
        floor["Floor (Floor.ts)"]:::world
        sky["Sky Rendering (Sky.ts)"]:::world
        subgraph "Instanced Objects"
            tree["Tree (Tree.ts)"]:::world
            treeTrunk["TreeTrunk (TreeTrunk.ts)"]:::world
        end
    end

    %% Lighting
    subgraph "Lighting"
        dirLight["DirLight (DirLight.ts)"]:::lighting
        hemiLight["HemiLight (HemiLight.ts)"]:::lighting
    end

    %% Materials & Shaders
    subgraph "Materials & Shaders"
        terrainMat["Terrain Material (terrain_mat.ts)"]:::materials
        subgraph "Sky Shaders"
            skyVertex["Sky Vertex Shader (sky_vertex.glsl)"]:::materials
            skyFragment["Sky Fragment Shader (sky_fragment.glsl)"]:::materials
        end
    end

    %% Utilities
    subgraph "Utilities"
        eventEmitter["EventEmitter (EventEmitter.ts)"]:::utilities
        fpsCounter["FPSCounter (FPSCounter.ts)"]:::utilities
        instancing["Instancing (Instancing.ts)"]:::utilities
        sizes["Sizes (Sizes.ts)"]:::utilities
        time["Time (Time.ts)"]:::utilities
        mapUtil["Map (map.ts)"]:::utilities
    end

    %% Assets
    assets["Assets (assets)"]:::assets

    %% Connections from Frontend to Application Core
    indexHTML -->|"bootstraps"| appCore
    indexJS -->|"bootstraps"| appCore

    %% Application Core connections
    appCore -->|"initializes"| camera
    appCore -->|"creates"| worldSetup
    appCore -->|"configures"| dirLight
    appCore -->|"configures"| hemiLight
    appCore -->|"applies"| terrainMat
    appCore -->|"manages"| eventEmitter
    appCore -->|"monitors"| fpsCounter
    appCore -->|"utilizes"| instancing
    appCore -->|"controls"| sizes
    appCore -->|"tracks"| time
    appCore -->|"maps"| mapUtil

    %% World Generation internal connections
    worldSetup -->|"generates"| terrainNoise
    worldSetup -->|"generates"| floor
    worldSetup -->|"renders"| sky
    worldSetup -->|"places"| tree
    worldSetup -->|"places"| treeTrunk

    %% Instancing support for objects
    instancing -->|"manages"| tree
    instancing -->|"manages"| treeTrunk

    %% Sky Rendering uses custom shaders
    sky -->|"uses"| skyVertex
    sky -->|"uses"| skyFragment

    %% Assets feed into World and Materials
    assets -->|"supplies"| worldSetup
    assets -->|"supplies"| terrainMat

    %% Styling definitions
    classDef frontend fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef core fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef camera fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef world fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef lighting fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef materials fill:#ffff99,stroke:#d4ac0d,stroke-width:2px;
    classDef utilities fill:#ccebc5,stroke:#31a354,stroke-width:2px;
    classDef assets fill:#fbb4ae,stroke:#e41a1c,stroke-width:2px;

    %% Click Events
    click indexHTML "https://github.com/fracali/terrain_generation_threejs/blob/main/src/index.html"
    click indexJS "https://github.com/fracali/terrain_generation_threejs/blob/main/src/index.js"
    click appCore "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/Application.ts"
    click camera "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/Camera.ts"
    click worldSetup "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/world/World.ts"
    click terrainNoise "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/world/TerrainNoise.ts"
    click floor "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/world/Floor.ts"
    click sky "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/world/Sky.ts"
    click tree "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/world/objects/Tree.ts"
    click treeTrunk "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/world/objects/TreeTrunk.ts"
    click dirLight "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/lights/DirLight.ts"
    click hemiLight "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/lights/HemiLight.ts"
    click terrainMat "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/materials/terrain_mat.ts"
    click skyVertex "https://github.com/fracali/terrain_generation_threejs/blob/main/src/shaders/sky/sky_vertex.glsl"
    click skyFragment "https://github.com/fracali/terrain_generation_threejs/blob/main/src/shaders/sky/sky_fragment.glsl"
    click eventEmitter "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/utils/EventEmitter.ts"
    click fpsCounter "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/utils/FPSCounter.ts"
    click instancing "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/utils/Instancing.ts"
    click sizes "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/utils/Sizes.ts"
    click time "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/utils/Time.ts"
    click mapUtil "https://github.com/fracali/terrain_generation_threejs/blob/main/src/js/utils/map.ts"
    click assets "https://github.com/fracali/terrain_generation_threejs/tree/main/src/assets"
```
