Building Blocks

Building Blocks is a voxel library for real-time applications.

Features include:

memory-efficient storage of voxel maps
- a ChunkMap with generic chunk storage
- LRU-cached storage of compressed chunks
- compressed serialization format
- OctreeSet bitset structure
mesh generation
- isosurface
- cubic / blocky
- height map
accelerated spatial queries
- ray casting and sphere casting
- range queries
procedural generation
- sampling signed distance fields
- constructive solid geometry (TODO)
pathfinding on voxel maps

Short Code Example

The code below samples a signed distance field and generates a mesh from it.

use building_blocks::{
    prelude::*,
    mesh::{SurfaceNetsBuffer, surface_nets},
    procgen::signed_distance_fields::sphere,
};

let center = PointN([25.0; 3]);
let radius = 10.0;
let sphere_sdf = sphere(center, radius);

let extent = Extent3i::from_min_and_shape(PointN([0; 3]), PointN([50; 3]));
let mut samples = Array3::fill_with(extent, &sphere_sdf);

let mut mesh_buffer = SurfaceNetsBuffer::new();
surface_nets(&samples, samples.extent(), &mut mesh_buffer);

Configuration

Features and WASM

Building Blocks is organized into several crates, some of which are hidden behind features, and some have features themselves, which get re-exported by the top-level crate.

For example, chunk compression supports two backends out of the box: Lz4 and Snappy. They are enabled with the "lz4" and "snappy" features. "lz4" is the default, but it relies on a C++ library, so it's not compatible with WASM. But Snappy is pure Rust, so it can! Just use default-features = false and add "snappy" to you features list, like so:

[dependencies.building-blocks]
version = "0.4.1"
default-features = false
features = ["snappy"]

LTO

It is highly recommended that you enable link-time optimization when using building-blocks. It will improve the performance of critical algorithms like meshing by up to 2x. Just add this to your Cargo.toml:

[profile.release]
lto = true

Learning

The current best way to learn about the library is to read the documentation and examples.

For the latest stable docs, look here.

For the latest unstable docs, clone the repo and run

cargo doc --open

There is plentiful documentation with examples.

Take a look in the examples/ directory to see how Building Blocks can be used in real applications.

To run the benchmarks (using the "criterion" crate), go to the root of a crate and run cargo bench.

To learn more about the motivations behind the library's design, read about our design philosophy and architecture.

Development

We prioritize work according to the project board.

If you'd like to make a contribution, please first read the contribution guidelines.