Nucleation

Nucleation is a high-performance Minecraft schematic parser and utility library written in Rust, with WebAssembly and FFI bindings for multiple environments.

Features

• Parse and manipulate multiple schematic formats (.schematic, .litematic, etc.)
• High-performance Rust core with WebAssembly bindings
• Chunk-based loading for progressive rendering
• Block entity support (chests, signs, etc.)
• Designed for integration with Cubane for 3D visualization

Installation

Rust

cargo add nucleation

JavaScript/TypeScript (via npm)

npm install nucleation
# or
yarn add nucleation

Usage Examples

JavaScript (WebAssembly)

import { SchematicParser } from 'nucleation';

// Load a schematic file
const response = await fetch('example.litematic');
const fileData = new Uint8Array(await response.arrayBuffer());

// Parse the schematic
const parser = new SchematicParser();
await parser.fromData(fileData);

// Get schematic dimensions
const [width, height, depth] = parser.getDimensions();
console.log(`Dimensions: ${width}x${height}x${depth}`);

// Load blocks progressively in chunks
const chunks = parser.chunksWithStrategy(
  16, 16, 16,           // chunk size
  "distance_to_camera", // loading strategy
  camera.x, camera.y, camera.z
);

// With Cubane integration
const renderer = new Cubane.Cubane();
for (const chunk of chunks) {
  for (const block of chunk.blocks) {
    const mesh = await renderer.getBlockMesh(block.name);
    mesh.position.set(block.x, block.y, block.z);
    scene.add(mesh);
  }
}

Rust

use nucleation::SchematicParser;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load a schematic file
    let data = std::fs::read("example.litematic")?;
    
    // Parse the schematic
    let parser = SchematicParser::new();
    let schematic = parser.from_data(&data)?;
    
    // Get block information
    let dimensions = schematic.get_dimensions();
    println!("Dimensions: {}x{}x{}", dimensions[0], dimensions[1], dimensions[2]);
    
    // Iterate through blocks
    for (pos, block) in schematic.iter_blocks() {
        println!("Block at {},{},{}: {}", pos.x, pos.y, pos.z, block.name);
    }
    
    Ok(())
}

Integration with Cubane

Nucleation works seamlessly with Cubane for 3D visualization, forming a complete solution for Minecraft schematic processing and rendering.

import { SchematicParser } from 'nucleation';
import { Cubane } from 'cubane';

// Parse schematic with Nucleation
const parser = new SchematicParser();
await parser.fromData(fileData);

// Render with Cubane
const cubane = new Cubane.Cubane();
// ... set up Three.js scene ...

// Load and render blocks
for (const block of parser.blocks()) {
  const mesh = await cubane.getBlockMesh(block.name);
  mesh.position.set(block.x, block.y, block.z);
  scene.add(mesh);
}

License

This project is available under the MIT or Apache-2.0 license.

Development

# Build the Rust library
cargo build --release

# Build the WebAssembly package
./build-wasm.sh

# Run tests
cargo test

Created and maintained by Nano