Metadata-Version: 2.4
Name: structura-core
Version: 0.3.0
Summary: Validated Minecraft Structure NBT and Litematic I/O, 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;
- native Litematic v5, v6 and v7 reading and writing;
- 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.
Native I/O retains the source Minecraft `DataVersion` and does not upgrade
block states or entity payloads between game versions.

```bash
pip install structura-core
structura-analyze path/to/structure.nbt --json
```

## Native conversion

```bash
structura-convert house.litematic house.nbt
structura-convert house.nbt house.litematic
structura-convert house.litematic house.schem --region Main
```

These commands need only the base package. Litematic is parsed directly with
the existing NBT dependency. Litemapy is used to produce an interoperability
test fixture, and is not an installation dependency.

```python
from structura_core import Litematic, Structure, export_litematic, load_structure

document = Litematic("house.litematic")
print(document.region_names)
structure = load_structure("house.litematic", region="Main")
export_litematic(structure, "house-copy.litematic")

structure = Structure.from_bytes(nbt_bytes)
structure = Structure.from_root(nbt_compound)
```

`from_root` owns a copy; caller-owned NBT is not modified. Both in-memory
constructors use the same validation as `Structure(path)`.

| Operation | Preserved / conversion rules |
|---|---|
| `Litematic(path).save(output)` | All native regions, metadata, pending ticks and unknown NBT fields; gzip bytes are reproducible. |
| `Litematic.to_structure()` | Block states, block entities, entity payloads and positions; all disjoint regions share one bounding box. |
| `load_structure(path, region="Main")` | One named Litematic region; blocks are normalized to nonnegative local coordinates. `source_origin` maps them back to schematic coordinates. |
| `export_litematic(structure, output)` | One region at `(0,0,0)`, using the selected palette. Missing cells become `minecraft:structure_void`, the no-placement marker; explicit air remains air. |

Negative region sizes do not mirror the blocks. Entity positions and block
positions use different Litematic coordinate conventions, both handled by the
reader. Overlapping regions are rejected instead of depending on file order;
choose a region explicitly. Unsupported versions and malformed arrays fail
with a `ValueError`.

Cross-format conversion does not preserve Litematic region names/layout,
placement origin, preview, scheduling ticks or arbitrary document metadata in
Structure NBT. Keep the native `Litematic` document when these matter.
Litematic export uses the active Structure palette; other palette variants and
additional Structure block-record fields are not representable there.
Minecraft entity `id` values are required for export. No IDs are guessed.

Native Litematic decoding and encoding default to at most 2,000,000 cells,
checked before unpacking or allocating block arrays. Raise `max_blocks` in
Python or `--max-blocks` in the converter for trusted larger files. This is an
allocation guard, not a sandbox for arbitrary untrusted compressed files.

## Stable responsibilities

`nbt.py` owns Structure validation and serialization; `litematic.py` adapts the
native format; `formats.py` selects the reader; `convert.py` supplies the CLI.
Readers retain block state IDs and properties rather than maintaining another
Minecraft registry. A game upgrade does not silently rewrite source data.

New editing tools and interactive navigation belong to a separate future
`structura-edit` package. Existing generation helpers remain available for
compatibility.

## Legacy input and existing helpers

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`.
