nucleation 0.1.126__tar.gz → 0.1.128__tar.gz

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

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

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

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

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

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

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

@@ -11,8 +11,9 @@
 5. [Metadata](#metadata)
 6. [Connectivity Analysis](#connectivity-analysis)
 7. [Filtering with Schematics](#filtering-with-schematics)
-8. [Renderer Integration](#renderer-integration)
-9. [Best Practices](#best-practices)
+8. [Sort Strategies for Circuit Execution](#sort-strategies-for-circuit-execution)
+9. [Renderer Integration](#renderer-integration)
+10. [Best Practices](#best-practices)
 
 ---
 
@@ -300,6 +301,150 @@ lit_lamps = region.filter_by_properties(schematic, { lit: "true" });
 
 ---
 
+## Sort Strategies for Circuit Execution
+
+When using `DefinitionRegion` for circuit IO, the order of positions determines bit assignment (position 0 = LSB). Use `SortStrategy` to control this ordering.
+
+### Available Strategies
+
+```javascript
+// JavaScript
+const { SortStrategyWrapper } = nucleation;
+
+// Axis-first ascending
+SortStrategyWrapper.yxz(); // Y first, then X, then Z (DEFAULT)
+SortStrategyWrapper.xyz(); // X first, then Y, then Z
+SortStrategyWrapper.zyx(); // Z first, then Y, then X
+
+// Axis-first descending (primary axis descending, others ascending)
+SortStrategyWrapper.yDescXZ(); // Y descending, then X, then Z
+SortStrategyWrapper.xDescYZ(); // X descending, then Y, then Z
+SortStrategyWrapper.zDescYX(); // Z descending, then Y, then X
+
+// Fully descending
+SortStrategyWrapper.descending(); // Y, X, Z all descending
+
+// Distance-based (useful for radial layouts)
+SortStrategyWrapper.distanceFrom(x, y, z); // Closest to (x,y,z) first
+SortStrategyWrapper.distanceFromDesc(x, y, z); // Farthest from (x,y,z) first
+
+// Order preservation
+SortStrategyWrapper.preserve(); // Keep order from region construction
+SortStrategyWrapper.reverse(); // Reverse the iteration order
+```
+
+```python
+# Python
+from nucleation import SortStrategy
+
+# Axis-first ascending
+SortStrategy.yxz()      # Y first, then X, then Z (DEFAULT)
+SortStrategy.xyz()      # X first, then Y, then Z
+SortStrategy.zyx()      # Z first, then Y, then X
+
+# Axis-first descending
+SortStrategy.y_desc_xz()  # Y descending, then X, then Z
+SortStrategy.x_desc_yz()  # X descending, then Y, then Z
+SortStrategy.z_desc_yx()  # Z descending, then Y, then X
+
+# Fully descending
+SortStrategy.descending()  # Y, X, Z all descending
+
+# Distance-based
+SortStrategy.distance_from(x, y, z)
+SortStrategy.distance_from_desc(x, y, z)
+
+# Order preservation
+SortStrategy.preserve()
+SortStrategy.reverse()
+```
+
+### Using with CircuitBuilder
+
+```javascript
+// JavaScript - Default sorting (YXZ)
+let builder = new CircuitBuilderWrapper(schematic).withInputAuto(
+	"data",
+	IoTypeWrapper.unsignedInt(8),
+	region
+);
+
+// Custom sorting (Y descending for top-to-bottom bit ordering)
+builder = new CircuitBuilderWrapper(schematic).withInputAutoSorted(
+	"data",
+	IoTypeWrapper.unsignedInt(8),
+	region,
+	SortStrategyWrapper.yDescXZ()
+);
+
+// Preserve box order (LSB in first box, MSB in second)
+const multiBoxRegion = DefinitionRegionWrapper.fromBoundingBoxes([
+	{ min: [0, 0, 0], max: [3, 0, 0] }, // Bits 0-3
+	{ min: [0, 0, 2], max: [3, 0, 2] }, // Bits 4-7
+]);
+builder = new CircuitBuilderWrapper(schematic).withInputAutoSorted(
+	"data",
+	IoTypeWrapper.unsignedInt(8),
+	multiBoxRegion,
+	SortStrategyWrapper.preserve()
+);
+
+// Distance-based (closest to sign position first)
+const signPos = [5, 2, 0];
+builder = new CircuitBuilderWrapper(schematic).withInputAutoSorted(
+	"data",
+	IoTypeWrapper.unsignedInt(8),
+	region,
+	SortStrategyWrapper.distanceFrom(...signPos)
+);
+```
+
+```python
+# Python - Default sorting (YXZ)
+builder = CircuitBuilder(schematic)
+builder.with_input_auto("data", IoType.unsigned_int(8), region)
+
+# Custom sorting (Y descending)
+builder = CircuitBuilder(schematic)
+builder.with_input_auto_sorted(
+    "data",
+    IoType.unsigned_int(8),
+    region,
+    SortStrategy.y_desc_xz()
+)
+
+# Preserve box order
+multi_box_region = DefinitionRegion.from_bounding_boxes([
+    ((0, 0, 0), (3, 0, 0)),  # Bits 0-3
+    ((0, 0, 2), (3, 0, 2)),  # Bits 4-7
+])
+builder = CircuitBuilder(schematic)
+builder.with_input_auto_sorted(
+    "data",
+    IoType.unsigned_int(8),
+    multi_box_region,
+    SortStrategy.preserve()
+)
+```
+
+### Parse from String
+
+```javascript
+// JavaScript
+const strategy = SortStrategyWrapper.fromString("y_desc");
+console.log(strategy.name); // "y_desc_x_z"
+```
+
+```python
+# Python
+strategy = SortStrategy.from_string("y_desc")
+print(strategy.name)  # "y_desc_x_z"
+```
+
+Valid strings: `"yxz"`, `"xyz"`, `"zyx"`, `"y_desc"`, `"x_desc"`, `"z_desc"`, `"descending"`, `"preserve"`, `"boxOrder"`, `"reverse"`
+
+---
+
 ## Renderer Integration
 
 This section provides patterns for integrating `DefinitionRegion` with 3D renderers.

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "nucleation"
-version = "0.1.126"
+version = "0.1.128"
 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.126 → nucleation-0.1.128}/release-artifacts/nucleation-original.js

@@ -470,6 +470,9 @@ export class CircuitBuilderWrapper {
     }
     /**
      * Add an input with full control
+     *
+     * Uses the default sort strategy (YXZ - Y first, then X, then Z).
+     * For custom ordering, use `withInputSorted`.
      * @param {string} name
      * @param {IoTypeWrapper} io_type
      * @param {LayoutFunctionWrapper} layout
@@ -522,6 +525,9 @@ export class CircuitBuilderWrapper {
     }
     /**
      * Add an output with full control
+     *
+     * Uses the default sort strategy (YXZ - Y first, then X, then Z).
+     * For custom ordering, use `withOutputSorted`.
      * @param {string} name
      * @param {IoTypeWrapper} io_type
      * @param {LayoutFunctionWrapper} layout
@@ -584,6 +590,9 @@ export class CircuitBuilderWrapper {
     }
     /**
      * Add an input with automatic layout inference
+     *
+     * Uses the default sort strategy (YXZ - Y first, then X, then Z).
+     * For custom ordering, use `withInputAutoSorted`.
      * @param {string} name
      * @param {IoTypeWrapper} io_type
      * @param {DefinitionRegionWrapper} region
@@ -618,6 +627,9 @@ export class CircuitBuilderWrapper {
     }
     /**
      * Add an output with automatic layout inference
+     *
+     * Uses the default sort strategy (YXZ - Y first, then X, then Z).
+     * For custom ordering, use `withOutputAutoSorted`.
      * @param {string} name
      * @param {IoTypeWrapper} io_type
      * @param {DefinitionRegionWrapper} region
@@ -635,6 +647,94 @@ export class CircuitBuilderWrapper {
         }
         return CircuitBuilderWrapper.__wrap(ret[0]);
     }
+    /**
+     * Add an input with full control and custom sort strategy
+     * @param {string} name
+     * @param {IoTypeWrapper} io_type
+     * @param {LayoutFunctionWrapper} layout
+     * @param {DefinitionRegionWrapper} region
+     * @param {SortStrategyWrapper} sort
+     * @returns {CircuitBuilderWrapper}
+     */
+    withInputSorted(name, io_type, layout, region, sort) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        _assertClass(io_type, IoTypeWrapper);
+        _assertClass(layout, LayoutFunctionWrapper);
+        _assertClass(region, DefinitionRegionWrapper);
+        _assertClass(sort, SortStrategyWrapper);
+        const ret = wasm.circuitbuilderwrapper_withInputSorted(ptr, ptr0, len0, io_type.__wbg_ptr, layout.__wbg_ptr, region.__wbg_ptr, sort.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return CircuitBuilderWrapper.__wrap(ret[0]);
+    }
+    /**
+     * Add an output with full control and custom sort strategy
+     * @param {string} name
+     * @param {IoTypeWrapper} io_type
+     * @param {LayoutFunctionWrapper} layout
+     * @param {DefinitionRegionWrapper} region
+     * @param {SortStrategyWrapper} sort
+     * @returns {CircuitBuilderWrapper}
+     */
+    withOutputSorted(name, io_type, layout, region, sort) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        _assertClass(io_type, IoTypeWrapper);
+        _assertClass(layout, LayoutFunctionWrapper);
+        _assertClass(region, DefinitionRegionWrapper);
+        _assertClass(sort, SortStrategyWrapper);
+        const ret = wasm.circuitbuilderwrapper_withOutputSorted(ptr, ptr0, len0, io_type.__wbg_ptr, layout.__wbg_ptr, region.__wbg_ptr, sort.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return CircuitBuilderWrapper.__wrap(ret[0]);
+    }
+    /**
+     * Add an input with automatic layout inference and custom sort strategy
+     * @param {string} name
+     * @param {IoTypeWrapper} io_type
+     * @param {DefinitionRegionWrapper} region
+     * @param {SortStrategyWrapper} sort
+     * @returns {CircuitBuilderWrapper}
+     */
+    withInputAutoSorted(name, io_type, region, sort) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        _assertClass(io_type, IoTypeWrapper);
+        _assertClass(region, DefinitionRegionWrapper);
+        _assertClass(sort, SortStrategyWrapper);
+        const ret = wasm.circuitbuilderwrapper_withInputAutoSorted(ptr, ptr0, len0, io_type.__wbg_ptr, region.__wbg_ptr, sort.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return CircuitBuilderWrapper.__wrap(ret[0]);
+    }
+    /**
+     * Add an output with automatic layout inference and custom sort strategy
+     * @param {string} name
+     * @param {IoTypeWrapper} io_type
+     * @param {DefinitionRegionWrapper} region
+     * @param {SortStrategyWrapper} sort
+     * @returns {CircuitBuilderWrapper}
+     */
+    withOutputAutoSorted(name, io_type, region, sort) {
+        const ptr = this.__destroy_into_raw();
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        _assertClass(io_type, IoTypeWrapper);
+        _assertClass(region, DefinitionRegionWrapper);
+        _assertClass(sort, SortStrategyWrapper);
+        const ret = wasm.circuitbuilderwrapper_withOutputAutoSorted(ptr, ptr0, len0, io_type.__wbg_ptr, region.__wbg_ptr, sort.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return CircuitBuilderWrapper.__wrap(ret[0]);
+    }
     /**
      * Create a new CircuitBuilder from a schematic
      * @param {SchematicWrapper} schematic
@@ -2922,6 +3022,171 @@ export class SimulationOptionsWrapper {
 }
 if (Symbol.dispose) SimulationOptionsWrapper.prototype[Symbol.dispose] = SimulationOptionsWrapper.prototype.free;
 
+const SortStrategyWrapperFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_sortstrategywrapper_free(ptr >>> 0, 1));
+/**
+ * Sort strategy for ordering positions in IO layouts
+ *
+ * Controls how positions are ordered when assigned to bits.
+ * Position 0 corresponds to bit 0 (LSB), position 1 to bit 1, etc.
+ */
+export class SortStrategyWrapper {
+
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(SortStrategyWrapper.prototype);
+        obj.__wbg_ptr = ptr;
+        SortStrategyWrapperFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        SortStrategyWrapperFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_sortstrategywrapper_free(ptr, 0);
+    }
+    /**
+     * Sort by Y descending, then X descending, then Z descending
+     * @returns {SortStrategyWrapper}
+     */
+    static descending() {
+        const ret = wasm.sortstrategywrapper_descending();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Parse sort strategy from string
+     *
+     * Accepts: "yxz", "xyz", "zyx", "y_desc", "x_desc", "z_desc",
+     *          "descending", "preserve", "reverse"
+     * @param {string} s
+     * @returns {SortStrategyWrapper}
+     */
+    static fromString(s) {
+        const ptr0 = passStringToWasm0(s, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.sortstrategywrapper_fromString(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return SortStrategyWrapper.__wrap(ret[0]);
+    }
+    /**
+     * Sort by Euclidean distance from a reference point (ascending)
+     * Closest positions first. Useful for radial layouts.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {SortStrategyWrapper}
+     */
+    static distanceFrom(x, y, z) {
+        const ret = wasm.sortstrategywrapper_distanceFrom(x, y, z);
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Sort by Euclidean distance from a reference point (descending)
+     * Farthest positions first.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {SortStrategyWrapper}
+     */
+    static distanceFromDesc(x, y, z) {
+        const ret = wasm.sortstrategywrapper_distanceFromDesc(x, y, z);
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Sort by X first (ascending), then Y, then Z
+     * @returns {SortStrategyWrapper}
+     */
+    static xyz() {
+        const ret = wasm.sortstrategywrapper_xyz();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Sort by Y first (ascending), then X, then Z
+     * Standard Minecraft layer-based ordering. This is the default.
+     * @returns {SortStrategyWrapper}
+     */
+    static yxz() {
+        const ret = wasm.sortstrategywrapper_yxz();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Sort by Z first (ascending), then Y, then X
+     * @returns {SortStrategyWrapper}
+     */
+    static zyx() {
+        const ret = wasm.iotypewrapper_float32();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Get the name of this strategy
+     * @returns {string}
+     */
+    get name() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.sortstrategywrapper_name(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Reverse of whatever order positions were added
+     * @returns {SortStrategyWrapper}
+     */
+    static reverse() {
+        const ret = wasm.sortstrategywrapper_reverse();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Preserve the order positions were added (no sorting)
+     * Useful when you've manually ordered positions or are using `fromBoundingBoxes`
+     * where box order matters.
+     * @returns {SortStrategyWrapper}
+     */
+    static preserve() {
+        const ret = wasm.sortstrategywrapper_preserve();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Sort by X first (descending), then Y ascending, then Z ascending
+     * @returns {SortStrategyWrapper}
+     */
+    static xDescYZ() {
+        const ret = wasm.sortstrategywrapper_xDescYZ();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Sort by Y first (descending), then X ascending, then Z ascending
+     * @returns {SortStrategyWrapper}
+     */
+    static yDescXZ() {
+        const ret = wasm.iotypewrapper_boolean();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+    /**
+     * Sort by Z first (descending), then Y ascending, then X ascending
+     * @returns {SortStrategyWrapper}
+     */
+    static zDescYX() {
+        const ret = wasm.sortstrategywrapper_zDescYX();
+        return SortStrategyWrapper.__wrap(ret);
+    }
+}
+if (Symbol.dispose) SortStrategyWrapper.prototype[Symbol.dispose] = SortStrategyWrapper.prototype.free;
+
 const StateModeConstantsFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_statemodeconstants_free(ptr >>> 0, 1));