Bonsai: procedural voxel terrain generated in GLSL

Bonsai's GPU-defined voxel world model

Bonsai addresses a specific class of game and visualization work: procedural voxel worlds whose terrain rules need to be changed without rewriting a conventional CPU-side generator. Its primary language is C, but the README says terrain is generated on the GPU with regular GLSL shaders. That choice makes shader programming the main extension point. A terrain generator can use anything expressible in a shader, which is a broader interface than exposing only the built-in noise functions.

The repository includes `examples/terrain_gen/`, a collection of pre-built terrain shaders, and a noise library for 1D, 2D, and 3D noise. Terrain derivatives are also available during second-stage decoration. This suggests a generation process that can create terrain and then derive additional surface information from it. The README does not document the exact buffer layout, shader dispatch sequence, or coordinate convention, so those details would need to be established from the implementation before extending the generator.

Bonsai's stated world capacity is approximately one billion blocks in each direction, with one block treated as one meter in the README's comparison. It also claims an all-time view distance equal to the entire world. Those are project claims, not independently measured results. No hardware matrix, memory requirement, generation time, or frame-rate target accompanies them, which makes them unsuitable as performance guarantees for a new project.

Rendering and runtime systems around voxel generation

Voxel generation sits inside a broader engine rather than operating as a standalone library. The renderer supports deferred shading, HDR lighting, order-independent transparency, lighting bloom, shadow mapping, and screen-space ambient occlusion. On the runtime side, the README lists entities, collision, particles, a UI framework, asset loaders, and primitive physics. This gives a procedural world a path toward an interactive application, but the documentation does not state which components are production-ready.

The engine includes an asynchronous job system and hot reloading for shaders and game code. Hot shader reloading is particularly relevant to the GPU generation model because generator changes can be developed without restarting the program. The precise reload boundary is not documented. It may apply to shader sources, generated resources, or both, and the README gives no command or editor workflow for testing the behavior.

A performance profiler is also included. Its documented facilities include manual instrumentation, memory allocation tracking, multithreaded callgraph tracing, context switches on Windows, and a physical core view on Windows. This is useful evidence that the repository addresses engine-level diagnostics, but it is not evidence of runtime performance. The README does not publish profiler output, test scenes, hardware requirements, or comparative measurements.

Windows and Linux installation for Bonsai

The supported binary route in the README is limited to Windows and Linux. It directs users to the Latest Releases page for pre-built binaries and assets. The README does not list filenames, archive formats, launch commands, or installation directories, so presenting an invented command would be misleading. A new user should open `../../releases/latest`, select the artifact for the operating system, and follow any instructions bundled with that release.

Source builds have a narrower documented prerequisite: `clang++` version 18.1 or later, plus appropriate system headers. The README says nearly all dependencies were written from scratch and identifies the C runtime library as the main external dependency needed for program startup. It also points to `docs/01_build_process.md` for the build procedure. Because that file's commands are not included here, this article cannot state a reproducible build command.

There is no homepage or documented package-manager installation in the README. Users should not assume support for Homebrew, apt, npm, or another distribution channel. Nor does the README list macOS as a supported release platform, despite listing Windows and Linux. Confirming the release artifact and build dependencies is therefore the first installation task rather than an optional packaging detail.

A first Bonsai session through terrain and editing examples

The repository's `examples/` directory provides concrete starting points, including `examples/blank_project/`, `examples/terrain_gen/`, and `examples/the_wanderer/`. For a first terrain-focused session, `examples/terrain_gen/` is the most direct project to inspect because it corresponds directly to Bonsai's defining feature. The README does not document the command used to launch an example, so no launch command can be reproduced from the available text.

A practical first use starts with a downloaded Windows or Linux release. After extracting or running the release in the manner documented by that artifact, the reader would need to consult `docs/00_getting_started.md` for initialization and `docs/controls.md` for input mappings. The repository also contains `settings.init`, `hotkeys.init`, `shaders/`, and `brushes/`, but the README does not identify which must be edited or copied for a first run. Those paths are useful repository evidence, not an executable configuration guide.

After confirming the base project launches, the meaningful extension is to inspect the terrain example and its GLSL shaders. The README supports changing generator behavior through shader code, and it identifies hot shader reloading as an engine feature. It does not define a shader interface or explain how edits propagate into the terrain pipeline, so the first customization should be based on the example's existing contracts rather than a guessed shader entry point.

SDF editing and the limits of Bonsai's alpha rewrite

World editing uses CSG-like signed distance fields and SDF brushes. The repository includes primitive shapes such as rectangles, spheres, lines, and cylinders, while `brushes/` contains a layer-based brush interface. Documentation states that GLSL brush shaders are still marked as coming soon, so programmable brush shaders are not an available feature despite their proximity to the GPU-oriented design.

The principal limitation is project maturity. Bonsai's 2.0 release line underwent a large rewrite of core systems, including the generator and editor. The README explicitly says releases will remain marked `alpha` until those systems are fully ported and considered stable. The listed releases remain alpha candidates, including `v2.0.0-alpha-rc8` from 2025-12-16. The repository is not archived, and its last push was on 2026-10-13, but recency does not remove the stated stability warning.

The upgrade cost is therefore more important than ordinary patch churn. Existing code or projects may need attention when generator and editor interfaces change. The README does not provide migration notes in the excerpt, compatibility guarantees, or a stable 2.0 release. It directs developers to issue 82 for remaining roadmap work. Bonsai is a poor fit when stable editor behavior and a settled extension API are contractual requirements.

WTFPL implications and the engine's practical boundary

Bonsai is distributed under the `WTFPL`, as identified by the repository metadata and `LICENSE`. That designation is unusually permissive in common usage, but this article does not provide legal advice or interpret whether a particular modification, asset, or distribution model satisfies applicable obligations. Teams should have their own review process for license compatibility, especially because a game can combine engine code with separately licensed shaders, fonts, models, audio, and other assets.

Bonsai differs from a conventional CPU voxel generator most clearly in its placement of terrain logic. A CPU generator might expose language-level functions, command objects, or job callbacks. Bonsai instead states that regular GLSL shaders generate terrain on the GPU. That approach makes the GPU and shader toolchain part of the content workflow, which is attractive for procedural work but also adds platform and driver considerations that the README does not spell out.

Bonsai is also not a complete production stack by documentation alone. Erosion, biomes, water, fluids, improved shadows, motion blur, and several terrain or mesh techniques appear on the wishlist. Sound decompression and an MCA importer are also unchecked. These absences do not prevent engine experimentation, but they narrow the audience to developers who need the voxel and procedural-generation foundations more than a documented, feature-complete game stack.

Editorial conclusion

Adopt Bonsai if procedural voxel terrain written in GLSL is central to your project and you can work with an alpha engine and limited platform documentation. Do not adopt it as a stable general-purpose engine without checking the v2.0 roadmap, platform requirements, migration needs, and licensing compatibility. For this repository, the first verification point is whether the documented GPU and shader requirements match your target environment.

Frequently asked questions

Official sources

1. Issues
2. License: WTFPL
3. README
4. Releases
5. scallyw4g/bonsai on GitHub