structura-core

Read and convert Minecraft structures.

Validated structure data, native format I/O and explicit conversion-loss reporting. Native formats need no Amulet Core translation engine.

The optional [world] extra reads bounded Java world regions and supports explicit block/entity patches with backups in Java 1.18+ saves.

Quick start

pip install structura-core
structura-convert house.litematic house.nbt
structura-convert house.nbt house.schem
structura-convert house.nbt house.snbt --strict

Formats

structura-convert reads all six formats and writes the first five. Java/Bedrock translation needs [bedrock] and can be lossy. Sponge v1 without a DataVersion requires --source-data-version when converting to another format; supply the source game's version, not the desired target.

The base package uses amulet-nbt for NBT parsing, NumPy for block data and portalocker for verified backup restore. The separate amulet-core translation dependency is installed only by [world], [legacy] or [bedrock].

Python

from structura_core import convert_structure, load_structure

structure = load_structure("house.litematic", region="Main")
print(structure.size, len(structure.present))
output = convert_structure(structure, "house.schem")
convert_structure("house.nbt", "house.snbt", strict=True)

convert_structure returns an absolute Path. Use Litematic, Schematic or Mcstructure document objects when native regions, metadata and unknown fields must survive a document copy.

Conversion rules

• Native Java conversion retains DataVersion; it does not upgrade game data.
• Omitted data produces ConversionWarning. --strict / strict=True rejects reported loss before writing; failed writes preserve an existing destination.
• Same-format native document copies retain their fields. Cross-format conversion cannot preserve metadata that the destination cannot represent.
• Java/Bedrock translation supports known vanilla blocks and waterlogging, omits ordinary entities and warns about block-entity fidelity. Its default target is 1.21.0.

pip install 'structura-core[bedrock]'
structura-convert house.nbt house.mcstructure --target-version 1.21.0

For old .schematic files, install [legacy] and use structura-convert-legacy old.schematic house.nbt --all-entities. The shared load_structure and structura-convert entry points also accept .schematic, retain all source entities, enforce their normal allocation limits and report normalization losses; strict mode rejects the conversion before writing. The legacy converter defaults to Java 1.21.1 and preserves selection bounds, air, materials and connections. --all-entities retains every source entity; otherwise only paintings and item frames are carried. Placement preparation belongs to structura-geo.

Documentation

• Release verification: installed packages, dependency upgrade and downstream checks.

• Migration to 0.6.1: changed analysis imports, legacy defaults and compatible package versions.

• Architecture: module responsibilities, data ownership and conversion stages.

• structura-geo: geometry, room and material metrics, morphology and placement preparation. Core has no dependency on geo or SciPy.

• Conversion guide: preservation rules, Litematic regions, Sponge metadata, limits and existing helpers.

• Format recipes: SNBT round trips, Sponge v1 source versions and the full Bedrock translation contract.

• structura-render: image, vector and 3D output from the same structures.

CLI commands support --help. Public entry points include type information for IDE completion. Interactive editing belongs to the separate structura-edit.