nucleation 0.1.184 → 0.2.2

package/README.md

@@ -1,350 +1,108 @@
-# Nucleation
+# Nucleation for JavaScript / TypeScript
 
-**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.
-
----
-
-[![Crates.io](https://img.shields.io/crates/v/nucleation.svg)](https://crates.io/crates/nucleation)
 [![npm](https://img.shields.io/npm/v/nucleation.svg)](https://www.npmjs.com/package/nucleation)
-[![PyPI](https://img.shields.io/pypi/v/nucleation.svg)](https://pypi.org/project/nucleation)
-
----
-
-## Features
-
-### Core
-
-- **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
-
-### Schematic Building
-
-- **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`)
-
-### Circuit Simulation
 
-- **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
+JavaScript / TypeScript bindings for **Nucleation**, a high-performance
+Minecraft schematic engine. Read, edit, build, simulate, and mesh
+`.schematic`, `.litematic`, `.nbt`, and `.mcstructure` files — in the
+browser or in Node.
 
-### 3D Mesh Generation
-
-- **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
-
-### Developer Experience
-
-- **Bracket notation** for blocks: `"minecraft:lever[facing=east,powered=false]"`
-- **Feature parity** across all language bindings
-- **Comprehensive documentation** in [`docs/`](docs/)
-- Seamless integration with [Cubane](https://github.com/Nano112/cubane)
+The core is written in Rust and compiled to WebAssembly via wasm-bindgen.
+A single package works in modern browsers, bundlers, and Node 18+.
 
 ---
 
-## Installation
-
-### Rust
-
-```bash
-cargo add nucleation
-```
-
-### JavaScript / TypeScript (WASM)
+## Install
 
 ```bash
 npm install nucleation
 ```
 
-### Python
-
 ```bash
-pip install nucleation
+pnpm add nucleation
 ```
 
-### C / PHP / FFI
-
-Download prebuilt `.so` / `.dylib` / `.dll` from [Releases](https://github.com/Schem-at/Nucleation/releases)
-or build locally using:
-
 ```bash
-./build-ffi.sh
+bun add nucleation
 ```
 
 ---
 
-## Quick Examples
-
-### Loading and Saving Schematics
-
-#### 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)
+## Quick start
 
 ```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())
-```
-
-### Building Schematics with ASCII Art
-
-```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](docs/guide/schematic-builder.md).
-
-### Compositional Circuit Design
-
-```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](docs/examples/4-bit-adder.md) for a complete hierarchical design.
-
-### CLI Tool
-
-```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
+import init from "nucleation";
+import { Schematic } from "nucleation/api";
 
-### Setting Blocks with Properties
+await init(); // load the wasm module
 
-```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`](examples/rust.md)
-
-### Redstone Circuit Simulation
-
-```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
-```
-
-### High-Level Typed Executor
-
-```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));
+const bytes = await fetch("example.litematic").then((r) => r.arrayBuffer());
+const schem = Schematic.open(new Uint8Array(bytes), {
+  hint: "example.litematic",
+});
 
-let result = executor.execute(
-    input_values,
-    ExecutionMode::FixedTicks { ticks: 100 }
-)?;
+schem.setBlock([0, 0, 0], "minecraft:gold_block");
+schem.setBlock([0, 1, 0], "minecraft:repeater", {
+  state: { delay: 4, facing: "east" },
+});
 
-// Get typed output
-let output = result.outputs.get("result").unwrap();
-assert_eq!(*output, Value::Bool(true));  // AND gate result
+const out = await schem.save("out.schem"); // Uint8Array
 ```
 
-**Supported types**: `Bool`, `U8`, `U16`, `U32`, `I8`, `I16`, `I32`, `Float32`, `Ascii`, `Array`, `Matrix`, `Struct`
-
-See [TypedCircuitExecutor Guide](docs/guide/typed-executor.md) for execution modes, state management, and more.
-
-### 3D Mesh Generation
+### Hot loops
 
-```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());
+```ts
+// One call into wasm — millions of placements/sec.
+const positions = Array.from({ length: 1_000_000 }, (_, x) => [x, 0, 0]);
+schem.setBlocks(positions, "minecraft:stone");
+
+// Pre-resolve once, place by index.
+const stone = schem.prepareBlock("minecraft:stone");
+for (const [x, y, z] of positions) {
+  schem.place(x, y, z, stone);
+}
 ```
 
----
-
-## 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
+### Tile-entity helpers
 
-# 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
+```ts
+import { chest, sign, text, Item } from "nucleation/api";
+
+schem.setBlock([0, 0, 0], "minecraft:chest", {
+  state: { facing: "north" },
+  nbt: chest([
+    Item("minecraft:diamond", { count: 64 }),
+    Item("minecraft:elytra"),
+  ]),
+});
+
+schem.setBlock([0, 1, 0], "minecraft:oak_sign", {
+  nbt: sign([text("Loot", { color: "gold" }), "this way →"]),
+});
 ```
 
 ---
 
 ## Documentation
 
-### 📖 Language-Specific Documentation
-
-Choose your language for complete API reference and examples:
+Full reference, including simulation, meshing, and resource-pack rendering,
+lives in the main repository:
 
-- **[Rust Documentation](docs/rust/)** - Complete Rust API reference
-- **[JavaScript/TypeScript Documentation](docs/javascript/)** - WASM API for web and Node.js
-- **[Python Documentation](docs/python/)** - Python bindings API
-- **[C/FFI Documentation](examples/ffi.md)** - C-compatible FFI for PHP, Go, etc.
+- [Nucleation on GitHub](https://github.com/Schem-at/Nucleation)
+- [JavaScript API reference](https://github.com/Schem-at/Nucleation/blob/master/docs/javascript/README.md)
+- [Schematic Builder guide](https://github.com/Schem-at/Nucleation/blob/master/docs/guide/schematic-builder.md)
 
-### 📚 Shared Guides
-
-These guides apply to all languages:
-
-- [SchematicBuilder Guide](docs/shared/guide/schematic-builder.md) - ASCII art and compositional design
-- [TypedCircuitExecutor Guide](docs/shared/guide/typed-executor.md) - High-level circuit simulation
-- [Circuit API Guide](docs/shared/guide/circuit-api.md) - CircuitBuilder and DefinitionRegion
-- [Unicode Palette Reference](docs/shared/unicode-palette.md) - Visual circuit characters
-
-### 🎯 Quick Links
+---
 
-- [Main Documentation Index](docs/) - Overview and comparison
-- [Examples Directory](examples/) - Working code examples
+## Why Rust + WASM?
 
----
+Nucleation's core is shared across Rust, WebAssembly/JS, Python, and C/PHP —
+one engine, one set of behaviour, one set of tests. The npm package you
+install is the same engine that powers the Python and Rust libraries; the
+wasm boundary is the only thing between your JS and native-speed parsing
+and meshing.
 
 ## License
 
-Licensed under the **GNU AGPL-3.0-only**.
-See [`LICENSE`](./LICENSE) for full terms.
-
-Made by [@Nano112](https://github.com/Nano112)
+AGPL-3.0-only. See the [main repository](https://github.com/Schem-at/Nucleation)
+for details.