structura-core 0.2.2__tar.gz → 0.2.3__tar.gz

structura_core-0.2.3/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: structura-core
+Version: 0.2.3
+Summary: Validated Minecraft Structure NBT I/O, legacy conversion and voxel geometry
+Project-URL: Repository, https://github.com/kirimba1024/structura-core
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: amulet-nbt<3,>=2.1
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<2,>=1.13
+Provides-Extra: legacy
+Requires-Dist: amulet-core<2,>=1.9; extra == "legacy"
+
+# structura-core
+
+Reusable Minecraft Java 1.21.1 structure-processing core. It owns:
+
+- validated Java Structure NBT I/O;
+- legacy schematic conversion and numeric analysis;
+- NumPy/SciPy voxel geometry primitives (connected components, closing).
+
+Structure input accepts gzip-compressed and raw NBT, including files with
+multiple palettes. Saving preserves all palettes, root metadata, additional
+block fields, block entities and entities. Repeated saves of the same data
+produce reproducible gzip bytes; they need not match the original file bytes.
+
+The library targets Minecraft Java 1.21.1 by default. Version constants live
+in `structura_core.version`; callers can still pass an explicit Amulet
+translation target to the legacy converter.
+
+```bash
+pip install structura-core
+structura-analyze path/to/structure.nbt --json
+```
+
+The `legacy` extra is needed for legacy input conversion. Structure NBT
+processing and Sponge v2 `.schem` export do not require `amulet-core`.
+
+```bash
+pip install 'structura-core[legacy]'
+structura-convert-legacy old.schematic structure.nbt
+structura-export-schematic structure.nbt structure.schem
+```
+
+For local development, use `pip install -e '.[legacy]'` from this package's
+directory.
+
+Legacy conversion keeps paintings and item frames by default, which is safe
+for generated structures. Preview tools can call `convert(...,
+preserve_all_entities=True)` to retain mobs, armor stands and loose items as
+well, including their exact fractional positions and NBT payloads.
+
+For conversion that retains selection bounds, authored air, bedrock and block
+connections, pass `prepare_for_placement=False` as well, or use:
+
+```bash
+structura-convert-legacy old.schematic preserved.nbt --preserve-layout --all-entities
+```
+
+The converter's historical default still prepares a structure for datapack
+placement: it trims bounds, replaces bedrock, repairs pane/bar connections and
+selects interior/door-clearance air. Preview tools use the preserving mode.
+Conversion retains custom entity namespaces and supplies translated block
+entity IDs, allowing the result to be exported as Sponge without guessing IDs.
+
+Generated `additions` fill missing cells and preserve authored cells, including
+explicit air. Use `replacements` to intentionally replace a cell; replacement
+also removes its old block entity NBT. Coordinates and palette indices must be
+integers in the NBT range. Every saved block is bounds-checked, and a failed
+write leaves an existing destination intact.
+
+```python
+from structura_core import Structure, save_structure
+from structura_core.export_schematic import export_schematic
+
+structure = Structure("house.nbt", palette_index=0)
+save_structure(structure, "copy.nbt", structure.size)
+export_schematic(structure, "house.schem")
+```
+
+Selecting `palette_index` chooses the active view without discarding the other
+palettes on save. An integer addition selects the corresponding variant in
+each palette; a string such as `"minecraft:stone"` adds that literal state to
+every palette. Shifts update entity positions and known vanilla hanging-entity
+coordinates, while retaining unrelated custom NBT.
+
+Sponge v2 has a single palette and a dense block array: export uses the selected
+palette and fills missing cells with air. Entities and block entity payloads
+are included; an entity without an `id` raises an error. This export does not
+translate Minecraft versions, and the output retains the source `DataVersion`.

structura_core-0.2.3/README.md

@@ -0,0 +1,77 @@
+# structura-core
+
+Reusable Minecraft Java 1.21.1 structure-processing core. It owns:
+
+- validated Java Structure NBT I/O;
+- legacy schematic conversion and numeric analysis;
+- NumPy/SciPy voxel geometry primitives (connected components, closing).
+
+Structure input accepts gzip-compressed and raw NBT, including files with
+multiple palettes. Saving preserves all palettes, root metadata, additional
+block fields, block entities and entities. Repeated saves of the same data
+produce reproducible gzip bytes; they need not match the original file bytes.
+
+The library targets Minecraft Java 1.21.1 by default. Version constants live
+in `structura_core.version`; callers can still pass an explicit Amulet
+translation target to the legacy converter.
+
+```bash
+pip install structura-core
+structura-analyze path/to/structure.nbt --json
+```
+
+The `legacy` extra is needed for legacy input conversion. Structure NBT
+processing and Sponge v2 `.schem` export do not require `amulet-core`.
+
+```bash
+pip install 'structura-core[legacy]'
+structura-convert-legacy old.schematic structure.nbt
+structura-export-schematic structure.nbt structure.schem
+```
+
+For local development, use `pip install -e '.[legacy]'` from this package's
+directory.
+
+Legacy conversion keeps paintings and item frames by default, which is safe
+for generated structures. Preview tools can call `convert(...,
+preserve_all_entities=True)` to retain mobs, armor stands and loose items as
+well, including their exact fractional positions and NBT payloads.
+
+For conversion that retains selection bounds, authored air, bedrock and block
+connections, pass `prepare_for_placement=False` as well, or use:
+
+```bash
+structura-convert-legacy old.schematic preserved.nbt --preserve-layout --all-entities
+```
+
+The converter's historical default still prepares a structure for datapack
+placement: it trims bounds, replaces bedrock, repairs pane/bar connections and
+selects interior/door-clearance air. Preview tools use the preserving mode.
+Conversion retains custom entity namespaces and supplies translated block
+entity IDs, allowing the result to be exported as Sponge without guessing IDs.
+
+Generated `additions` fill missing cells and preserve authored cells, including
+explicit air. Use `replacements` to intentionally replace a cell; replacement
+also removes its old block entity NBT. Coordinates and palette indices must be
+integers in the NBT range. Every saved block is bounds-checked, and a failed
+write leaves an existing destination intact.
+
+```python
+from structura_core import Structure, save_structure
+from structura_core.export_schematic import export_schematic
+
+structure = Structure("house.nbt", palette_index=0)
+save_structure(structure, "copy.nbt", structure.size)
+export_schematic(structure, "house.schem")
+```
+
+Selecting `palette_index` chooses the active view without discarding the other
+palettes on save. An integer addition selects the corresponding variant in
+each palette; a string such as `"minecraft:stone"` adds that literal state to
+every palette. Shifts update entity positions and known vanilla hanging-entity
+coordinates, while retaining unrelated custom NBT.
+
+Sponge v2 has a single palette and a dense block array: export uses the selected
+palette and fills missing cells with air. Entities and block entity payloads
+are included; an entity without an `id` raises an error. This export does not
+translate Minecraft versions, and the output retains the source `DataVersion`.

{structura_core-0.2.2 → structura_core-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "structura-core"
-version = "0.2.2"
+version = "0.2.3"
 description = "Validated Minecraft Structure NBT I/O, legacy conversion and voxel geometry"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -29,3 +29,9 @@ where = ["src"]
 
 [project.urls]
 Repository = "https://github.com/kirimba1024/structura-core"
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]

{structura_core-0.2.2 → structura_core-0.2.3}/src/structura_core/__init__.py

@@ -3,4 +3,4 @@
 from .nbt import AIR_NAMES, Structure, parse_state, save_structure, state_key
 
 __all__ = ["AIR_NAMES", "Structure", "parse_state", "save_structure", "state_key"]
-__version__ = "0.2.2"
+__version__ = "0.2.3"

{structura_core-0.2.2 → structura_core-0.2.3}/src/structura_core/analyze.py

@@ -266,9 +266,7 @@ class StructureAnalyzer:
         """Unlike dirt/stone/grass, bedrock is never a deliberate material
         choice in a curated build -- its only realistic source is a
         WorldEdit selection that reached all the way down to the world
-        floor. Found by inspecting a real rejected asset (2026-09-01,
-        [Obturonius]peakfortress -- rejected live as "ugly", turned out to
-        be 32.7% bedrock): a stronger, unambiguous version of the natural-
+        floor. This is a stronger, unambiguous version of the natural-
         terrain heuristic above, worth its own warning rather than being
         folded into that one fuzzier signal."""
         hist = self.block_histogram()
@@ -388,9 +386,7 @@ class StructureAnalyzer:
     # ---- G. environment fit -- material-palette voting, the same
     #  technique natural_terrain_fraction already uses, just against
     #  different curated block sets. A guess to narrow human/AI attention,
-    #  not a verdict -- e.g. this is the kind of signal that could have
-    #  flagged davegr_house_cave's mismatch (heavy glass/wood, low stone)
-    #  ahead of the live in-game rejection recorded in its notes. --------
+    #  not a verdict. ----------------------------------------------------
 
     _WATER_BLOCKS = {
         "minecraft:prismarine",
@@ -730,7 +726,7 @@ class StructureAnalyzer:
             warnings.append(
                 f"bedrock: {bf * 100:.1f}% of blocks -- almost never a deliberate "
                 f"material choice, near-certain sign the selection reached the "
-                f"world floor (see [Obturonius]peakfortress, rejected live at 32.7%)"
+                "world floor"
             )
         return warnings
 

{structura_core-0.2.2 → structura_core-0.2.3}/src/structura_core/convert_legacy.py

@@ -25,7 +25,7 @@ from amulet_nbt import (
     StringTag,
 )
 
-from .nbt import load_root, write_root
+from .nbt import _integer, load_root, write_root
 from .version import DATA_VERSION, JAVA_VERSION
 
 # Blocks that are never a deliberate material choice in a curated
@@ -265,14 +265,27 @@ def convert(
     target_version=JAVA_VERSION,
     quiet_errors: bool = True,
     preserve_all_entities: bool = False,
+    *,
+    prepare_for_placement: bool = True,
 ):
+    """Translate legacy input; optionally apply the established placement cleanup.
+
+    Set prepare_for_placement=False for previews or format conversion that must
+    retain the selection's size, air, authored materials and connections.
+    The historical default remains available for existing datapack pipelines.
+    """
+    data_version = _integer(data_version, "DataVersion")
     if len(target_version) != 3 or any(part < 0 for part in target_version):
         raise ValueError(f"invalid Java target version: {target_version!r}")
+    target_version = tuple(_integer(part, "Java version component") for part in target_version)
+    logger = logging.getLogger("amulet")
+    previous_level = logger.level
+    level = None
     if quiet_errors:
-        logging.getLogger("amulet").setLevel(logging.CRITICAL)
+        logger.setLevel(logging.CRITICAL)
 
-    level = amulet.load_level(src_path)
     try:
+        level = amulet.load_level(src_path)
         dim = level.dimensions[0]
         bounds = level.bounds(dim)
         (minx, miny, minz), (maxx, maxy, maxz) = bounds.min, bounds.max
@@ -301,13 +314,16 @@ def convert(
 
                     # universal air with stray legacy block_data properties
                     # (WorldEdit metadata leftovers) collapses to plain air.
-                    if block.base_name == "air":
-                        air_positions.add(pos)
-                        continue
+                    if block.base_name == "air" and block.namespace in {"minecraft", "universal_minecraft"}:
+                        if not prepare_for_placement:
+                            block = amulet.Block("minecraft", "air")
+                        else:
+                            air_positions.add(pos)
+                            continue
                     replacement = FORCED_REPLACEMENTS.get(
                         (block.namespace, block.base_name)
                     )
-                    if replacement is not None:
+                    if prepare_for_placement and replacement is not None:
                         block = amulet.Block(*replacement)
                     if block.namespace == "universal_minecraft":
                         raise ValueError(
@@ -337,6 +353,7 @@ def convert(
                     entry_nbt = None
                     if block_entity is not None:
                         entry_nbt = block_entity.nbt.compound.copy()
+                        entry_nbt["id"] = StringTag(block_entity.namespaced_name)
                         block_entities_count += 1
 
                     blocks.append((pos, idx, entry_nbt))
@@ -345,96 +362,98 @@ def convert(
         legacy_entities = _legacy_entities(legacy_root, preserve_all_entities)
         legacy_text = _legacy_tile_text(legacy_root)
 
-        # Trim the bounding box to the actual building. The source
-        # .schematic's WorldEdit selection is usually padded well beyond the
-        # real structure (the original builder eyeballing a region), and
-        # `size` isn't just cosmetic -- terrain_adaptation's skirt and
-        # dimension_padding both operate over the full declared footprint,
-        # so a loose bounding box drags the terrain-blending staircase out
-        # across empty margin where there's no building at all.
-        trim_positions = [p for p, _, _ in blocks]
-        if preserve_all_entities:
-            trim_positions.extend(
-                tuple(int(value // 1) for value in pos)
-                for pos, _payload in legacy_entities
-                if all(
-                    0 <= value < limit
-                    for value, limit in zip(pos, (size_x, size_y, size_z))
+        ox = oy = oz = 0
+        if prepare_for_placement:
+            # Trim the bounding box to the actual building. The source
+            # .schematic's WorldEdit selection is usually padded well beyond the
+            # real structure (the original builder eyeballing a region), and
+            # `size` isn't just cosmetic -- terrain_adaptation's skirt and
+            # dimension_padding both operate over the full declared footprint,
+            # so a loose bounding box drags the terrain-blending staircase out
+            # across empty margin where there's no building at all.
+            trim_positions = [p for p, _, _ in blocks]
+            if preserve_all_entities:
+                trim_positions.extend(
+                    tuple(int(value // 1) for value in pos)
+                    for pos, _payload in legacy_entities
+                    if all(
+                        0 <= value < limit
+                        for value, limit in zip(pos, (size_x, size_y, size_z))
+                    )
                 )
+            if not trim_positions:
+                raise ValueError(
+                    f"source contains no renderable blocks or entities: {src_path}"
+                )
+            bx = [p[0] for p in trim_positions]
+            by = [p[1] for p in trim_positions]
+            bz = [p[2] for p in trim_positions]
+            ox, oy, oz = min(bx), min(by), min(bz)
+            new_size_x, new_size_y, new_size_z = (
+                max(bx) - ox + 1,
+                max(by) - oy + 1,
+                max(bz) - oz + 1,
             )
-        if not trim_positions:
-            raise ValueError(
-                f"source contains no renderable blocks or entities: {src_path}"
-            )
-        bx = [p[0] for p in trim_positions]
-        by = [p[1] for p in trim_positions]
-        bz = [p[2] for p in trim_positions]
-        ox, oy, oz = min(bx), min(by), min(bz)
-        new_size_x, new_size_y, new_size_z = (
-            max(bx) - ox + 1,
-            max(by) - oy + 1,
-            max(bz) - oz + 1,
-        )
-        if (ox, oy, oz) != (0, 0, 0) or (new_size_x, new_size_y, new_size_z) != (
-            size_x,
-            size_y,
-            size_z,
-        ):
-            print(
-                f"    trimmed bounding box: {size_x}x{size_y}x{size_z} -> "
-                f"{new_size_x}x{new_size_y}x{new_size_z} (offset {ox},{oy},{oz})"
+            if (ox, oy, oz) != (0, 0, 0) or (new_size_x, new_size_y, new_size_z) != (
+                size_x,
+                size_y,
+                size_z,
+            ):
+                print(
+                    f"    trimmed bounding box: {size_x}x{size_y}x{size_z} -> "
+                    f"{new_size_x}x{new_size_y}x{new_size_z} (offset {ox},{oy},{oz})"
+                )
+                blocks = [
+                    ((x - ox, y - oy, z - oz), idx, nbt) for (x, y, z), idx, nbt in blocks
+                ]
+                air_positions = {
+                    (x - ox, y - oy, z - oz)
+                    for (x, y, z) in air_positions
+                    if ox <= x <= ox + new_size_x - 1
+                    and oy <= y <= oy + new_size_y - 1
+                    and oz <= z <= oz + new_size_z - 1
+                }
+                size_x, size_y, size_z = new_size_x, new_size_y, new_size_z
+
+            # Air: exterior (open padding around the building) is omitted so it
+            # doesn't carve a crater into destination terrain; interior (fully
+            # enclosed pockets -- real rooms) is placed explicitly so those
+            # rooms get hollowed out even when the piece lands partway inside a
+            # hill and would otherwise show raw terrain poking through.
+            blocks, pane_fixes = _fix_pane_bar_connections(
+                blocks, palette_list, palette_index
             )
-            blocks = [
-                ((x - ox, y - oy, z - oz), idx, nbt) for (x, y, z), idx, nbt in blocks
-            ]
-            air_positions = {
-                (x - ox, y - oy, z - oz)
-                for (x, y, z) in air_positions
-                if ox <= x <= ox + new_size_x - 1
-                and oy <= y <= oy + new_size_y - 1
-                and oz <= z <= oz + new_size_z - 1
-            }
-            size_x, size_y, size_z = new_size_x, new_size_y, new_size_z
-
-        # Air: exterior (open padding around the building) is omitted so it
-        # doesn't carve a crater into destination terrain; interior (fully
-        # enclosed pockets -- real rooms) is placed explicitly so those
-        # rooms get hollowed out even when the piece lands partway inside a
-        # hill and would otherwise show raw terrain poking through.
-        blocks, pane_fixes = _fix_pane_bar_connections(
-            blocks, palette_list, palette_index
-        )
-        if pane_fixes:
-            print(f"    pane/bars connection fixes: {pane_fixes}")
+            if pane_fixes:
+                print(f"    pane/bars connection fixes: {pane_fixes}")
 
-        solid_positions = {pos for pos, _, _ in blocks}
-        exterior_air, interior_air = _split_exterior_interior_air(
-            air_positions, solid_positions, size_x, size_y, size_z
-        )
+            solid_positions = {pos for pos, _, _ in blocks}
+            exterior_air, interior_air = _split_exterior_interior_air(
+                air_positions, solid_positions, size_x, size_y, size_z
+            )
 
-        door_air = _door_clearance(
-            blocks,
-            palette_list,
-            (size_x, size_y, size_z),
-            solid_positions,
-            interior_air,
-        )
-        air_to_place = interior_air | door_air
-        if air_to_place:
-            air_idx = palette_index.get("minecraft:air")
-            if air_idx is None:
-                air_idx = len(palette_list)
-                palette_index["minecraft:air"] = air_idx
-                comp = CompoundTag()
-                comp["Name"] = StringTag("minecraft:air")
-                palette_list.append(comp)
-            for pos in air_to_place:
-                blocks.append((pos, air_idx, None))
-        print(
-            f"    air: {len(exterior_air)} exterior (omitted), "
-            f"{len(interior_air)} interior, "
-            f"{len(door_air)} door-clearance (placed explicitly)"
-        )
+            door_air = _door_clearance(
+                blocks,
+                palette_list,
+                (size_x, size_y, size_z),
+                solid_positions,
+                interior_air,
+            )
+            air_to_place = interior_air | door_air
+            if air_to_place:
+                air_idx = palette_index.get("minecraft:air")
+                if air_idx is None:
+                    air_idx = len(palette_list)
+                    palette_index["minecraft:air"] = air_idx
+                    comp = CompoundTag()
+                    comp["Name"] = StringTag("minecraft:air")
+                    palette_list.append(comp)
+                for pos in air_to_place:
+                    blocks.append((pos, air_idx, None))
+            print(
+                f"    air: {len(exterior_air)} exterior (omitted), "
+                f"{len(interior_air)} interior, "
+                f"{len(door_air)} door-clearance (placed explicitly)"
+            )
 
         shifted_text = {
             (tx - ox, ty - oy, tz - oz): lines
@@ -478,7 +497,7 @@ def convert(
         entities_tag = ListTag()
         for (ex, ey, ez), payload in legacy_entities:
             pos = (ex - ox, ey - oy, ez - oz)
-            if not all(
+            if prepare_for_placement and not all(
                 0 <= v < limit for v, limit in zip(pos, (size_x, size_y, size_z))
             ):
                 continue
@@ -495,7 +514,12 @@ def convert(
         print(f"    blocks written: {len(blocks)}")
         print(f"    block entities: {block_entities_count}")
     finally:
-        level.close()
+        try:
+            if level is not None:
+                level.close()
+        finally:
+            if quiet_errors:
+                logger.setLevel(previous_level)
 
 
 LEGACY_ENTITIES = {
@@ -666,15 +690,21 @@ def _legacy_entities(root, preserve_all=False):
     root = _schematic_root(root)
     for entry in root.get("Entities") or []:
         data = _entity_data(entry)
-        legacy = str(data.get("id") or data.get("Id") or "").split(":")[-1]
+        identifier = str(data.get("id") or data.get("Id") or "")
+        namespace, separator, legacy = identifier.partition(":")
+        if not separator:
+            legacy, namespace = namespace, ""
         key = legacy.replace("_", "").lower()
         kind = (LEGACY_ENTITY_ALIASES if preserve_all else LEGACY_ENTITIES).get(key)
+        custom = bool(namespace and namespace != "minecraft")
+        if custom:
+            kind = identifier if preserve_all else None
         if kind is None and preserve_all and legacy:
             snake = re.sub(r"(?<!^)(?=[A-Z])", "_", legacy).replace(".", "_").lower()
             kind = f"minecraft:{snake}"
         if kind is None:
             continue
-        hanging = key in LEGACY_ENTITIES
+        hanging = not custom and key in LEGACY_ENTITIES
         if hanging:
             try:
                 pos = tuple(
@@ -715,6 +745,11 @@ def main():
     ap.add_argument("src", help="legacy .schematic path")
     ap.add_argument("dst", help="output vanilla structure .nbt path")
     ap.add_argument("--data-version", type=int, default=DATA_VERSION)
+    ap.add_argument(
+        "--preserve-layout", action="store_true",
+        help="preserve selection bounds, air, materials and connections instead of placement cleanup",
+    )
+    ap.add_argument("--all-entities", action="store_true", help="retain every source entity")
     ap.add_argument(
         "--target-version",
         default="1.21.1",
@@ -727,7 +762,11 @@ def main():
         ap.error("--target-version must contain three integers, for example 1.21.1")
     if len(target_version) != 3:
         ap.error("--target-version must contain three integers, for example 1.21.1")
-    convert(args.src, args.dst, args.data_version, target_version)
+    convert(
+        args.src, args.dst, args.data_version, target_version,
+        preserve_all_entities=args.all_entities,
+        prepare_for_placement=not args.preserve_layout,
+    )
 
 
 if __name__ == "__main__":

structura_core-0.2.3/src/structura_core/export_schematic.py

@@ -0,0 +1,108 @@
+"""Export Structure NBT as Sponge Schematic v2, including entities."""
+
+import argparse
+from copy import deepcopy
+from pathlib import Path
+
+import numpy as np
+from amulet_nbt import (
+    ByteArrayTag, CompoundTag, DoubleTag, IntArrayTag, IntTag, ListTag,
+    ShortTag, StringTag,
+)
+
+from .nbt import Structure, state_key, write_root
+
+
+def _encode_varints(values):
+    data = bytearray()
+    for value in values:
+        value = int(value)
+        while value > 127:
+            data.append((value & 127) | 128)
+            value >>= 7
+        data.append(value)
+    return bytes(data)
+
+
+def schematic_root(src):
+    """Build a v2 payload using the selected palette; omitted cells become air.
+
+    Sponge has one palette and a dense block array. Other Structure palettes
+    and the distinction between omitted cells and air are not representable.
+    """
+    src.validate()
+    sx, sy, sz = src.size
+    if any(value > 65535 for value in src.size):
+        raise ValueError("Sponge v2 dimensions must fit an unsigned short (1..65535)")
+
+    dedup_index = {}
+    remap = []
+    for entry in src.palette_raw:
+        key = state_key(entry)
+        remap.append(dedup_index.setdefault(key, len(dedup_index)))
+
+    air_index = dedup_index.setdefault("minecraft:air", len(dedup_index))
+    indices = np.full((sx, sy, sz), air_index, dtype=np.uint32)
+    for pos, index in src.present.items():
+        indices[pos] = remap[index]
+    # Sponge order is x + z * Width + y * Width * Length.
+    block_data = _encode_varints(np.transpose(indices, (1, 2, 0)).ravel())
+
+    block_entities = ListTag()
+    for pos, nbt in src.block_nbt.items():
+        if "id" not in nbt:
+            raise ValueError(f"block entity at {pos} has no id for Sponge export")
+        if not isinstance(nbt["id"], StringTag) or not str(nbt["id"]):
+            raise ValueError(f"block entity at {pos} needs a non-empty string id for Sponge export")
+        entry = deepcopy(nbt)
+        entry["Id"] = StringTag(str(entry.pop("id")))
+        entry["Pos"] = IntArrayTag(list(pos))
+        block_entities.append(entry)
+
+    entities = ListTag()
+    for record in src.entities:
+        entry = deepcopy(record["nbt"])
+        if "id" not in entry:
+            raise ValueError("entity has no id for Sponge export")
+        if not isinstance(entry["id"], StringTag) or not str(entry["id"]):
+            raise ValueError("entity needs a non-empty string id for Sponge export")
+        entry["Id"] = StringTag(str(entry.pop("id")))
+        entry["Pos"] = ListTag([DoubleTag(value.py_data) for value in record["pos"]])
+        entities.append(entry)
+
+    return CompoundTag({
+        "Version": IntTag(2),
+        "DataVersion": IntTag(src.data_version),
+        "Width": ShortTag(sx if sx < 32768 else sx - 65536),
+        "Height": ShortTag(sy if sy < 32768 else sy - 65536),
+        "Length": ShortTag(sz if sz < 32768 else sz - 65536),
+        "Offset": IntArrayTag([0, 0, 0]),
+        "Palette": CompoundTag({key: IntTag(i) for key, i in dedup_index.items()}),
+        "PaletteMax": IntTag(len(dedup_index)),
+        "BlockData": ByteArrayTag(np.frombuffer(block_data, dtype=np.int8)),
+        "BlockEntities": block_entities,
+        "Entities": entities,
+    })
+
+
+def export_schematic(src, destination):
+    """Write a Sponge v2 file without requiring the legacy conversion extra."""
+    destination = Path(destination)
+    write_root(schematic_root(src), destination, name="Schematic")
+    return destination
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("src")
+    parser.add_argument("dst")
+    parser.add_argument("--palette", type=int, default=0, help="Structure palette to export")
+    args = parser.parse_args()
+
+    src = Structure(args.src, palette_index=args.palette)
+    export_schematic(src, args.dst)
+    print(f"{args.dst} size={src.size} blocks={len(src.present)} entities={len(src.entities)}")
+
+
+if __name__ == "__main__":
+    main()