nucleation 0.1.128__tar.gz → 0.1.129__tar.gz

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

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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nucleation
-Version: 0.1.128
+Version: 0.1.129
 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.129}/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.129}/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.129}/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.129}/pyproject.toml

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

{nucleation-0.1.128 → nucleation-0.1.129}/release-artifacts/package.json

@@ -5,7 +5,7 @@
     "Nano nano@schem.at"
   ],
   "description": "A high-performance Minecraft schematic parser and utility library",
-  "version": "0.1.128",
+  "version": "0.1.129",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

{nucleation-0.1.128 → nucleation-0.1.129}/src/formats/litematic.rs

@@ -146,6 +146,13 @@ fn create_metadata(schematic: &UniversalSchematic) -> NbtCompound {
 
     metadata.insert("Software", NbtTag::String("UniversalSchematic".to_string()));
 
+    // Add NucleationDefinitions if present
+    if !schematic.definition_regions.is_empty() {
+        if let Ok(json) = serde_json::to_string(&schematic.definition_regions) {
+            metadata.insert("NucleationDefinitions", NbtTag::String(json));
+        }
+    }
+
     metadata
 }
 fn create_regions(schematic: &UniversalSchematic) -> NbtCompound {
@@ -303,6 +310,13 @@ fn parse_metadata(
 
     // We don't need to parse EnclosingSize, TotalVolume, TotalBlocks as they will be recalculated
 
+    // Parse NucleationDefinitions
+    if let Ok(json) = metadata.get::<_, &str>("NucleationDefinitions") {
+        if let Ok(regions) = serde_json::from_str(json) {
+            schematic.definition_regions = regions;
+        }
+    }
+
     Ok(())
 }
 

{nucleation-0.1.128 → nucleation-0.1.129}/src/formats/schematic.rs

@@ -1,3 +1,4 @@
+use std::collections::HashMap;
 use std::fmt;
 use std::io::{BufReader, Cursor, Read};
 
@@ -208,7 +209,15 @@ pub fn to_schematic_v3(
     schematic_data.insert("Entities", NbtTag::List(entities));
 
     // Add metadata
-    schematic_data.insert("Metadata", schematic.metadata.to_nbt());
+    let mut metadata_tag = schematic.metadata.to_nbt();
+    if !schematic.definition_regions.is_empty() {
+        if let NbtTag::Compound(ref mut metadata_compound) = metadata_tag {
+            if let Ok(json) = serde_json::to_string(&schematic.definition_regions) {
+                metadata_compound.insert("NucleationDefinitions", NbtTag::String(json));
+            }
+        }
+    }
+    schematic_data.insert("Metadata", metadata_tag);
 
     // Create the proper root structure with "Schematic" tag
     let mut root = NbtCompound::new();
@@ -281,7 +290,16 @@ pub fn to_schematic_v2(
     schematic_data.insert("BlockEntities", NbtTag::List(block_entities));
     schematic_data.insert("Entities", NbtTag::List(entities));
 
-    schematic_data.insert("Metadata", schematic.metadata.to_nbt());
+    // Add metadata
+    let mut metadata_tag = schematic.metadata.to_nbt();
+    if !schematic.definition_regions.is_empty() {
+        if let NbtTag::Compound(ref mut metadata_compound) = metadata_tag {
+            if let Ok(json) = serde_json::to_string(&schematic.definition_regions) {
+                metadata_compound.insert("NucleationDefinitions", NbtTag::String(json));
+            }
+        }
+    }
+    schematic_data.insert("Metadata", metadata_tag);
 
     // Create the proper root structure with "Schematic" tag
     let mut root = NbtCompound::new();
@@ -412,7 +430,14 @@ pub fn from_schematic(data: &[u8]) -> Result<UniversalSchematic, Box<dyn std::er
     let schem = root.get::<_, &NbtCompound>("Schematic").unwrap_or(&root);
     let schem_version = schem.get::<_, i32>("Version")?;
 
+    let mut definition_regions = HashMap::new();
+
     let name = if let Some(metadata) = schem.get::<_, &NbtCompound>("Metadata").ok() {
+        if let Ok(json) = metadata.get::<_, &str>("NucleationDefinitions") {
+            if let Ok(regions) = serde_json::from_str(json) {
+                definition_regions = regions;
+            }
+        }
         metadata.get::<_, &str>("Name").ok().map(|s| s.to_string())
     } else {
         None
@@ -422,6 +447,7 @@ pub fn from_schematic(data: &[u8]) -> Result<UniversalSchematic, Box<dyn std::er
     let mc_version = schem.get::<_, i32>("DataVersion").ok();
 
     let mut schematic = UniversalSchematic::new(name);
+    schematic.definition_regions = definition_regions;
     schematic.metadata.mc_version = mc_version;
 
     let width = schem.get::<_, i16>("Width")? as u32;

{nucleation-0.1.128 → nucleation-0.1.129}/src/universal_schematic.rs

@@ -2,6 +2,7 @@ use crate::block_entity::BlockEntity;
 use crate::block_position::BlockPosition;
 use crate::bounding_box::BoundingBox;
 use crate::chunk::Chunk;
+use crate::definition_region::DefinitionRegion;
 use crate::entity::Entity;
 use crate::metadata::Metadata;
 use crate::region::Region;
@@ -19,6 +20,8 @@ pub struct UniversalSchematic {
     pub default_region: Region,
     pub other_regions: HashMap<String, Region>,
     pub default_region_name: String,
+    #[serde(default = "HashMap::new")]
+    pub definition_regions: HashMap<String, DefinitionRegion>,
     #[serde(skip, default = "HashMap::new")]
     block_state_cache: HashMap<String, BlockState>,
 }
@@ -58,6 +61,7 @@ impl UniversalSchematic {
             default_region: Region::new(default_region_name.clone(), (0, 0, 0), (1, 1, 1)),
             other_regions: HashMap::new(),
             default_region_name,
+            definition_regions: HashMap::new(),
             block_state_cache: HashMap::new(),
         }
     }
@@ -641,7 +645,18 @@ impl UniversalSchematic {
     pub fn to_nbt(&self) -> NbtCompound {
         let mut root = NbtCompound::new();
 
-        root.insert("Metadata", self.metadata.to_nbt());
+        let mut metadata_tag = self.metadata.to_nbt();
+
+        // Serialize definition regions to JSON string and store in Metadata
+        if !self.definition_regions.is_empty() {
+            if let NbtTag::Compound(ref mut metadata_compound) = metadata_tag {
+                if let Ok(json) = serde_json::to_string(&self.definition_regions) {
+                    metadata_compound.insert("NucleationDefinitions", NbtTag::String(json));
+                }
+            }
+        }
+
+        root.insert("Metadata", metadata_tag);
 
         // Create combined regions for NBT
         let mut regions_tag = NbtCompound::new();
@@ -660,10 +675,19 @@ impl UniversalSchematic {
     }
 
     pub fn from_nbt(nbt: NbtCompound) -> Result<Self, String> {
-        let metadata = Metadata::from_nbt(
-            nbt.get::<_, &NbtCompound>("Metadata")
-                .map_err(|e| format!("Failed to get Metadata: {}", e))?,
-        )?;
+        let metadata_tag = nbt
+            .get::<_, &NbtCompound>("Metadata")
+            .map_err(|e| format!("Failed to get Metadata: {}", e))?;
+
+        let metadata = Metadata::from_nbt(metadata_tag)?;
+
+        // Try to parse definition regions from Metadata
+        let mut definition_regions = HashMap::new();
+        if let Ok(json) = metadata_tag.get::<_, &str>("NucleationDefinitions") {
+            if let Ok(regions) = serde_json::from_str(json) {
+                definition_regions = regions;
+            }
+        }
 
         let regions_tag = nbt
             .get::<_, &NbtCompound>("Regions")
@@ -695,10 +719,68 @@ impl UniversalSchematic {
             default_region,
             other_regions,
             default_region_name,
+            definition_regions,
             block_state_cache: HashMap::new(),
         })
     }
 
+    pub fn import_insign_regions(&mut self) -> Result<(), String> {
+        let json_value = crate::insign::compile_schematic_insign(self)
+            .map_err(|e| format!("Insign compilation error: {}", e))?;
+
+        if let Some(regions_map) = json_value.as_object() {
+            for (name, data) in regions_map {
+                let mut def_region = DefinitionRegion::new();
+
+                // Parse bounding boxes
+                if let Some(boxes) = data.get("bounding_boxes").and_then(|v| v.as_array()) {
+                    for bbox_json in boxes {
+                        if let Some(coords) = bbox_json.as_array() {
+                            if coords.len() >= 2 {
+                                let min_arr = coords[0].as_array();
+                                let max_arr = coords[1].as_array();
+
+                                if let (Some(min), Some(max)) = (min_arr, max_arr) {
+                                    if min.len() == 3 && max.len() == 3 {
+                                        let min_tuple = (
+                                            min[0].as_i64().unwrap_or(0) as i32,
+                                            min[1].as_i64().unwrap_or(0) as i32,
+                                            min[2].as_i64().unwrap_or(0) as i32,
+                                        );
+                                        let max_tuple = (
+                                            max[0].as_i64().unwrap_or(0) as i32,
+                                            max[1].as_i64().unwrap_or(0) as i32,
+                                            max[2].as_i64().unwrap_or(0) as i32,
+                                        );
+                                        def_region.add_bounds(min_tuple, max_tuple);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+
+                // Parse metadata
+                if let Some(meta) = data.get("metadata").and_then(|v| v.as_object()) {
+                    for (key, value) in meta {
+                        // Convert value to string
+                        let val_str = match value {
+                            serde_json::Value::String(s) => s.clone(),
+                            serde_json::Value::Number(n) => n.to_string(),
+                            serde_json::Value::Bool(b) => b.to_string(),
+                            _ => value.to_string(),
+                        };
+                        def_region.set_metadata(key, val_str);
+                    }
+                }
+
+                self.definition_regions.insert(name.clone(), def_region);
+            }
+        }
+
+        Ok(())
+    }
+
     pub fn get_default_region_mut(&mut self) -> &mut Region {
         &mut self.default_region
     }

nucleation-0.1.129/tests/definition_regions_test.rs

@@ -0,0 +1,187 @@
+use nucleation::block_entity::BlockEntity;
+use nucleation::definition_region::DefinitionRegion;
+use nucleation::utils::NbtValue;
+use nucleation::{BlockState, UniversalSchematic};
+use std::collections::HashMap;
+
+#[test]
+fn test_definition_regions_roundtrip_chain() {
+    // 1. Forge a Universal Schematic
+    let mut original = UniversalSchematic::new("Roundtrip Test".to_string());
+
+    // Add some blocks
+    original.set_block(0, 0, 0, BlockState::new("minecraft:stone".to_string()));
+    original.set_block(1, 1, 1, BlockState::new("minecraft:dirt".to_string()));
+
+    // Add Definition Regions
+    let mut def_region_a = DefinitionRegion::new();
+    def_region_a.add_bounds((0, 0, 0), (5, 5, 5));
+    def_region_a.set_metadata("type", "input");
+    def_region_a.set_metadata("signal", "redstone");
+
+    let mut def_region_b = DefinitionRegion::new();
+    def_region_b.add_bounds((10, 10, 10), (15, 15, 15));
+    def_region_b.set_metadata("type", "output");
+
+    original
+        .definition_regions
+        .insert("InputA".to_string(), def_region_a);
+    original
+        .definition_regions
+        .insert("OutputB".to_string(), def_region_b);
+
+    // 2. Roundtrip to .schem (V3)
+    let schem_data = original
+        .to_schematic()
+        .expect("Failed to serialize to .schem");
+    let from_schem =
+        UniversalSchematic::from_schematic(&schem_data).expect("Failed to deserialize from .schem");
+
+    // Verify consistency
+    verify_consistency(&original, &from_schem, "Original -> Schem");
+
+    // 3. Roundtrip from the loaded schematic to .litematic
+    let litematic_data = nucleation::litematic::to_litematic(&from_schem)
+        .expect("Failed to serialize to .litematic");
+    let from_litematic = nucleation::litematic::from_litematic(&litematic_data)
+        .expect("Failed to deserialize from .litematic");
+
+    // Verify consistency
+    verify_consistency(&from_schem, &from_litematic, "Schem -> Litematic");
+
+    // 4. Verify original vs final
+    verify_consistency(&original, &from_litematic, "Original -> Final");
+}
+
+#[test]
+fn test_schematic_v2_definition_regions() {
+    let mut original = UniversalSchematic::new("V2 Test".to_string());
+    original.set_block(0, 0, 0, BlockState::new("minecraft:stone".to_string()));
+
+    let mut def_region = DefinitionRegion::new();
+    def_region.add_bounds((0, 0, 0), (1, 1, 1));
+    def_region.set_metadata("test", "v2");
+    original
+        .definition_regions
+        .insert("TestV2".to_string(), def_region);
+
+    // Explicitly use V2
+    let schem_data = nucleation::schematic::to_schematic_version(
+        &original,
+        nucleation::schematic::SchematicVersion::V2,
+    )
+    .expect("Failed to serialize to .schem v2");
+
+    let from_schem = UniversalSchematic::from_schematic(&schem_data)
+        .expect("Failed to deserialize from .schem v2");
+
+    verify_consistency(&original, &from_schem, "Original -> Schem V2");
+}
+
+#[test]
+fn test_insign_integration() {
+    let mut schematic = UniversalSchematic::new("Insign Test".to_string());
+
+    // Create a sign that defines a region via Insign syntax
+    // @region_name=rc([min],[max])
+    // #region_name:key=value
+    let mut sign = BlockEntity::new("minecraft:sign".to_string(), (0, 0, 0));
+    sign.nbt.insert(
+        "Text1".to_string(),
+        NbtValue::String(r##"{"text":"@my_region"}"##.to_string()),
+    );
+    sign.nbt.insert(
+        "Text2".to_string(),
+        NbtValue::String(r##"{"text":"=rc([0,0,0],"}"##.to_string()),
+    );
+    sign.nbt.insert(
+        "Text3".to_string(),
+        NbtValue::String(r##"{"text":"[5,5,5])"}"##.to_string()),
+    );
+    sign.nbt.insert(
+        "Text4".to_string(),
+        NbtValue::String(r##"{"text":"#my_region:k=\"v\""}"##.to_string()),
+    );
+
+    schematic.add_block_entity(sign);
+
+    // Run import
+    schematic
+        .import_insign_regions()
+        .expect("Failed to import insign regions");
+
+    // Verify
+    assert!(schematic.definition_regions.contains_key("my_region"));
+    let region = schematic.definition_regions.get("my_region").unwrap();
+
+    // Check bounds (should be 0,0,0 to 5,5,5)
+    let bounds = region.get_bounds().unwrap();
+    assert_eq!(bounds.min, (0, 0, 0));
+    assert_eq!(bounds.max, (5, 5, 5));
+
+    // Check metadata
+    assert_eq!(region.get_metadata("k"), Some(&"v".to_string()));
+}
+
+fn verify_consistency(expected: &UniversalSchematic, actual: &UniversalSchematic, stage: &str) {
+    assert_eq!(
+        expected.definition_regions.len(),
+        actual.definition_regions.len(),
+        "{}: Region count mismatch",
+        stage
+    );
+
+    for (name, exp_region) in &expected.definition_regions {
+        assert!(
+            actual.definition_regions.contains_key(name),
+            "{}: Missing region '{}'",
+            stage,
+            name
+        );
+        let act_region = actual.definition_regions.get(name).unwrap();
+
+        // Compare metadata
+        assert_eq!(
+            exp_region.metadata, act_region.metadata,
+            "{}: Metadata mismatch for region '{}'",
+            stage, name
+        );
+
+        // Compare boxes count
+        assert_eq!(
+            exp_region.boxes.len(),
+            act_region.boxes.len(),
+            "{}: Box count mismatch for region '{}'",
+            stage,
+            name
+        );
+
+        // Compare total volume as a proxy for box geometry (exact box order might vary depending on impl details, though here it should be exact)
+        assert_eq!(
+            exp_region.volume(),
+            act_region.volume(),
+            "{}: Volume mismatch for region '{}'",
+            stage,
+            name
+        );
+
+        // Compare exact boxes (assuming order is preserved by serialization which it should be for Vec)
+        for (i, (exp_box, act_box)) in exp_region
+            .boxes
+            .iter()
+            .zip(act_region.boxes.iter())
+            .enumerate()
+        {
+            assert_eq!(
+                exp_box.min, act_box.min,
+                "{}: Box {} min mismatch for region '{}'",
+                stage, i, name
+            );
+            assert_eq!(
+                exp_box.max, act_box.max,
+                "{}: Box {} max mismatch for region '{}'",
+                stage, i, name
+            );
+        }
+    }
+}