1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
//! Greedy mesh generation for voxel chunks with LOD and neighbor-aware seam culling.
//!
//! # Greedy meshing
//!
//! Naive voxel renderers emit one quad per visible face, producing O(n³) geometry
//! even for flat surfaces. Greedy meshing collapses adjacent coplanar faces of the
//! same voxel type into a single merged quad, reducing geometry by an order of
//! magnitude for typical terrain. The algorithm processes each of the six cardinal
//! directions independently: for every slice perpendicular to the current axis it
//! builds a 2-D visibility mask, then scans the mask left-to-right / top-to-bottom
//! extending each run into the largest rectangle of identical voxels before emitting
//! a single quad and clearing the merged region.
//!
//! # Entry points
//!
//! Two public meshing functions are provided:
//!
//! - [`generate_chunk_mesh`] — standalone meshing. Border faces that exit the
//! chunk boundary are always emitted as visible, which leaves gaps between
//! adjacent loaded chunks until they are meshed independently.
//! - [`generate_chunk_mesh_with_neighbors`] — seam-free meshing. Border faces are
//! checked against the corresponding face of each adjacent chunk via
//! [`ChunkNeighbors`]. A face is culled when the neighboring voxel is solid,
//! eliminating single-voxel cracks at chunk boundaries.
//!
//! Prefer [`generate_chunk_mesh_with_neighbors`] for in-world rendering.
//! Use [`generate_chunk_mesh`] for isolated previews or when neighbor data is
//! unavailable.
//!
//! # Level of detail (LOD)
//!
//! The `step` parameter controls the LOD resolution. A step of `1` samples every
//! voxel at full detail. A step of `2` groups each `2×2×2` block into a single
//! super-voxel (half resolution), halving triangle counts for distant chunks.
//! [`lod::compute_lod`] maps viewer distance to a level; [`lod::lod_to_step`]
//! converts a level to the step value to pass here.
//!
//! | LOD level | Step | Distance threshold |
//! |-----------|------|------------------------|
//! | `0` | `1` | < 200 world units |
//! | `1` | `2` | ≥ 200 world units |
//!
//! [`lod::compute_lod_with_hysteresis`] adds a ±5-unit hysteresis band around the
//! threshold to prevent rapid LOD oscillation as the viewer moves along the boundary.
//!
//! # Output mesh attributes
//!
//! Every mesh produced by this module contains:
//!
//! | Attribute | Type | Description |
//! |-------------------------|---------------|------------------------------------|
//! | `ATTRIBUTE_POSITION` | `Float32x3` | Vertex positions in chunk-local space |
//! | `ATTRIBUTE_NORMAL` | `Float32x3` | Face normals (one of six unit axes) |
//! | `ATTRIBUTE_UV_0` | `Float32x2` | UVs scaled by voxel count for tiling |
//! | `ATTRIBUTE_COLOR` | `Float32x4` | Per-vertex color from [`VoxelType::color`] |
//! | Indices | `U32` | Triangle list with CCW winding |
//!
//! [`MeshPlugin<V>`] wires the mesh generation, LOD update, and chunk despawn
//! systems into a Bevy app.
pub use ;
pub use generate_chunk_mesh_with_neighbors;
pub use ;
use *;
use crateCHUNK_SIZE;
use crateGeneratorSystems;
use crateVoxelType;
// ─── MeshPlugin ───────────────────────────────────────────────────────────────
/// Bevy [`Plugin`] that registers the mesh generation, LOD update, and chunk
/// despawn systems for a specific voxel type `V`.
///
/// Add this plugin after [`crate::world::WorldPlugin`] and
/// [`crate::generator::GeneratorPlugin`]. It registers three systems in the
/// [`Update`] schedule:
///
/// - [`lod_update_system`] — recomputes LOD levels every frame and emits
/// [`crate::world::ChunkModified`] when a level changes.
/// - [`chunk_mesh_system`] — runs after [`crate::generator::GeneratorSystems`];
/// responds to [`crate::world::ChunkModified`] by (re)building chunk meshes.
/// - [`chunk_despawn_system`] — responds to [`crate::world::ChunkUnloadRequest`]
/// by optionally saving to disk and despawning the entity.
///
/// # Examples
///
/// ```rust,no_run
/// use bevy::prelude::*;
/// use voxel_framework::{VoxelPlugin, generator::GeneratorPlugin, mesh::MeshPlugin, voxel::DefaultVoxel};
///
/// App::new()
/// .add_plugins(DefaultPlugins)
/// .add_plugins(VoxelPlugin::<DefaultVoxel>::new())
/// .add_plugins(GeneratorPlugin::<DefaultVoxel>::new())
/// .add_plugins(MeshPlugin::<DefaultVoxel>::new())
/// .run();
/// ```
/// Border voxel data from the six cardinal neighbors of a chunk, used for
/// seam-free meshing with [`generate_chunk_mesh_with_neighbors`].
///
/// Each slot holds a flat `CHUNK_SIZE × CHUNK_SIZE` array containing the
/// outermost face of the adjacent chunk that abuts the current chunk on that
/// side. The array is obtained from `Chunk::border_slice` on the neighbor.
///
/// The face index convention matches `FACE_DIRS`:
///
/// | Index | Direction | Neighbor face stored |
/// |-------|-----------|-------------------------------|
/// | `0` | `+Y` | bottom face of the chunk above |
/// | `1` | `-Y` | top face of the chunk below |
/// | `2` | `+X` | left face of the chunk to the right |
/// | `3` | `-X` | right face of the chunk to the left |
/// | `4` | `+Z` | back face of the chunk in front |
/// | `5` | `-Z` | front face of the chunk behind |
///
/// A slot set to `None` means the neighbor is not loaded; the border face is
/// then treated as open air and the face is emitted unconditionally.