nucleation
A high-performance Minecraft schematic engine, powered by a native Rust core. Parse, edit, diff, fingerprint, and generate schematics from Python.
Policy-driven normalization, material profiles, content inspection, UUID standardization, bounded decoding, and registry routing are documented in the complete transformation-policy guide.
Wheels are published for CPython 3.12+ (stable ABI) on Linux, macOS, and Windows.
They include a py.typed marker and generated .pyi stubs for Mypy, Pyright,
and editor completion. The installed package-level __init__.pyi explicitly
re-exports every generated native type, followed by the hand-written veneer
types; this keeps package exports equally visible to Mypy and Pyright while
preserving the native classes' type identities.
Install
pip install nucleation
Quick start
import nucleation
schematic = nucleation.Schematic.create("demo")
schematic.set_block(1, 2, 3, "minecraft:stone")
print(schematic.get_block_name(1, 2, 3)) # "minecraft:stone"
schematic.save_to_file("demo.litematic")
loaded = nucleation.Schematic.load_from_file("demo.litematic")
Normalize imported content
Preview and apply the same versioned policy contract used by every language binding:
from nucleation import Schematic, TransformPlan, inspect_transform, apply_transform
schematic = Schematic.open("incoming.schem")
plan = TransformPlan.registry_safe()
preview = inspect_transform(schematic, plan)
if not preview.rejected and not preview.quarantined:
report = apply_transform(schematic, plan)
schematic.save("normalized.schem")
Inspection never mutates the schematic. Apply is atomic: a rejecting rule
returns report.rejected == True and leaves the original unchanged. For only
lossless palette cleanup, use TransformPlan.canonical().
Split disconnected builds
Keep every meaningful connected machine independent while attaching only tiny, nearby loose parts:
schematic = nucleation.Schematic.open("combined.schem")
pieces = schematic.split_connected_attach_nearby(
16, # components this large always remain standalone
3, # tiny parts may attach across at most three empty blocks
)
for index in range(pieces.len()):
pieces.piece(index).save(f"machine-{index + 1}.schem")
Attachment is lossless and non-transitive: fragments cannot form a chain that recombines otherwise independent builds. Whole-world extraction, including the Python control plane and remote Store worker, is documented in the world-segmentation guide.
To emit every disconnected component literally, use a zero standalone threshold. Every component then becomes a core and the gap is ignored:
pieces = schematic.split_connected_attach_nearby(0, 0)
Curate a lossless corpus
Keep raw extraction lossless, then build registry and ranking views with an auditable policy. Every rejected ID and reason is retained:
from pathlib import Path
from nucleation import (
CurationPolicy,
curate_corpus,
write_registry_archives,
write_top_owner_archives,
)
policy = CurationPolicy.minima(
min_blocks=2, # reject standalone blocks
min_palette_names=2, # reject one-material schematics
name="ore-sanity-v1",
)
corpus = curate_corpus(Path("/data/ore"), Path("/data/ore/curation/ore-sanity-v1"), policy)
write_registry_archives(corpus, Path("/data/ore/registry-import"))
write_top_owner_archives(corpus, Path("/data/ore/top-20-owner-archives"))
CurationPolicy also accepts declarative MetricRule entries over analyser or
catalogue fields and named Python predicates. The policy receives a stable
SHA-256 content ID which is embedded into package indexes and owner manifests.
Changing a filter therefore cannot silently reuse an older curated result.
What is included
The published wheel contains the core feature set: schematic editing, all schematic formats, world import and export (including streaming), the schematic builder, the procedural building tool, definition regions, diff and fingerprinting, autostack, NBT helpers, SDF sampling, and the in-memory/filesystem store.
Redstone simulation, mesh generation, GPU rendering, and embedded scripting require building the package from source with the extra cargo features enabled (a Rust toolchain is required):
git clone https://github.com/Schem-at/Nucleation
cd Nucleation
pip install ./bindings/python
The source build defaults to the full feature set (bridge-full). Set the
NUCLEATION_FEATURES environment variable to choose a different cargo feature list,
for example NUCLEATION_FEATURES=bridge,simulation.
Documentation
License
MIT
Building a smaller feature set
Published wheels include bridge-full. A source build can select a smaller
Cargo feature set, including transitive dependencies:
NUCLEATION_FEATURES=bridge pip install --no-binary=nucleation nucleation
NUCLEATION_FEATURES=bridge,rendering,mc-tick pip install --no-binary=nucleation nucleation
bridge is required. Cargo's normal default features stay enabled. Disabled
features omit their Python types and methods, including animation rendering
methods. Enable scripting-lua or scripting-js explicitly when needed; a
minimal build requires neither scripting engine. Selection reads the same
Cargo feature definitions and Rust bridge gates for checkouts and sdists.
On Android/Termux, the build explicitly links the interpreter library and
android/log. Install matching Python development libraries; a missing
interpreter library fails configuration. Ordinary Linux/macOS extensions keep
nanobind's module linkage, without imposing a new libpython dependency.
Native errors
Catch nucleation.NucleationError for engine failures and inspect error.code
against nucleation.NucleationErrorCode constants. This also applies to
nucleation.core and the open/save convenience methods. Python argument
errors are not converted into engine errors.
1 maintainer
Metadata
1 maintainer
Release files for nucleation 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| nucleation-0.12.0.tar.gz | 3.0 MB | Without provenance | Details |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nucleation-0.12.0-cp312-abi3-win_amd64.whl | CPython 3.12 | abi3 | Windows x86-64 | Details |
| nucleation-0.12.0-cp312-abi3-manylinux_2_28_x86_64.whl | CPython 3.12 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| nucleation-0.12.0-cp312-abi3-macosx_11_0_arm64.whl | CPython 3.12 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 47.4 MB
Release files / nucleation-0.12.0.tar.gz
| Download URL | nucleation-0.12.0.tar.gz |
|---|---|
| Size | 3.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ade12f71233002d93eeb89bfc4bf9f49f27c02bb9cbec41e33a7da9df9031fb8
|
|
BLAKE2b-256 checksum How to use checksums |
97712a11daf0b0e3710c6126343a4e2ba1de3841bfbc4aad6ea98f9a5e72d547
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / nucleation-0.12.0-cp312-abi3-win_amd64.whl
| Download URL | nucleation-0.12.0-cp312-abi3-win_amd64.whl |
|---|---|
| Size | 12.3 MB |
| Tags | CPython 3.12 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
e90ca78bbb6a79dda5785f0f1d45ec62bbd635a40d25a4d2044d8d4cfcf0873a
|
|
BLAKE2b-256 checksum How to use checksums |
4c9d31a5e14b082430aabd65475077b417b152ba5d37209149bbb4851d396d03
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / nucleation-0.12.0-cp312-abi3-manylinux_2_28_x86_64.whl
| Download URL | nucleation-0.12.0-cp312-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 17.5 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
da51e74420e43921876e5ef07435606373e45606d235923702cff2cf277fd9ef
|
|
BLAKE2b-256 checksum How to use checksums |
b6b4772ea9cdbfed726e1757d24a595583e0042dc45fcb530d90caa09a39839f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / nucleation-0.12.0-cp312-abi3-macosx_11_0_arm64.whl
| Download URL | nucleation-0.12.0-cp312-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 14.5 MB |
| Tags | CPython 3.12 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
8152d0e2025acc42b57e821ab230a55013afae7c85a293d6fac225b87623466a
|
|
BLAKE2b-256 checksum How to use checksums |
76dede442aafb2a1e78a4a99f54870b0c185eca6c90c67bea8f56834e841c7e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for nucleation 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
