# splashdust/bevy_voxel_world architecture

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

- Interactive diagram: https://gitdiagram.com/splashdust/bevy_voxel_world
- Repository: https://github.com/splashdust/bevy_voxel_world

## Overview

For `bevy_voxel_world`, you’re diagramming a Bevy‐plugin that provides a multithreaded ECS‐based voxel terrain system. Below is a step‐by‐step guide to capture its essential architecture:

##### Main Components
- **Bevy Engine Core**
- App Builder & Scheduler (Stages: Update, PostUpdate, Render)
- **VoxelWorldPlugin**
- Registers resources, systems, and camera component (`VoxelWorldCamera<T>`)
- **Configuration (VoxelWorldConfig trait)**
- User‐supplied type (e.g. `MyWorld`)
- Defines spawning distance, texture mapping, meshing callback, etc.
- **Resources**
- `VoxelWorld<T>` – central API for `get_voxel`, `set_voxel`, `raycast`
- `ChunkMap` – tracks active chunk coordinates
- `MeshCache` – caches generated meshes per chunk signature
- **Systems**
- Chunk Spawner / Despawner (based on camera position & spawning distance)
- Meshing Enqueue System (packages chunk data & sends to thread pool)
- Meshing Completion System (receives `Mesh`, inserts into chunk entity)
- Raycast & Voxel Access Systems (process input, emit events)
- DebugDraw System (optional visualization overlays)
- **Meshing Pipeline**
- Task Pool (Bevy’s task pool)
- `block-mesh-rs` (simple algorithm) invoked in worker threads
- **GPU & Shaders**
- WGSL shaders (`voxel_texture.wgsl`, `custom_material.wgsl`)
- 2D texture array for materials

##### Relationships & Data Flow
- **App Builder → VoxelWorldPlugin**: plugin hooks into Bevy schedule.
- **Camera Move → Chunk Spawner**: updates `ChunkMap` resource.
- **ChunkMap Read + VoxelWorld.get (procedural + HashMap)** → produces raw voxel array.
- **Meshing Enqueue System → Task Pool**: hands off array + `texture_index_mapper`.
- **Worker Thread → block-mesh-rs**: generates a `Mesh` and optional bundle.
- **Meshing Completion System (main thread)**: retrieves mesh, updates `MeshCache`, inserts Mesh + Material into chunk Entity.
- **Bevy Renderer**: draws chunk Entities with Mesh + WGSL Material.
- **User Systems (with `VoxelWorld<T>`)**: call `set_voxel` / `get_voxel` / `raycast`, enqueue remeshing.

##### Architectural Patterns & Design Principles
- **ECS Architecture**: data (components), behavior (systems), orchestration (schedule).
- **Plugin Pattern**: encapsulates feature set, registers into host engine.
- **Trait‐based DI**: `VoxelWorldConfig` for inversion of control & multiple worlds.
- **Multithreading**: nonblocking meshing in task pool.
- **Caching**: reuse meshes via `MeshCache`, cache procedural data per spawned chunk.

##### Essential Elements
- **Notes** or callouts at extension/hook points where user code integrates.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bevy Engine Core
    subgraph "Bevy Engine Core"
        AppBuilderScheduler["App Builder & Scheduler"]:::core
    end

    %% Plugin & Configuration
    subgraph "Plugin & Config"
        VoxelWorldPlugin["VoxelWorldPlugin"]:::plugin
        VoxelWorldConfig["VoxelWorldConfig Trait"]:::plugin
    end

    %% Resources
    subgraph "Resources"
        VoxelWorld["VoxelWorld<T>"]:::resource
        ChunkMap["ChunkMap"]:::resource
        MeshCache["MeshCache"]:::resource
        ChunkEntity["Chunk Entity"]:::resource
    end

    %% Systems
    subgraph "Systems"
        ChunkSpawnerSystem["Chunk Spawner/Despawner"]:::system
        MeshingEnqueueSystem["Meshing Enqueue System"]:::system
        MeshingCompletionSystem["Meshing Completion System"]:::system
        RaycastSystem["Raycast & Voxel Access System"]:::system
        DebugDrawSystem["DebugDraw System"]:::system
    end

    %% External / Pipeline
    subgraph "External Libraries & GPU"
        Camera["Camera Movement"]:::external
        MeshingPipeline["Task Pool & block-mesh-rs"]:::external
        WGSL1["voxel_texture.wgsl"]:::external
        WGSL2["custom_material.wgsl"]:::external
        Renderer["Bevy Renderer"]:::external
    end

    %% Connections
    AppBuilderScheduler -->|"add_plugin(VoxelWorldPlugin)"| VoxelWorldPlugin
    VoxelWorldPlugin -->|"uses config"| VoxelWorldConfig
    VoxelWorldPlugin -->|"registers resource"| VoxelWorld
    VoxelWorldPlugin -->|"registers resource"| ChunkMap
    VoxelWorldPlugin -->|"registers resource"| MeshCache
    VoxelWorldPlugin -->|"registers system"| ChunkSpawnerSystem
    VoxelWorldPlugin -->|"registers system"| MeshingEnqueueSystem
    VoxelWorldPlugin -->|"registers system"| MeshingCompletionSystem
    VoxelWorldPlugin -->|"registers system"| RaycastSystem
    VoxelWorldPlugin -->|"registers system"| DebugDrawSystem

    Camera -->|"camera moved"| ChunkSpawnerSystem
    ChunkSpawnerSystem -->|"update chunk coords"| ChunkMap
    ChunkMap -->|"get_voxel() layers"| VoxelWorld
    VoxelWorld -->|"raw voxel array"| MeshingEnqueueSystem
    MeshingEnqueueSystem -->|"enqueue chunk for meshing"| MeshingPipeline
    MeshingPipeline -->|"generate Mesh"| MeshingCompletionSystem
    MeshingCompletionSystem -->|"insert mesh & material"| ChunkEntity
    MeshingCompletionSystem -->|"update cache"| MeshCache
    ChunkEntity -->|"render with mesh & material"| Renderer
    WGSL1 --- Renderer
    WGSL2 --- Renderer
    RaycastSystem -->|"raycast events"| VoxelWorld

    %% Click Events
    click AppBuilderScheduler "https://github.com/splashdust/bevy_voxel_world/blob/main/src/lib.rs"
    click VoxelWorldPlugin "https://github.com/splashdust/bevy_voxel_world/blob/main/src/plugin.rs"
    click VoxelWorldConfig "https://github.com/splashdust/bevy_voxel_world/blob/main/src/configuration.rs"
    click VoxelWorld "https://github.com/splashdust/bevy_voxel_world/blob/main/src/voxel_world.rs"
    click ChunkMap "https://github.com/splashdust/bevy_voxel_world/blob/main/src/chunk_map.rs"
    click MeshCache "https://github.com/splashdust/bevy_voxel_world/blob/main/src/mesh_cache.rs"
    click ChunkSpawnerSystem "https://github.com/splashdust/bevy_voxel_world/blob/main/src/chunk_map.rs"
    click MeshingEnqueueSystem "https://github.com/splashdust/bevy_voxel_world/blob/main/src/meshing.rs"
    click MeshingCompletionSystem "https://github.com/splashdust/bevy_voxel_world/blob/main/src/meshing.rs"
    click RaycastSystem "https://github.com/splashdust/bevy_voxel_world/blob/main/src/voxel_traversal.rs"
    click DebugDrawSystem "https://github.com/splashdust/bevy_voxel_world/blob/main/src/debug_draw.rs"
    click MeshingPipeline "https://github.com/splashdust/bevy_voxel_world/blob/main/src/meshing.rs"
    click WGSL1 "https://github.com/splashdust/bevy_voxel_world/blob/main/src/shaders/voxel_texture.wgsl"
    click WGSL2 "https://github.com/splashdust/bevy_voxel_world/blob/main/assets/custom_material.wgsl"
    click ChunkEntity "https://github.com/splashdust/bevy_voxel_world/blob/main/src/chunk.rs"

    %% Styles
    classDef core fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef plugin fill:#A9DFBF,stroke:#333,stroke-width:1px
    classDef resource fill:#F5CBA7,stroke:#333,stroke-width:1px
    classDef system fill:#D2B4DE,stroke:#333,stroke-width:1px
    classDef external fill:#CACFD2,stroke:#333,stroke-width:1px
```
