Nucleation

Nucleation is a high-performance Minecraft schematic engine written in Rust with full support for Rust, WebAssembly/JavaScript, Python, and FFI-based integrations like PHP and C.

> Built for performance, portability, and parity across ecosystems.

---


---

Features

$3

- Multi-format support: .schematic, .litematic, .nbt, .mcstructure, and more
- Memory-safe Rust core with zero-copy deserialization
- Cross-platform: Linux, macOS, Windows (x86_64 + ARM64)
- Multi-language: Rust, JavaScript/TypeScript (WASM), Python, C/FFI

$3

- SchematicBuilder: Create schematics with ASCII art and Unicode characters
- Compositional Design: Build circuits hierarchically from smaller components
- Unicode Palettes: Visual circuit design with intuitive characters (→, │, █, etc.)
- Template System: Define circuits in human-readable text format
- CLI Tool: Build schematics from command line (schematic-builder)

$3

- Redstone simulation via MCHPRS integration (optional simulation feature)
- TypedCircuitExecutor: High-level API with typed inputs/outputs (Bool, U32, Ascii, etc.)
- CircuitBuilder: Fluent API for streamlined executor creation
- DefinitionRegion: Advanced region manipulation with boolean ops, filtering, and connectivity analysis
- Custom IO: Inject and monitor signal strengths at specific positions
- Execution Modes: Fixed ticks, until condition, until stable, until change
- State Management: Stateless, stateful, or manual tick control

$3

- Resource pack loading from ZIP files or raw bytes
- GLB/glTF export for standard 3D viewers and engines
- USDZ export for Apple AR Quick Look
- Raw mesh export for custom rendering pipelines (positions, normals, UVs, colors, indices)
- Per-region and per-chunk meshing for large schematics
- Greedy meshing to reduce triangle count
- Occlusion culling to skip fully hidden blocks
- Ambient occlusion with configurable intensity
- Resource pack querying — list/get/add blockstates, models, and textures

$3

- Bracket notation for blocks: "minecraft:lever[facing=east,powered=false]"
- Feature parity across all language bindings
- Comprehensive documentation in docs/
- Seamless integration with Cubane

---

Installation

$3

``bash
cargo add nucleation
`

$3

`bash
npm install nucleation
`

$3

`bash
pip install nucleation
`

$3

Download prebuilt .so / .dylib / .dll from Releases
or build locally using:

`bash
./build-ffi.sh
`

---

Quick Examples

$3

#### Rust

`rust
use nucleation::UniversalSchematic;

let bytes = std::fs::read("example.litematic")?;
let mut schematic = UniversalSchematic::new("my_schematic");
schematic.load_from_data(&bytes)?;
println!("{:?}", schematic.get_info());
`

#### JavaScript (WASM)

`ts
import { SchematicParser } from "nucleation";

const bytes = await fetch("example.litematic").then((r) => r.arrayBuffer());
const parser = new SchematicParser();
await parser.fromData(new Uint8Array(bytes));
console.log(parser.getDimensions());
`

#### Python

`python
from nucleation import Schematic

with open("example.litematic", "rb") as f:
data = f.read()

schem = Schematic("my_schematic")
schem.load_from_bytes(data)
print(schem.get_info())
`

$3

`rust
use nucleation::SchematicBuilder;

// Use Unicode characters for visual circuit design!
let circuit = SchematicBuilder::new()
.from_template(r#"
# Base layer
ccc
ccc

# Logic layer
─→─
│█│
"#)
.build()?;

// Save as litematic
let bytes = nucleation::litematic::to_litematic(&circuit)?;
std::fs::write("circuit.litematic", bytes)?;
`

Available in Rust, JavaScript, and Python! See SchematicBuilder Guide.

$3

`rust
// Build a basic gate
let and_gate = create_and_gate();

// Use it in a larger circuit
let half_adder = SchematicBuilder::new()
.map_schematic('A', and_gate) // Use entire schematic as palette entry!
.map_schematic('X', xor_gate)
.layers(&[&["AX"]]) // Place side-by-side
.build()?;

// Stack multiple copies
let four_bit_adder = SchematicBuilder::new()
.map_schematic('F', full_adder)
.layers(&[&["FFFF"]]) // 4 full-adders in a row
.build()?;
`

See 4-Bit Adder Example for a complete hierarchical design.

$3

`bash


Build schematic from text template

cat circuit.txt | schematic-builder -o circuit.litematic

From file

schematic-builder -i circuit.txt -o circuit.litematic

Choose format

schematic-builder -i circuit.txt -o circuit.schem --format schem

Export as mcstructure

schematic-builder -i circuit.txt -o circuit.mcstructure --format mcstructure
`

---

Advanced Examples

$3

`js
const schematic = new SchematicWrapper();
schematic.set_block(
0,
1,
0,
"minecraft:lever[facing=east,powered=false,face=floor]"
);
schematic.set_block(
5,
1,
0,
"minecraft:redstone_wire[power=15,east=side,west=side]"
);
`

More in examples/rust.md

$3

`js
const simWorld = schematic.create_simulation_world();
simWorld.on_use_block(0, 1, 0); // Toggle lever
simWorld.tick(2);
simWorld.flush();
const isLit = simWorld.is_lit(15, 1, 0); // Check if lamp is lit
`

$3

`rust
use nucleation::{TypedCircuitExecutor, IoType, Value, ExecutionMode};

// Create executor with typed IO
let mut executor = TypedCircuitExecutor::new(world, inputs, outputs);

// Execute with typed values
let mut input_values = HashMap::new();
input_values.insert("a".to_string(), Value::Bool(true));
input_values.insert("b".to_string(), Value::Bool(true));

let result = executor.execute(
input_values,
ExecutionMode::FixedTicks { ticks: 100 }
)?;

// Get typed output
let output = result.outputs.get("result").unwrap();
assert_eq!(*output, Value::Bool(true)); // AND gate result
`

Supported types: Bool, U8, U16, U32, I8, I16, I32, Float32, Ascii, Array, Matrix, Struct

See TypedCircuitExecutor Guide for execution modes, state management, and more.

$3

`rust
use nucleation::{UniversalSchematic, meshing::{MeshConfig, ResourcePackSource}};

// Load schematic and resource pack
let schematic = UniversalSchematic::from_litematic_bytes(&schem_data)?;
let pack = ResourcePackSource::from_file("resourcepack.zip")?;

// Configure meshing
let config = MeshConfig::new()
.with_greedy_meshing(true)
.with_cull_occluded_blocks(true);

// Generate GLB mesh
let result = schematic.to_mesh(&pack, &config)?;
std::fs::write("output.glb", &result.glb_data)?;

// Or USDZ for AR
let usdz = schematic.to_usdz(&pack, &config)?;

// Or raw mesh data for custom rendering
let raw = schematic.to_raw_mesh(&pack, &config)?;
println!("Vertices: {}, Triangles: {}", raw.vertex_count(), raw.triangle_count());
`

---

Development

`bash


Build the Rust core

cargo build --release

Build with simulation support

cargo build --release --features simulation

Build with meshing support

cargo build --release --features meshing

Build WASM module (includes simulation)

./build-wasm.sh

Build Python bindings locally

maturin develop --features python

Build FFI libs

./build-ffi.sh

Run tests

cargo test
cargo test --features simulation
cargo test --features meshing
./test-wasm.sh # WASM tests with simulation

Pre-push verification (recommended before pushing)

./pre-push.sh # Runs all checks that CI runs
`

---

Documentation

$3

Choose your language for complete API reference and examples:

- Rust Documentation - Complete Rust API reference
- JavaScript/TypeScript Documentation - WASM API for web and Node.js
- Python Documentation - Python bindings API
- C/FFI Documentation - C-compatible FFI for PHP, Go, etc.

$3

These guides apply to all languages:

- SchematicBuilder Guide - ASCII art and compositional design
- TypedCircuitExecutor Guide - High-level circuit simulation
- Circuit API Guide - CircuitBuilder and DefinitionRegion
- Unicode Palette Reference - Visual circuit characters

$3

- Main Documentation Index - Overview and comparison
- Examples Directory - Working code examples

---

License

Licensed under the GNU AGPL-3.0-only.
See LICENSE` for full terms.

Made by @Nano112