# zylann/godot_voxel architecture

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

- Interactive diagram: https://gitdiagram.com/zylann/godot_voxel
- Repository: https://github.com/zylann/godot_voxel

## Overview

##### Major Components and Their Roles
- Voxel Engine Core: Central runtime logic (see directories like engine/voxel_engine.cpp, engine/voxel_engine_gd.cpp, and engine/voxel_engine_updater.cpp). This is the heart of voxel processing.
- Voxel Data Storage and Streaming: Components that handle voxel data management (storage/ and streams/ directories, including voxel_buffer, voxel_data, region files, SQLite streams, etc.).
- Voxel Generators: Components responsible for creating voxel data procedurally (generators/ directory with subfolders for simple algorithms, graph-based generators, and multipass generators).
- Voxel Meshers: Responsible for converting voxel data into meshes, both blocky and smooth (meshers/ directory subdivided into blocky, cubes, and transvoxel approaches).
- Voxel Modifiers: Modules that alter voxel data (modifiers/, with further support for Godot integration).
- Editor Integration and Tools: Modules that add custom editor features and debugging tools (editor/ directory, including graph editors, library inspectors, instance modules, and custom dialogs).
- Shader Management: Shader scripts and shader generation for rendering details (shaders/ directory, including development shader templates and production shader code).
- Third-party Dependencies: Libraries such as FastNoise, Meshoptimizer, lz4, and SQLite are included to enhance noise generation, mesh optimization, and data persistence.

##### Relationships and Data Flow
- At the “top” you have Godot itself interfacing with the Voxel Tools via GDExtension.
- The Voxel Engine Core communicates with the Voxel Generators to create terrain data. Data flows from generators into the storage/streams layers, where voxel data is buffered, saved/loaded, and possibly streamed.
- The Meshers then take this voxel data to generate chunked meshes, which are then passed to the rendering pipeline (supported by shaders).
- Voxel Modifiers and the Voxel Graph system allow further dynamic modifications to the voxel data at runtime.
- Editor Components facilitate design-time tweaking, visualization, and debugging. They connect to most of the runtime components (engine, generators, meshers) and also offer enhancements like inspector plugins, node dialogs, and custom Godot editor windows.

##### Architectural Patterns and Technologies
- Modular design and separation of concerns: Each folder (engine, generators, meshers, modifiers, and streams) represents a distinct module/component.
- Integration with Godot via GDExtension: Highlight the two-way interface between the native C++ modules and Godot’s scripting layer (exposed via project/addons and project/voxel.gdextension files).
- Use of third-party libraries, such as FastNoise (for procedural generation) and Meshoptimizer (for mesh simplification and performance), which play key roles in generating and processing data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    GodotEngine["Godot Engine"]:::godot
    VoxelGTExt["Voxel Tools GDExtension"]:::engine
    EngineCore["Voxel Engine Core"]:::engine

    subgraph "Voxel Generators"
        VGMain["Voxel Generators"]:::generators
        SG["Simple Generators"]:::generators
        GG["Graph-based Generators"]:::generators
        MG["Multipass Generators"]:::generators
        VGMain --> SG
        VGMain --> GG
        VGMain --> MG
    end

    subgraph "Data Storage and Streaming"
        Storage["Voxel Storage"]:::storage
        Streaming["Voxel Streaming"]:::storage
        Storage -->|"buffered"| Streaming
    end

    subgraph "Voxel Meshers"
        MeshersMain["Voxel Meshers"]:::meshers
        BM["Blocky Mesher"]:::meshers
        CM["Cubes Mesher"]:::meshers
        TM["Transvoxel Mesher"]:::meshers
        MeshersMain --> BM
        MeshersMain --> CM
        MeshersMain --> TM
    end

    Modifiers["Voxel Modifiers"]:::modifiers
    Editor["Editor Integration & Tools"]:::editor
    Shaders["Shader Management"]:::shaders
    ThirdParty["Third-party Dependencies"]:::thirdparty

    GodotEngine -->|"viaGDExtension"| VoxelGTExt
    VoxelGTExt --> EngineCore
    EngineCore -->|"proceduralGen"| VGMain
    EngineCore -->|"dataStorage"| Storage
    EngineCore --> Modifiers
    Streaming -->|"meshingInput"| MeshersMain
    MeshersMain --> Shaders

    Editor --- EngineCore
    Editor --- VGMain
    Editor --- MeshersMain

    ThirdParty -.-> VGMain
    ThirdParty -.-> MeshersMain
    ThirdParty -.-> Storage

    %% Click Events for Voxel Engine Core
    click EngineCore "https://github.com/zylann/godot_voxel/blob/master/engine/voxel_engine.cpp"
    click EngineCore "https://github.com/zylann/godot_voxel/blob/master/engine/voxel_engine_gd.cpp"
    click EngineCore "https://github.com/zylann/godot_voxel/blob/master/engine/voxel_engine_updater.cpp"

    %% Click Events for Data Storage and Streaming
    click Storage "https://github.com/zylann/godot_voxel/blob/master/storage/voxel_buffer.cpp"
    click Storage "https://github.com/zylann/godot_voxel/blob/master/storage/voxel_data.cpp"
    click Streaming "https://github.com/zylann/godot_voxel/blob/master/streams/voxel_stream.cpp"
    click Streaming "https://github.com/zylann/godot_voxel/blob/master/streams/voxel_stream_memory.cpp"

    %% Click Events for Voxel Generators
    click VGMain "https://github.com/zylann/godot_voxel/tree/master/generators/"
    click SG "https://github.com/zylann/godot_voxel/tree/master/generators/simple"
    click GG "https://github.com/zylann/godot_voxel/tree/master/generators/graph"
    click MG "https://github.com/zylann/godot_voxel/tree/master/generators/multipass"

    %% Click Events for Voxel Meshers
    click MeshersMain "https://github.com/zylann/godot_voxel/tree/master/meshers/"
    click BM "https://github.com/zylann/godot_voxel/tree/master/meshers/blocky"
    click CM "https://github.com/zylann/godot_voxel/tree/master/meshers/cubes"
    click TM "https://github.com/zylann/godot_voxel/tree/master/meshers/transvoxel"

    %% Click Events for Voxel Modifiers
    click Modifiers "https://github.com/zylann/godot_voxel/tree/master/modifiers/"
    click Modifiers "https://github.com/zylann/godot_voxel/tree/master/modifiers/godot"

    %% Click Events for Editor Integration
    click Editor "https://github.com/zylann/godot_voxel/tree/master/editor/"
    click Editor "https://github.com/zylann/godot_voxel/tree/master/project/addons/zylann.voxel/editor"

    %% Click Event for Shader Management
    click Shaders "https://github.com/zylann/godot_voxel/tree/master/shaders/"

    %% Click Event for Third-party Dependencies
    click ThirdParty "https://github.com/zylann/godot_voxel/tree/master/thirdparty/"

    %% Styles
    classDef godot fill:#c0eaff,stroke:#333,stroke-width:2px;
    classDef engine fill:#a9d0f5,stroke:#333,stroke-width:2px;
    classDef storage fill:#a1d490,stroke:#333,stroke-width:2px;
    classDef generators fill:#f5c9a9,stroke:#333,stroke-width:2px;
    classDef meshers fill:#d1a9f5,stroke:#333,stroke-width:2px;
    classDef modifiers fill:#f5a9a9,stroke:#333,stroke-width:2px;
    classDef editor fill:#a9f5e1,stroke:#333,stroke-width:2px;
    classDef shaders fill:#f3f5a9,stroke:#333,stroke-width:2px;
    classDef thirdparty fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
