🧬 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 TypeScript support
• 🐍 Native Python bindings (pip install nucleation)
• ⚙️ C-compatible FFI for PHP, C, Go, etc.
• 🎨 Blockpedia integration for color analysis and block transformations (native targets)
• 🔄 Feature parity across all interfaces via single API definition
• 📦 Binary builds for Linux, macOS, Windows (x86_64 + ARM64)
• 🚀 Automatic binding generation from centralized API definitions
• 🧪 Comprehensive test suite with CI/CD pipeline

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

📖 → Documentation | Complete Code Example

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

📖 → Documentation | Complete Code Example

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

📖 → Documentation | Complete Code Example

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

📖 → Documentation | Complete Code Example

🔧 Development

Building

# Build the Rust core
cargo build --release

# Build WASM module with target support
cargo build --target wasm32-unknown-unknown --features wasm
./build-wasm.sh

# Build Python bindings locally
maturin develop --features python

# Build FFI libs
./build-ffi.sh

🤖 Automated Binding Generation

Nucleation uses a single source of truth approach for all bindings. The API is defined once in src/api_definition.rs and automatically translated to all supported languages:

# Generate all binding files from API definition
cargo run --bin generate-bindings

# Check if bindings are up to date
cargo run --bin generate-bindings check

# Generate API documentation report
cargo run --bin generate-bindings report

This generates:

• WASM: TypeScript definitions and JavaScript bindings
• Python: PyO3 bindings and .pyi type stubs
• FFI: C header files and Rust FFI implementations

🧪 Testing

# Run all tests
cargo test

# Test specific targets
cargo test --features wasm --test wasm_tests        # WASM tests
cargo test --test python_tests                      # Python tests
cargo test --test blockpedia_integration_test       # Blockpedia tests (non-WASM only)

# Test WASM build specifically
cargo build --target wasm32-unknown-unknown --features wasm

Note: WASM builds exclude blockpedia features for compatibility. Color analysis and block transformations are available only on native targets.

Version Management

Versions are centrally managed in version.toml. Use the Makefile commands:

# Check version consistency across all files
make version-check

# Bump versions automatically
make version-bump-patch    # 0.1.0 → 0.1.1
make version-bump-minor    # 0.1.0 → 0.2.0  
make version-bump-major    # 0.1.0 → 1.0.0

# Update all files from version.toml
make version-update

📖 → Full Version Management Guide

📚 Submodules & Bindings

📄 Documentation & Examples

Each binding includes comprehensive documentation and working code examples:

⚖️ License

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

Made by @Nano112 with ❤️