How splashdust/bevy_voxel_world works
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.