nucleation 0.1.83

A high-performance Minecraft schematic parser and utility library

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

• Multi-format support: .schematic, .litematic, .nbt, etc.
• Memory-safe Rust core with zero-copy deserialization
• WASM module for browser + Node.js with simulation support
• Native Python bindings (pip install nucleation)
• C-compatible FFI for PHP, C, Go, etc.
• Redstone circuit simulation via MCHPRS integration (optional simulation feature)
• Bracket notation for setting blocks with properties: "minecraft:lever[facing=east,powered=false]"
• Feature parity across all interfaces
• Binary builds for Linux, macOS, Windows (x86_64 + ARM64)
• Seamless integration with Cubane

---

Installation

Rust

cargo add nucleation

JavaScript / TypeScript (WASM)

npm install nucleation

Python

pip install nucleation

C / PHP / FFI

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

./build-ffi.sh

---

Quick Examples

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());

More in examples/rust.md

---

JavaScript (WASM)

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());

Setting blocks with properties (bracket notation):

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]");

Redstone simulation:

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

Custom IO signal injection/monitoring:

// Configure custom IO nodes for precise signal control
const options = new SimulationOptions();
options.addCustomIo(5, 1, 0); // Mark position as custom IO node

const simWorld = schematic.create_simulation_world_with_options(options);

// Inject custom signal strength
simWorld.setSignalStrength(5, 1, 0, 12); // Set signal to 12
simWorld.tick(5);
simWorld.flush();

// Read signal strength
const strength = simWorld.getSignalStrength(5, 1, 0);
console.log(`Signal strength: ${strength}`);

More in examples/wasm.md

---

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())

More in examples/python.md

---

FFI (PHP/C)

#include "nucleation.h"

SchematicHandle* handle = schematic_new("MySchem");
schematic_load_data(handle, data_ptr, data_len);

CSchematicInfo info;
schematic_get_info(handle, &info);
printf("Size: %dx%dx%d\n", info.width, info.height, info.depth);

schematic_free(handle);

More in examples/ffi.md

---

Development

# Build the Rust core
cargo build --release

# Build with simulation support
cargo build --release --features simulation

# 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
./test-wasm.sh  # WASM tests with simulation

# Pre-push verification (recommended before pushing)
./pre-push.sh  # Runs all checks that CI runs

---

Submodules & Bindings

Rust

• examples/rust.md

JavaScript/TypeScript

• examples/wasm.md

Python

• examples/python.md

FFI (C/PHP)

• examples/ffi.md

---

License

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

Made by @Nano112