{"id":13790357,"url":"https://github.com/bonsairobo/building-blocks","last_synced_at":"2025-05-12T09:32:32.697Z","repository":{"id":45789431,"uuid":"302505779","full_name":"bonsairobo/building-blocks","owner":"bonsairobo","description":"A voxel library for real-time applications.","archived":true,"fork":false,"pushed_at":"2022-06-23T15:47:54.000Z","size":4228,"stargazers_count":375,"open_issues_count":11,"forks_count":31,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-10T06:51:37.065Z","etag":null,"topics":["3d","gamedev","geometry","mesh","rendering","voxel"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bonsairobo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-09T01:49:58.000Z","updated_at":"2025-05-09T12:13:52.000Z","dependencies_parsed_at":"2022-07-17T00:16:21.375Z","dependency_job_id":null,"html_url":"https://github.com/bonsairobo/building-blocks","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonsairobo%2Fbuilding-blocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonsairobo%2Fbuilding-blocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonsairobo%2Fbuilding-blocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonsairobo%2Fbuilding-blocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bonsairobo","download_url":"https://codeload.github.com/bonsairobo/building-blocks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253377221,"owners_count":21898936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","gamedev","geometry","mesh","rendering","voxel"],"created_at":"2024-08-03T22:00:42.215Z","updated_at":"2025-05-12T09:32:32.259Z","avatar_url":"https://github.com/bonsairobo.png","language":"Rust","funding_links":[],"categories":["Integration","Libraries"],"sub_categories":[],"readme":"# building-blocks\r\n\r\n[![Crates.io](https://img.shields.io/crates/v/building-blocks.svg)](https://crates.io/crates/building-blocks)\r\n[![Docs.rs](https://docs.rs/building-blocks/badge.svg)](https://docs.rs/building-blocks)\r\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\r\n[![Crates.io](https://img.shields.io/crates/d/building-blocks.svg)](https://crates.io/crates/building-blocks)\r\n[![Discord](https://img.shields.io/discord/770726405557321778.svg?logo=discord\u0026colorB=7289DA)](https://discord.gg/CnTNjwb)\r\n\r\nBuilding Blocks is a voxel library for real-time applications.\r\n\r\n### Project Status\r\n\r\nThis crate is in maintenance mode. I have extracted the most useful features into their own crates\r\nwith fewer overall dependencies. Rather than providing generic APIs centered around a bespoke `Array` type,\r\nthe new crates provide simpler APIs that only require slice `[T]` data.\r\n\r\nThe list of new crates is here: https://github.com/stars/bonsairobo/lists/my-stack\r\n\r\nThere are currently no plans to resume development on `building-blocks`, and users should consider migrating\r\nto the new crates. These crates will be actively maintained as their development is driven by the\r\n[feldspar](https://github.com/bonsairobo/feldspar) project.\r\n\r\n![LOD\r\nTerrain](https://media.githubusercontent.com/media/bonsairobo/building-blocks/main/examples/screenshots/lod_terrain.png)\r\n\r\nWe focus on generally useful data structures and algorithms. Features include:\r\n\r\n- 2D and 3D data storage\r\n  - [`Array`](crate::storage::array) with structure-of-arrays (`SoA`) storage of multiple data channels per spatial\r\n    dimension\r\n  - [`ChunkTree`](crate::storage::chunk_tree) is a quadtree (2D) or octree (3D) with generic chunks and chunk storage\r\n  - [`ChunkDb`](crate::storage::database) for compressed, persistent voxel worlds, backed by the\r\n    [`sled`](https://docs.rs/sled) embedded database\r\n- level of detail\r\n  - [`ChunkDownsampler`](crate::storage::chunk_tree::ChunkDownsampler) trait controls how new samples are generated from LOD\r\n    N into LOD N+1\r\n  - `ChunkTree` can act as a clipmap for keeping high detail close to a focal point, generating events to trigger:\r\n    - chunk generation / loading\r\n    - chunk split / merge when desired sample rate changes\r\n    - chunk eviction\r\n- mesh generation\r\n  - Surface Nets isosurface extraction\r\n  - Minecraft-style greedy meshing\r\n  - height maps\r\n- spatial queries\r\n  - ray and ball casting against octrees with [`ncollide3d`](https://www.ncollide.org/)\r\n  - Amanatides and Woo ray grid traversal\r\n  - pathfinding\r\n- procedural generation\r\n  - sampling signed distance fields\r\n  - constructive solid geometry with [`sdfu`](https://docs.rs/sdfu)\r\n\r\n## Short Code Example\r\n\r\nThe code below samples a [signed distance field](https://en.wikipedia.org/wiki/Signed_distance_function) and generates a\r\nmesh from it.\r\n\r\n```rust\r\nuse building_blocks::{\r\n    core::sdfu::{Sphere, SDF},\r\n    prelude::*,\r\n    mesh::{SurfaceNetsBuffer, surface_nets},\r\n};\r\n\r\nlet center = Point3f::fill(25.0);\r\nlet radius = 10.0;\r\nlet sphere_sdf = Sphere::new(radius).translate(center);\r\n\r\nlet extent = Extent3i::from_min_and_shape(Point3i::ZERO, Point3i::fill(50));\r\nlet mut samples = Array3x1::fill_with(extent, |p| sphere_sdf.dist(Point3f::from(p)));\r\n\r\nlet mut mesh_buffer = SurfaceNetsBuffer::default();\r\nlet voxel_size = 2.0; // length of the edge of a voxel\r\nlet estimate_normals = true; // use the SDF to estimate normals instead of flat shading\r\nsurface_nets(\u0026samples, samples.extent(), voxel_size, estimate_normals, \u0026mut mesh_buffer);\r\n```\r\n\r\n## Learning\r\n\r\n### Design and Architecture\r\n\r\nThere is a terse [design doc](https://github.com/bonsairobo/building-blocks/blob/main/DESIGN.md) that gives an overview of\r\ndesign decisions made concerning the current architecture. You might find this useful as a high-level summary of the most\r\nimportant pieces of code.\r\n\r\n### Docs and Examples\r\n\r\nThe current best way to learn about the library is to read the documentation and examples. For the latest stable docs, look\r\n[here](https://docs.rs/building_blocks/latest/building_blocks). For the latest unstable docs, clone the repo and run\r\n\r\n```sh\r\ncargo doc --open\r\n```\r\n\r\nThere is plentiful documentation with examples. Take a look in the `examples/` directory to see how Building Blocks can be\r\nused in real applications.\r\n\r\n#### Getting Started\r\n\r\nThis library is organized into several crates. The most fundamental are:\r\n\r\n- [**core**](crate::core): lattice point and extent data types\r\n- [**storage**](crate::storage): storage for lattice maps, i.e. functions defined on `Z^2` and `Z^3`\r\n\r\nThen you get extra bits of functionality from the others:\r\n\r\n- [**mesh**](crate::mesh): 3D mesh generation algorithms\r\n- [**search**](crate::search): search algorithms on lattice maps\r\n\r\nTo learn the basics about lattice maps, start with these doc pages:\r\n\r\n- [point](https://docs.rs/building_blocks_core/latest/building_blocks_core/point/struct.PointN.html)\r\n- [extent](https://docs.rs/building_blocks_core/latest/building_blocks_core/extent/struct.ExtentN.html)\r\n- [array](https://docs.rs/building_blocks_storage/latest/building_blocks_storage/array/index.html)\r\n- [access traits](https://docs.rs/building_blocks_storage/latest/building_blocks_storage/access_traits/index.html)\r\n- [chunk map](https://docs.rs/building_blocks_storage/latest/building_blocks_storage/chunk/map/index.html)\r\n- [transform map](https://docs.rs/building_blocks_storage/latest/building_blocks_storage/transform_map/index.html)\r\n- [fn map](https://docs.rs/building_blocks_storage/latest/building_blocks_storage/func/index.html)\r\n\r\n### Benchmarks\r\n\r\nTo run the benchmarks (using the \"criterion\" crate), go to the root of a crate and run `cargo bench`. As of version 0.5.0,\r\nall benchmark results are posted in the release notes.\r\n\r\n## Configuration\r\n\r\n### LTO\r\n\r\nIt is highly recommended that you enable link-time optimization when using building-blocks. It will improve the performance\r\nof critical algorithms like meshing by up to 2x. Just add this to your Cargo.toml:\r\n\r\n```toml\r\n[profile.release]\r\nlto = \"thin\"\r\n```\r\n\r\n### Cargo Features\r\n\r\nBuilding Blocks is organized into several crates, some of which are hidden behind features, and some have features\r\nthemselves, which get re-exported by the top-level crate. Some features are enabled by default. You can avoid taking\r\nunnecessary dependencies by declaring `default-features = false` in your `Cargo.toml`:\r\n\r\n```toml\r\n[dependencies.building-blocks]\r\nversion = \"0.7\"\r\ndefault-features = false\r\nfeatures = [\"foo\", \"bar\"]\r\n```\r\n\r\n#### Math Type Conversions\r\n\r\nThe `PointN` types have conversions to/from [`glam`](https://docs.rs/glam), [`nalgebra`](https://nalgebra.org/),\r\n[`cgmath`](https://docs.rs/cgmath) and [`mint`](https://docs.rs/mint) types by enabling the corresponding feature.\r\n\r\n#### Compression Backends and WASM\r\n\r\nChunk compression supports two backends out of the box: `Lz4` and `Snappy`. They are enabled with the \"lz4\" and \"snappy\"\r\nfeatures. \"lz4\" is the default, but it relies on a C++ library, so it's not compatible with WASM. But Snappy is pure Rust,\r\nso it can! Just use `default-features = false` and add \"snappy\" to you `features` list.\r\n\r\n#### Chunk Databases\r\n\r\nFor persistent voxel worlds that support edits, it's useful to have an embedded database for crash-consistent save state.\r\nWe've chosen to use the [`sled`](https://github.com/spacejam/sled) crate. When you enable the `sled` feature, you will get\r\naccess to a `ChunkDb` type that supports reading and writing compressed chunk data. And because `sled` does not yet support\r\nincremental backups (AKA snapshots), we've also implemented our own snapshot scheme in a separate\r\n[`sled-snapshots`](https://github.com/bonsairobo/sled-snapshots) crate which backs a `VersionedChunkDb`. This database\r\nschema only stores the changes (deltas) between versions, so you don't have to store an entire map in every save.\r\n\r\n#### VOX Files\r\n\r\n\".VOX\" files are supported via the [`vox-format`](https://docs.rs/vox-format/) crate. Enable the `vox-format` feature to get\r\nthe `VoxModelBuffer` trait impl for `Array3x1`, which allows you to read VOX files directly into an array.\r\n\r\n#### Images\r\n\r\nArrays can be converted to `ImageBuffer`s and constructed from `GenericImageView`s from the [`image`](https://docs.rs/image)\r\ncrate. Enable the `image` feature to expose the generic `encode_image` function and `From\u003cIm\u003e where Im: GenericImageView`\r\nimpl.\r\n\r\n#### Signed Distance Field Utilities (sdfu)\r\n\r\nThe [`sdfu`](https://docs.rs/sdfu) crate provides convenient APIs for constructive solid geometry operations. By enabling\r\nthis feature, the `PointN` types will implement the `sdfu::mathtypes` traits in order to be used with these APIs. The `sdfu`\r\ncrate also gets exported under `building_blocks::core::sdfu`.\r\n\r\n## Development\r\n\r\nWe prioritize work according to the [project board](https://github.com/bonsairobo/building-blocks/projects/1).\r\n\r\nIf you'd like to make a contribution, please first read the **[design\r\nphilosophy](https://github.com/bonsairobo/building-blocks/blob/main/DESIGN.md)** and **[contribution\r\nguidelines](https://github.com/bonsairobo/building-blocks/blob/main/CONTRIBUTING.md)**.\r\n\r\nLicense: MIT\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonsairobo%2Fbuilding-blocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonsairobo%2Fbuilding-blocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonsairobo%2Fbuilding-blocks/lists"}