Introducing building-blocks v0.1.0

I'm excited to announce the first release of Building Blocks, an engine-agnostic Rust library focused on voxel game development.

Here's just a glimpse of what's possible. This is the "bevy_meshing" example, which generates meshes on the fly using various shapes and algorithms:

This is the same core technology behind the voxel-mapper project, which is currently based on the deprecated ilattice3. After a while piling new code into those projects, I decided I was in need of a "new set of bones" with some performance and API improvements.

After a lot of exploration, trials, errors, and lessons learned, I believe I've distilled a useful feature set for developers who need to work with volumetric data in a real-time setting. The most common problems I've encountered when working with billions of voxels are related to performance and memory usage. It has been a fun challenge to craft an ergonomic API that doesn't compromise performance where it really counts. Even with all of the hard work that went into make this library usable, there is still so much room for optimization.

The specific feature set provided by this release is mostly focused on the core data types and containers for voxel data, as well as some meshing, search, and collision algorithms that run on the CPU (GPU acceleration is on the road map). More specifically, you will find:

• the core 2D and 3D point and extent data types used for addressing voxel storage
  • no mandatory dependence on a 3rd party math library like nalgebra, but there are conversion trait impls behind a feature flag
• dense and sparse voxel storage
  • 2D and 3D arrays
  • chunked arrays that support fast compression and LRU caching
    • for the simple kinds of voxels you see in Minecraft, LZ4 chunk compression can achieve an efficiency of 60:1
    • this could theoretically support 125 billion 2-byte voxels in 4 GB of memory
    • LZ4 decompression rates exceed 2 GB/s per core in the worst case
  • fast, composable access traits for indexing, iteration, and copying
  • compressed bincode serialization to save your voxel maps to files or send them over a network
• meshing algorithms that produce coherent meshes, even on chunk boundaries
  • a Naive Surface Nets implementation for smooth voxels
  • a Greedy Meshing implementation for cube voxels
  • an algorithm for meshing height maps
  • all single-threaded, but you can easily run these algorithms on many chunks in parallel using your preferred runtime
• octree acceleration structures for spatial queries
  • very low memory usage (< 1 bit per voxel)
  • supports raycasting against voxel bounding boxes
  • ncollide3d integration behind a feature flag
• pathfinding algorithms
  • greedy best-first search
• criterion benchmarks
  • it is nontrivial to implement real-time voxel algorithms, so there is a suite of benchmarks written using the criterion crate to ensure that we aren't blindly micro-optimizing
• miscellaneous
  • encoding/decoding 3D arrays in VOX format via the dot_vox crate
    • this allows you to import/export your maps for editing in applications like Magicavoxel
  • encoding/decoding 2D arrays into pixel images via the image crate
    • so you can load up height maps from noise images if you like

One notable disclaimer, making a voxel game at massive scale (hundreds of billions of voxels) requires one very important feature that isn't implemented yet: dynamic level of detail. Without it, your meshes will not only look bad at a distance, but they will take up way too much memory. But this item is on the roadmap!

I hope to see more people building cool stuff with this library. Stay tuned for future releases, and please feel welcome to contribute when you have a problem that isn't solved by Building Blocks.

P.S. thanks to @superdump (Rob Swain) and @dekuraan (Declan Li-Carney) for being early adopters and providing me with feedback along the way. You can see one example of building-blocks being used in the wild here.