A high-performance Minecraft schematic parser and utility library
npm install nucleationNucleation 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.
---



---
- 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
- 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)
- 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
- 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
- Bracket notation for blocks: "minecraft:lever[facing=east,powered=false]"
- Feature parity across all language bindings
- Comprehensive documentation in docs/
- Seamless integration with Cubane
---
``bash`
cargo add nucleation
`bash`
npm install nucleation
`bash`
pip install nucleation
Download prebuilt .so / .dylib / .dll from Releases
or build locally using:
`bash`
./build-ffi.sh
---
#### 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())
`
`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.
`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.
`bashBuild schematic from text template
cat circuit.txt | schematic-builder -o circuit.litematic
---
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]"
);
`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, StructSee 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 --releaseBuild with simulation support
cargo build --release --features simulationBuild with meshing support
cargo build --release --features meshingBuild WASM module (includes simulation)
./build-wasm.shBuild Python bindings locally
maturin develop --features pythonBuild FFI libs
./build-ffi.shRun tests
cargo test
cargo test --features simulation
cargo test --features meshing
./test-wasm.sh # WASM tests with simulationPre-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
LICENSE` for full terms.Made by @Nano112