Nucleation

A Minecraft schematic engine in Rust: load, build, simulate, mesh, and render schematics from seven languages.

Every frame of this 3x7 knot is a separately generated schematic: its braid advances while a periodic cellular field flows along the curve, cutting raised scorched plates over a molten core. It was built and rendered by nucleation (Python source · frame 0 .schem · SDFs and fields).

Install

cargo add nucleation        # Rust
npm  install nucleation     # JavaScript / TypeScript (Node ≥ 18 or a bundler)
pip  install nucleation     # Python (CPython 3.12+)

Kotlin/JVM, PHP, C, and C++ ship as archives on Releases; see the quickstarts.

Features

Every capability, with its own deep-dive doc:

• Basics — create, inspect, load, save, and download a complete example

• Formats and I/O — load, edit, and save every supported format

• Regions, transforms, stamping — deterministic multi-region builds, scoped rigid transforms, and reusable stamping

• Shapes, brushes, masked fills — the building primitives

• SDF shapes, terrain, and fields — typed composable geometry, custom functions, terrain, Voronoi

• Palettes and color — turning colors into blocks

• Voxelizing 3D models — GLB/OBJ meshes, texture projection

• Geodata — elevation grids and OSM footprints

• Composition — stacking the primitives

• Chunk iteration, streaming, worlds — constant-memory pipelines and world I/O

• World segmentation — a whole world into individual builds with provenance, deterministically

• Embedded schematic provenance — standardized world, map, dimension, coordinates, and source identity inside each build

• Transformation and content policies — canonical palettes, material standards, entity/NBT rules, UUID rewriting, and registry-safe inspection

• Block entities, entities, NBT — SNBT round-trips

• Redstone simulation — MCHPRS redpiler, typed circuit executors

• Tick simulation — vanilla-accurate tick loop, verified against captures from the game

• Meshing and rendering — GLB/glTF/USDZ and the headless renderer

• Animating a build — assembly, layer printing, reveals along a curve

• Analysis — diff, fingerprint, auto-stack

• Versions and translation — data-version migration, Java <-> Bedrock

• The block database — 1,196 blocks, facts and measured colors

• Embedded scripting — Lua and JS against the full API

• Pluggable storage — mem, fs, SSH, S3, Redis, Postgres

• Bindings and languages — one generated API, seven languages

Normalize imported schematics

Normalization is an explicit, versioned pipeline rather than an implicit part of loading or saving. Dry-run the exact plan first, inspect its stable audit report, then apply it atomically:

from nucleation import Schematic, TransformPlan, inspect_transform, apply_transform

schematic = Schematic.open("incoming.schem")
plan = TransformPlan.registry_safe()

preview = inspect_transform(schematic, plan)  # never mutates schematic
if not preview.rejected and not preview.quarantined:
    report = apply_transform(schematic, plan)  # all passes commit, or none do
    schematic.save("normalized.schem")

Use TransformPlan.canonical() for lossless deterministic palette cleanup. Use a custom plan for material conventions, text/NBT/item/entity rules, limits, or UUID standardization. The complete transformation-policy guide documents every field, default, action, report, safety guarantee, Python helper, shared JSON contract, and the storage-backed registry pipeline.

The gallery

Ten more builds, each a short recipe that leans on the same handful of primitives: a rainbow DNA helix and a trefoil knot, a Menger sponge, a fractal tree, a gyroid, a Mandelbulb, a voxelized fox, a supershape, animated wave interference, and type set in blocks.

Every one is a few dozen lines. Open the gallery for all ten with their code.

Redstone EDA

Electronic design automation for redstone lives in redstone-eda/: Verilog in, exhaustively sim-verified .schem out.

An HDL compiler (combinational and sequential — always @(posedge clk) becomes a characterized DFF bank plus a clock spine), a verified comparator-cell library, place-and-route (crates/pnr-core + crates/nucleation-routing, with DRC/LVS/STA on a generated Routing bridge), an interactive compositor with a browser app, and 18 baked-at-rest artifacts totalling 221,785 blocks and 2,660 verification checks — up to the 32-bit Kogge-Stone adder above.

Nothing is trusted because it looks right: every artifact is proven in mc-tick, the vanilla-accurate tick simulator, before it is saved, and is saved settled so what you paste is what was proven.

Documentation & development

• Documentation index: per-language references and all feature guides (shapes & brushes, palettes, SDF terrain, scripting, block database)
• docs/readme-snippets/: every snippet in the feature docs, with its verified output
• Release notes

The public documentation site is built with Material for MkDocs. Preview it locally with:

python -m venv .venv
.venv/bin/pip install -r requirements-docs.txt
.venv/bin/mkdocs serve

Pushes to master publish the same strict build to GitHub Pages through .github/workflows/docs.yml.

Also in the box: layer-art templates (schematics from ASCII art).

Start here: docs/DEV.md — the iteration recipe. The crate builds under many feature combinations, and each one recompiles all 159 dependencies into its own artifacts; picking features ad hoc is what turned edit-check loops into hour-long ones. docs/DEV.md has the canonical feature set, the tier table, and the disk-hygiene rules.

brew install sccache                # prerequisite (wired in .cargo/config.toml)
tools/dev.sh fast [crate]           # the loop — seconds
tools/dev.sh pre-land               # tests + wasm32 + studio + smoke — minutes
tools/dev.sh full                   # the merge gate — exhaustive, all features
tools/doctor.sh                     # "why is my loop slow?" / disk hygiene

cargo test                          # core suite
./tools/gen-bindings.sh             # regenerate bindings (diplomat-tool fork)
./examples/bridge_smoke/js/run.sh   # end-to-end smoke per language

.github/workflows/dev-tiers.yml runs those same tiers on push and PR with sccache and target caching. The release/manual CI matrix regenerates bindings and fails on drift, exercises every built wheel and the assembled JAR, and smoke-tests all seven language bindings.

License

MIT. See LICENSE.