voxel-framework 0.10.0

A reusable voxel engine framework built on Bevy
Documentation
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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
//! Shared material and rendering components for voxel chunks.
//!
//! Provides two rendering paths for voxel chunks:
//!
//! 1. **Texture array path** (opt-in) — when [`ChunkTextureArray`] is inserted
//!    as a resource before the plugin initialises, chunks are rendered with
//!    [`ChunkMaterial`], a custom PBR material that samples a `texture_2d_array`.
//!    The embedded WGSL shader applies per-vertex AO and simple diffuse lighting.
//!
//! 2. **Fallback path** (default) — when [`ChunkTextureArray`] is absent, chunks
//!    use a shared [`bevy::pbr::StandardMaterial`] with vertex colors. This path
//!    requires no texture assets and is compatible with all `VoxelType` palettes.

use bevy::asset::RenderAssetUsages;
use bevy::math::bounding::Aabb3d;
use bevy::mesh::MeshVertexBufferLayoutRef;
use bevy::pbr::{Material, MaterialPipeline, MaterialPipelineKey, MeshPipelineKey};
use bevy::prelude::*;
use bevy::render::alpha::AlphaMode;
use bevy::render::render_resource::{
    AsBindGroup, RenderPipelineDescriptor, SpecializedMeshPipelineError,
};
use bevy::shader::ShaderRef;

use crate::mesh::ATTRIBUTE_TEXTURE_LAYER;

// ─── ChunkMaterial (texture array path) ───────────────────────────────────────

/// Custom chunk material that samples a GPU `texture_2d_array`.
///
/// Register this via [`ChunkTextureArray`] before adding [`super::RenderPlugin`].
/// The embedded WGSL shader multiplies the sampled texture color by the
/// per-vertex AO value (stored in `ATTRIBUTE_COLOR`) and applies simple diffuse
/// lighting with a fixed sun direction.
///
/// # Shader bindings
///
/// | Binding | Name              | Type                  |
/// |---------|-------------------|-----------------------|
/// | 0       | `texture_array`   | `texture_2d_array<f32>` |
/// | 1       | `texture_sampler` | `sampler`             |
///
/// # Vertex attributes
///
/// | Location | Attribute              | Type       |
/// |----------|------------------------|------------|
/// | 0        | `ATTRIBUTE_POSITION`   | `Float32x3` |
/// | 1        | `ATTRIBUTE_NORMAL`     | `Float32x3` |
/// | 2        | `ATTRIBUTE_UV_0`       | `Float32x2` |
/// | 3        | `ATTRIBUTE_COLOR`      | `Float32x4` |
/// | 4        | `ATTRIBUTE_TEXTURE_LAYER` | `Uint32` |
#[derive(Asset, TypePath, AsBindGroup, Clone)]
pub struct ChunkMaterial {
    /// Handle to the assembled texture array image (all voxel layers stacked).
    #[texture(0, sample_type = "float", dimension = "2d_array")]
    #[sampler(1)]
    pub texture_array: Handle<Image>,
}

impl Material for ChunkMaterial {
    fn vertex_shader() -> ShaderRef {
        "embedded://voxel_framework/render/chunk.wgsl".into()
    }

    fn fragment_shader() -> ShaderRef {
        "embedded://voxel_framework/render/chunk.wgsl".into()
    }

    fn specialize(
        _pipeline: &MaterialPipeline,
        descriptor: &mut RenderPipelineDescriptor,
        layout: &MeshVertexBufferLayoutRef,
        key: MaterialPipelineKey<Self>,
    ) -> Result<(), SpecializedMeshPipelineError> {
        // The prepass pipelines (depth, normal, motion-vector) use Bevy's
        // built-in prepass vertex shader, which has its own vertex attribute
        // expectations. Don't override the vertex buffer layout for them —
        // Bevy sets it up correctly. Our custom layout is only needed for the
        // main pass where chunk.wgsl's vertex function runs.
        let is_prepass = key.mesh_key.intersects(
            MeshPipelineKey::DEPTH_PREPASS
                | MeshPipelineKey::NORMAL_PREPASS
                | MeshPipelineKey::MOTION_VECTOR_PREPASS,
        );
        if is_prepass {
            return Ok(());
        }

        let vertex_layout = layout.0.get_layout(&[
            Mesh::ATTRIBUTE_POSITION.at_shader_location(0),
            Mesh::ATTRIBUTE_NORMAL.at_shader_location(1),
            Mesh::ATTRIBUTE_UV_0.at_shader_location(2),
            Mesh::ATTRIBUTE_COLOR.at_shader_location(3),
            ATTRIBUTE_TEXTURE_LAYER.at_shader_location(4),
        ])?;
        descriptor.vertex.buffers = vec![vertex_layout];
        Ok(())
    }
}

// ─── ChunkTextureArray ────────────────────────────────────────────────────────

/// Optional resource that opts chunks into the texture-array rendering path.
///
/// Insert this resource before adding [`super::RenderPlugin`]. The plugin reads
/// it during startup to create a [`ChunkMaterial`] handle that is shared across
/// all chunk entities.
///
/// When this resource is absent the plugin falls back to [`bevy::pbr::StandardMaterial`]
/// with vertex colors, which requires no texture setup.
///
/// # Example
///
/// ```rust,no_run
/// use bevy::prelude::*;
/// use voxel_framework::render::ChunkTextureArray;
///
/// let mut app = App::new();
/// app.add_plugins(MinimalPlugins).init_asset::<Image>();
/// let my_texture_array_handle: Handle<Image> = Handle::default();
///
/// // In your Bevy app setup, before adding VoxelCorePlugin / VoxelPlugin:
/// app.insert_resource(ChunkTextureArray {
///     handle: my_texture_array_handle,
/// });
/// ```
#[derive(Resource)]
pub struct ChunkTextureArray {
    /// Handle to a `texture_2d_array` [`Image`] containing one layer per voxel type.
    pub handle: Handle<Image>,
}

// ─── ChunkMaterialHandle ─────────────────────────────────────────────────────

/// Internal resource that tracks which material handle all chunk entities share.
///
/// Populated by [`setup_chunk_material`] during [`bevy::prelude::Startup`].
/// The `systems.rs` mesh system reads this to attach materials to chunk entities.
#[derive(Resource, Default)]
pub struct ChunkMaterialHandle {
    /// Handle to the shared `StandardMaterial` (fallback path). `None` until setup runs.
    pub standard: Option<Handle<StandardMaterial>>,
    /// Handle to the shared `ChunkMaterial` (texture-array path). `None` unless
    /// [`ChunkTextureArray`] was inserted before plugin setup.
    pub custom: Option<Handle<ChunkMaterial>>,
}

// ─── ChunkMaterialConfig ─────────────────────────────────────────────────────

/// Configuration for the fallback `StandardMaterial` chunk material.
///
/// Insert this resource before adding `RenderPlugin` to customise fallback
/// material properties. If absent, sensible defaults are used (white base color,
/// high roughness, no metallic, opaque rendering).
///
/// This resource has no effect when [`ChunkTextureArray`] is present because
/// the texture-array path uses the embedded WGSL shader.
#[derive(Resource, Clone, Debug)]
pub struct ChunkMaterialConfig {
    /// Base color of the material. Vertex colors are multiplied by this value.
    pub base_color: Color,
    /// Alpha policy shared by all fallback chunks. Defaults to opaque so terrain
    /// writes depth. Select `AlphaMode::Blend` explicitly for translucent palettes;
    /// this does not split opaque/translucent geometry or sort individual faces.
    pub alpha_mode: AlphaMode,
    /// Perceptual roughness of the PBR material (0.0 = smooth, 1.0 = rough).
    pub perceptual_roughness: f32,
    /// Metallic factor (0.0 = dielectric, 1.0 = metal).
    pub metallic: f32,
    /// Reflectance at normal incidence for dielectric materials.
    pub reflectance: f32,
}

impl Default for ChunkMaterialConfig {
    fn default() -> Self {
        Self {
            base_color: Color::WHITE,
            alpha_mode: AlphaMode::Opaque,
            perceptual_roughness: 0.9,
            metallic: 0.0,
            reflectance: 0.1,
        }
    }
}

// ─── ChunkRendered ────────────────────────────────────────────────────────────

/// Marker component indicating a chunk entity has been set up for rendering.
///
/// Inserted alongside `Mesh3d` and `MeshMaterial3d` to prevent duplicate
/// render setup on the same entity.
#[derive(Component)]
pub struct ChunkRendered;

// ─── setup_chunk_material ────────────────────────────────────────────────────

/// Startup system that creates the shared chunk material.
///
/// If [`ChunkTextureArray`] is present, creates a [`ChunkMaterial`] backed by
/// the provided texture array. Otherwise creates a `StandardMaterial` with
/// vertex colors. The handle is stored in [`ChunkMaterialHandle`].
pub fn setup_chunk_material(
    mut standard_materials: ResMut<Assets<StandardMaterial>>,
    mut chunk_materials: ResMut<Assets<ChunkMaterial>>,
    mut handle: ResMut<ChunkMaterialHandle>,
    config: Res<ChunkMaterialConfig>,
    texture_array: Option<Res<ChunkTextureArray>>,
) {
    if let Some(tex) = texture_array {
        // Texture-array path — use the embedded WGSL shader.
        let mat = ChunkMaterial {
            texture_array: tex.handle.clone(),
        };
        handle.custom = Some(chunk_materials.add(mat));
    } else {
        // Fallback path — standard PBR material with vertex colors.
        // Opaque terrain must write depth even when every vertex has alpha 1.
        // Translucent palettes can explicitly opt into a different alpha policy.
        let material = StandardMaterial {
            base_color: config.base_color,
            perceptual_roughness: config.perceptual_roughness,
            metallic: config.metallic,
            reflectance: config.reflectance,
            alpha_mode: config.alpha_mode,
            ..default()
        };
        handle.standard = Some(standard_materials.add(material));
    }
}

// ─── chunk_aabb ──────────────────────────────────────────────────────────────

/// Creates an axis-aligned bounding box sized for a standard voxel chunk.
///
/// The AABB is centered at half the chunk extent along each axis, covering
/// the full 16x16x16 voxel region. This enables Bevy's built-in frustum
/// culling to skip off-screen chunks.
pub fn chunk_aabb() -> Aabb3d {
    use bevy::math::Vec3A;
    Aabb3d::new(Vec3A::splat(8.0), Vec3A::splat(8.0))
}

// ─── upgrade_to_texture_material ─────────────────────────────────────────────

/// Upgrades existing chunk entities from `StandardMaterial` to `ChunkMaterial`
/// once [`ChunkTextureArray`] becomes available (i.e. after async texture loading).
///
/// `setup_chunk_material` runs at `Startup` — before any textures have loaded —
/// so it always falls back to `StandardMaterial`. This system runs every `Update`
/// frame, does nothing until `ChunkTextureArray` is inserted AND
/// `ChunkMaterialHandle.custom` is still `None`, then:
///
/// 1. Creates a `ChunkMaterial` from the texture array handle.
/// 2. Stores it in `ChunkMaterialHandle.custom`.
/// 3. Replaces `MeshMaterial3d<StandardMaterial>` with `MeshMaterial3d<ChunkMaterial>`
///    on every entity that already has a [`ChunkRendered`] marker.
///
/// Because the greedy mesher always emits `ATTRIBUTE_TEXTURE_LAYER` vertices,
/// existing meshes are already compatible with `ChunkMaterial` — no remesh needed.
pub fn upgrade_to_texture_material(
    mut commands: Commands,
    mut chunk_materials: ResMut<Assets<ChunkMaterial>>,
    mut handle: ResMut<ChunkMaterialHandle>,
    texture_array: Option<Res<ChunkTextureArray>>,
    rendered_chunks: Query<Entity, (With<ChunkRendered>, With<MeshMaterial3d<StandardMaterial>>)>,
) {
    // Only act once: when ChunkTextureArray appears but we haven't upgraded yet.
    if handle.custom.is_some() {
        return;
    }
    let Some(tex) = texture_array else {
        return;
    };

    let mat = ChunkMaterial {
        texture_array: tex.handle.clone(),
    };
    let mat_handle = chunk_materials.add(mat);
    handle.custom = Some(mat_handle.clone());

    // Swap the material on every already-rendered chunk.
    for entity in &rendered_chunks {
        commands
            .entity(entity)
            .remove::<MeshMaterial3d<StandardMaterial>>()
            .insert(MeshMaterial3d(mat_handle.clone()));
    }

    eprintln!(
        "voxel texture array active — {} chunk(s) upgraded to ChunkMaterial",
        rendered_chunks.iter().count()
    );
}

// ─── build_texture_array ─────────────────────────────────────────────────────

/// Assembles N identically-sized [`Image`]s into a single GPU `texture_2d_array`.
///
/// Each input image is expected to be the same pixel dimensions and format.
/// The images are stacked in the order provided: layer 0 = `images[0]`,
/// layer 1 = `images[1]`, etc.
///
/// Returns an [`Image`] whose `texture_descriptor` is configured as a
/// `D2` texture with `depth_or_array_layers = N`, suitable for binding as a
/// `texture_2d_array` in a WGSL shader.
///
/// # Panics
///
/// Panics if `images` is empty or if images have different sizes / formats.
pub fn build_texture_array(images: &[Image]) -> Image {
    assert!(
        !images.is_empty(),
        "build_texture_array: must provide at least one image"
    );
    let first = &images[0];
    let width = first.width();
    let height = first.height();
    let format = first.texture_descriptor.format;
    let layers = images.len() as u32;

    // Validate all images have matching dimensions and format.
    for (i, img) in images.iter().enumerate() {
        assert_eq!(img.width(), width, "image {i} width mismatch");
        assert_eq!(img.height(), height, "image {i} height mismatch");
        assert_eq!(
            img.texture_descriptor.format, format,
            "image {i} format mismatch"
        );
    }

    // Concatenate raw pixel data from all layers.
    let mut combined: Vec<u8> = Vec::new();
    for img in images {
        if let Some(data) = &img.data {
            combined.extend_from_slice(data);
        }
    }

    use bevy::render::render_resource::{
        Extent3d, TextureDimension, TextureViewDescriptor, TextureViewDimension,
    };

    let size = Extent3d {
        width,
        height,
        depth_or_array_layers: layers,
    };

    let mut array_image = Image::new(
        size,
        TextureDimension::D2,
        combined,
        format,
        RenderAssetUsages::RENDER_WORLD,
    );

    // Tell Bevy/wgpu to interpret this as a 2D array texture view.
    array_image.texture_view_descriptor = Some(TextureViewDescriptor {
        label: Some("chunk_texture_array_view"),
        dimension: Some(TextureViewDimension::D2Array),
        ..Default::default()
    });

    array_image
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{
        chunk::Chunk,
        mesh::generate_chunk_mesh,
        voxel::{DefaultVoxel, VoxelType},
    };
    use bevy::mesh::VertexAttributeValues;

    fn startup(config: ChunkMaterialConfig, texture: bool) -> App {
        let mut app = App::new();
        app.init_resource::<Assets<StandardMaterial>>()
            .init_resource::<Assets<ChunkMaterial>>()
            .init_resource::<ChunkMaterialHandle>()
            .insert_resource(config)
            .add_systems(Startup, setup_chunk_material);
        if texture {
            app.insert_resource(ChunkTextureArray {
                handle: Handle::default(),
            });
        }
        app.update();
        app
    }

    #[test]
    fn fallback_terrain_is_opaque_by_default() {
        let app = startup(ChunkMaterialConfig::default(), false);
        let handles = app.world().resource::<ChunkMaterialHandle>();
        let materials = app.world().resource::<Assets<StandardMaterial>>();
        let material = materials.get(handles.standard.as_ref().unwrap()).unwrap();
        assert_eq!(material.alpha_mode, AlphaMode::Opaque);
        assert!(handles.custom.is_none());
    }

    #[test]
    fn default_palette_solids_are_opaque_and_air_has_no_geometry() {
        for step in [1, 2] {
            assert_eq!(
                generate_chunk_mesh(&Chunk::<DefaultVoxel>::new(), step).count_vertices(),
                0
            );
            for voxel in [
                DefaultVoxel::Rock,
                DefaultVoxel::IronOre,
                DefaultVoxel::SiliconCrystal,
                DefaultVoxel::RareMineral,
            ] {
                assert_eq!(voxel.color()[3], 1.0);
                let mut chunk = Chunk::new();
                chunk.set(0, 0, 0, voxel);
                let mesh = generate_chunk_mesh(&chunk, step);
                assert!(mesh.count_vertices() > 0);
                let Some(VertexAttributeValues::Float32x4(colors)) =
                    mesh.attribute(Mesh::ATTRIBUTE_COLOR)
                else {
                    panic!("expected vertex colors")
                };
                assert!(colors.iter().all(|color| color[3] == 1.0));
            }
        }
    }
    #[test]
    fn fallback_honors_explicit_alpha_and_pbr_configuration() {
        for alpha_mode in [AlphaMode::Blend, AlphaMode::Mask(0.4)] {
            let config = ChunkMaterialConfig {
                base_color: Color::srgba(0.2, 0.3, 0.4, 0.5),
                alpha_mode,
                perceptual_roughness: 0.6,
                metallic: 0.7,
                reflectance: 0.8,
            };
            let app = startup(config.clone(), false);
            let handles = app.world().resource::<ChunkMaterialHandle>();
            let materials = app.world().resource::<Assets<StandardMaterial>>();
            let material = materials.get(handles.standard.as_ref().unwrap()).unwrap();
            assert_eq!(material.alpha_mode, alpha_mode);
            assert_eq!(material.base_color, config.base_color);
            assert_eq!(material.perceptual_roughness, config.perceptual_roughness);
            assert_eq!(material.metallic, config.metallic);
            assert_eq!(material.reflectance, config.reflectance);
        }
    }

    #[test]
    fn texture_array_ignores_fallback_alpha_policy() {
        let app = startup(
            ChunkMaterialConfig {
                alpha_mode: AlphaMode::Blend,
                ..default()
            },
            true,
        );
        let handles = app.world().resource::<ChunkMaterialHandle>();
        assert!(handles.standard.is_none());
        let materials = app.world().resource::<Assets<ChunkMaterial>>();
        let material = materials.get(handles.custom.as_ref().unwrap()).unwrap();
        assert_eq!(material.alpha_mode(), AlphaMode::Opaque);
        assert_eq!(material.texture_array, Handle::<Image>::default());
    }
}