nucleation 0.1.128__tar.gz → 0.1.130__tar.gz

{nucleation-0.1.128 → nucleation-0.1.130}/Cargo.lock

@@ -1687,7 +1687,7 @@ dependencies = [
 
 [[package]]
 name = "nucleation"
-version = "0.1.128"
+version = "0.1.130"
 dependencies = [
  "base64",
  "bytemuck",

{nucleation-0.1.128 → nucleation-0.1.130}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nucleation"
-version = "0.1.128"
+version = "0.1.130"
 edition = "2021"
 description = "A high-performance Minecraft schematic parser and utility library"
 authors = ["Nano nano@schem.at"]

{nucleation-0.1.128 → nucleation-0.1.130}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nucleation
-Version: 0.1.128
+Version: 0.1.130
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU Affero General Public License v3

{nucleation-0.1.128 → nucleation-0.1.130}/docs/README.md

@@ -70,6 +70,7 @@ These guides apply to all languages:
 | TypedCircuitExecutor | ✅   | ✅         | ⚠️     |
 | CircuitBuilder       | ✅   | ✅         | ⚠️     |
 | DefinitionRegion     | ✅   | ✅         | ⚠️     |
+| Insign DSL Support   | ✅   | ✅         | ⚠️     |
 | Custom IO Signals    | ✅   | ✅         | ⚠️     |
 
 **Legend:**

{nucleation-0.1.128 → nucleation-0.1.130}/docs/insign-io-integration.md

@@ -12,6 +12,8 @@ Instead of manually defining IO layouts in code, you can annotate your Minecraft
 4. Sort positions using distance-based or custom sorting strategies
 5. Create a fully configured `TypedCircuitExecutor`
 
+You can also use `import_insign_regions()` to simply extract regions into the schematic's metadata without creating an executor.
+
 ## Basic Usage
 
 ### 1. Annotate Your Schematic with Signs
@@ -45,6 +47,25 @@ let result = executor.execute(
 )?;
 ```
 
+### 3. Direct Region Import (Advanced)
+
+If you just want to populate the schematic's `definition_regions` from signs (e.g., for later use or serialization), use `import_insign_regions()`:
+
+```rust
+let mut schematic = /* load schematic */;
+
+// Extracts all Insign regions and stores them in schematic.definition_regions
+schematic.import_insign_regions()?;
+
+// Now you can access them directly
+if let Some(region) = schematic.definition_regions.get("io.counter") {
+    println!("Counter region volume: {}", region.volume());
+}
+
+// When you save the schematic, these regions will be persisted!
+let bytes = schematic.to_schematic()?;
+```
+
 ## Insign Syntax for IO
 
 ### Region Definition

{nucleation-0.1.128 → nucleation-0.1.130}/docs/rust/README.md

@@ -93,6 +93,32 @@ pub struct Region {
 }
 ```
 
+### DefinitionRegion
+
+A logical region defined by multiple bounding boxes, used for defining inputs, outputs, and other logical constructs.
+
+```rust
+pub struct DefinitionRegion {
+    pub boxes: Vec<BoundingBox>,
+    pub metadata: HashMap<String, String>,
+}
+```
+
+**Methods (Fluent API):**
+- `new() -> Self` - Create empty region
+- `from_bounds(min: (i32, i32, i32), max: (i32, i32, i32)) -> Self` - Create from bounds
+- `add_bounds(&mut self, min, max) -> &mut Self` - Add a bounding box
+- `add_point(&mut self, x, y, z) -> &mut Self` - Add a single point
+- `set_color(&mut self, color: u32) -> &mut Self` - Set visualization color
+- `with_metadata(&mut self, key, value) -> &mut Self` - Add metadata
+- `filter_by_block(&mut self, schematic, block_name) -> &mut Self` - Keep only matching blocks
+- `exclude_block(&mut self, schematic, block_name) -> &mut Self` - Remove matching blocks
+- `subtract(&mut self, other) -> &mut Self` - Boolean subtraction
+- `intersect(&mut self, other) -> &mut Self` - Boolean intersection
+- `union_into(&mut self, other) -> &mut Self` - Boolean union
+
+**Note:** Methods like `filter_by_block` require a reference to the `UniversalSchematic`. Due to Rust's borrowing rules, you may need to clone the region or build it separately before inserting it into the schematic if you need to filter based on the schematic's own blocks.
+
 ## Loading and Saving
 
 ### Litematic Format

{nucleation-0.1.128 → nucleation-0.1.130}/docs/shared/guide/definition-region.md

@@ -8,12 +8,13 @@
 2. [Accessing Region Data](#accessing-region-data)
 3. [Geometric Transformations](#geometric-transformations)
 4. [Boolean Operations](#boolean-operations)
-5. [Metadata](#metadata)
-6. [Connectivity Analysis](#connectivity-analysis)
-7. [Filtering with Schematics](#filtering-with-schematics)
-8. [Sort Strategies for Circuit Execution](#sort-strategies-for-circuit-execution)
-9. [Renderer Integration](#renderer-integration)
-10. [Best Practices](#best-practices)
+11. [Serialization & Persistence](#serialization--persistence)
+12. [Metadata](#metadata)
+13. [Connectivity Analysis](#connectivity-analysis)
+14. [Filtering with Schematics](#filtering-with-schematics)
+15. [Sort Strategies for Circuit Execution](#sort-strategies-for-circuit-execution)
+16. [Renderer Integration](#renderer-integration)
+17. [Best Practices](#best-practices)
 
 ---
 
@@ -240,7 +241,49 @@ combined = region_a.union(region_b);
 
 ---
 
-## Metadata
+## Serialization & Persistence
+
+Definition Regions can be serialized and embedded directly into schematic files. This allows you to define logical regions (like inputs, outputs, or documentation zones) that persist when the schematic is saved and loaded.
+
+### Supported Formats
+
+- **.litematic**: Stored in the `Metadata` compound tag.
+- **.schem (V3)**: Stored in the `Metadata` compound tag.
+- **.schem (V2)**: Legacy support via `Metadata` tag injection.
+
+### How it Works
+
+When you save a `UniversalSchematic`, its `definition_regions` map is serialized to JSON and stored in the schematic's metadata under the key `NucleationDefinitions`. When loading, this JSON is parsed back into full `DefinitionRegion` objects.
+
+### Example
+
+```rust
+// Rust
+let mut schematic = UniversalSchematic::new("MyCircuit".to_string());
+
+// Create a region
+let mut region = DefinitionRegion::new();
+region.add_bounds((0, 0, 0), (5, 5, 5));
+region.set_metadata("type", "input");
+
+// Add to schematic
+schematic.definition_regions.insert("MainInput".to_string(), region);
+
+// Save to file (region data is embedded)
+let data = schematic.to_schematic().unwrap();
+std::fs::write("circuit.schem", data).unwrap();
+
+// ... later ...
+
+// Load from file (region data is restored)
+let loaded = UniversalSchematic::from_schematic(&data).unwrap();
+let loaded_region = loaded.definition_regions.get("MainInput").unwrap();
+assert_eq!(loaded_region.get_metadata("type"), Some(&"input".to_string()));
+```
+
+This works seamlessly across all language bindings (Rust, JavaScript/WASM, Python).
+
+---
 
 Store arbitrary key-value data with regions:
 

{nucleation-0.1.128 → nucleation-0.1.130}/examples/rust.md

@@ -113,3 +113,50 @@ The Rust side does **not** re-export those symbols to avoid name clashes.
 * **Deterministic randomness**—chunk loading strategy `"Random"` hashes the
   schematic name, so the order is stable across runs.
 
+---
+
+## 6 · Definition Regions & Fluent API
+
+Nucleation provides a fluent API for defining logical regions within your schematic. This is useful for marking inputs, outputs, or other significant areas.
+
+### Basic Usage
+
+You can chain methods to define a region's properties:
+
+```rust
+schematic.create_region("my_region".to_string(), (0, 0, 0), (5, 5, 5))
+    .add_bounds((10, 0, 0), (15, 5, 5)) // Add disjoint area
+    .set_color(0xFF0000)                // Set visualization color
+    .with_metadata("type", "input");    // Add custom metadata
+```
+
+### Filtering Blocks (Borrow Checker Patterns)
+
+When filtering a region based on the blocks inside it (e.g., "keep only stone blocks"), you need to access the schematic's block data. In Rust, this creates a borrow checker challenge because the region is owned by the schematic.
+
+**Pattern A: Clone, Modify, Insert**
+Safest approach. Clone the region so you can borrow the schematic immutably while modifying the region.
+
+```rust
+if let Some(region) = schematic.definition_regions.get("layout") {
+    let mut region_clone = region.clone();
+    
+    // Now safe to borrow schematic immutably
+    region_clone.filter_by_block(&schematic, "minecraft:stone");
+    
+    // Update the schematic
+    schematic.definition_regions.insert("stone_only".to_string(), region_clone);
+}
+```
+
+**Pattern B: Build Before Inserting**
+Create the region independently, modify it, and then insert it into the schematic.
+
+```rust
+use nucleation::definition_region::DefinitionRegion;
+
+let mut new_region = DefinitionRegion::from_bounds((0,0,0), (5,5,5));
+new_region.exclude_block(&schematic, "minecraft:air");
+schematic.definition_regions.insert("non_air".to_string(), new_region);
+```
+

nucleation-0.1.130/examples/rust_fluent_api.rs

@@ -0,0 +1,50 @@
+use nucleation::definition_region::DefinitionRegion;
+use nucleation::UniversalSchematic;
+
+fn main() {
+    let mut schematic = UniversalSchematic::new("FluentRust".to_string());
+
+    // Setup some blocks
+    schematic.set_block_str(0, 0, 0, "minecraft:stone");
+    schematic.set_block_str(1, 0, 0, "minecraft:dirt");
+    schematic.set_block_str(2, 0, 0, "minecraft:stone");
+
+    // 1. Basic Fluent API (No dependency on schematic content)
+    // This works perfectly because we only borrow the region mutably (via the schematic),
+    // and we don't need to borrow the schematic again for these methods.
+    schematic
+        .create_region("layout".to_string(), (0, 0, 0), (2, 0, 0))
+        .add_bounds((0, 1, 0), (2, 1, 0))
+        .set_color(0xFF0000)
+        .with_metadata("description", "Main Layout");
+
+    println!("Created region 'layout'");
+
+    // 2. Advanced Fluent API (Filtering based on schematic content)
+    // In Rust, we cannot do:
+    // schematic.get_definition_region_mut("layout").filter_by_block(&schematic, "stone");
+    // Because `get_definition_region_mut` borrows `schematic` mutably,
+    // and `filter_by_block` needs to borrow `schematic` immutably.
+
+    // Pattern A: Clone the region, modify, and update (Safe, slightly slower)
+    if let Some(region) = schematic.definition_regions.get("layout") {
+        let mut region_clone = region.clone();
+
+        // Now we can pass &schematic because region_clone is separate
+        region_clone.filter_by_block(&schematic, "minecraft:stone");
+
+        // Update the schematic
+        schematic
+            .definition_regions
+            .insert("stone_only".to_string(), region_clone);
+    }
+
+    // Pattern B: Build region separately before inserting
+    let mut new_region = DefinitionRegion::from_bounds((0, 0, 0), (5, 5, 5));
+    new_region.exclude_block(&schematic, "minecraft:air");
+    schematic
+        .definition_regions
+        .insert("non_air".to_string(), new_region);
+
+    println!("Created filtered regions 'stone_only' and 'non_air'");
+}

{nucleation-0.1.128 → nucleation-0.1.130}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "nucleation"
-version = "0.1.128"
+version = "0.1.130"
 description = "A high-performance Minecraft schematic parser and utility library"
 authors = [{ name = "Nano", email = "nano@schem.at" }]
 license = { text = "AGPL-3.0-only" }