schematica
Health Warn
- No license — Repository has no license file
- Description — Repository has a description
- Active repo — Last push 41 days ago
- Low visibility — Only 5 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
AI skill for generating Minecraft Java Edition schematics with Python, voxel geometry, procedural builders, previews, and Sponge/MCEdit/Litematica export.
Schematica
Python toolkit and interactive REPL for building Minecraft Java Edition
schematics, packaged as an AI skill. Compose geometry primitives, shapely
polygons, trimesh meshes, heightmaps, boolean ops, and procedural generators
into structures, with session-based editing (undo/redo), multi-view PNG
previews, and Sponge .schem, MCEdit .schematic, and Litematica .litematic
export. Version 0.2 adds an advanced map-design toolkit: 12 themed design
palettes, terrain-draped roads/rivers, MST road networks, plazas with
fountains, towers with crenellated roofs, bridges with piers and lamps, seeded
ruin/decay passes, lighting lattices, 3D-noise cave carving, WorldEdit-style
weighted replace patterns, and preview colors derived from the real vanilla
textures. The AI agent is the creative driver: it uses this toolkit to realize
the user's request.
Install
The toolkit lives under scripts/. Install from there:
cd scripts
pip install -e .[dev]
Or runtime deps only:
pip install -r scripts/requirements.txt
For minecraft-data block catalogs, vendor the PrismarineJS repo at the repo or
skill root, or point SCHEMATICA_MINECRAFT_DATA at any clone:
git clone https://github.com/PrismarineJS/minecraft-data minecraft_data
Without it, a built-in fallback block list is used (519 blocks incl. wood,
copper, colored and modern-decor families) shipped as editable JSON atscripts/schematica/blocks/data/fallback_blocks.json
(SCHEMATICA_FALLBACK_BLOCKS overrides). Previews pick colors from a bundled
texture-derived table; regenerate per version withpython -m schematica.blocks.colors <mc_version>.
Quick start (library)
from schematica.session.session import Session
from schematica.shapes.primitives import Box, Sphere, Cylinder
s = Session.new((32, 32, 32), version="1.20.1")
s.add(Box(0, 0, 0, 31, 0, 31), "minecraft:stone") # floor
s.add(Box(2, 1, 2, 6, 5, 6), "minecraft:oak_planks") # hut walls
s.add(Sphere(16, 18, 16, 6), "minecraft:glass") # dome
s.subtract(Cylinder(16, 1, 16, 2, 0, 20)) # carve a shaft
s.replace("minecraft:stone", "minecraft:polished_andesite")
from schematica.export.sponge import write_sponge
write_sponge(s.grid, "build.schem")
from schematica.render.preview import preview
preview(s.grid, "previews") # writes top/front/right/iso PNGs
Quick start (REPL)
Set PYTHONPATH=scripts (or pip install -e scripts/ first):
python -m schematica
Or run a script non-interactively:
python -m schematica --script build.txt
Example script:
session.new size=24x24x24 version=1.20.1
add.box frm=0,0,0 to=23,0,23 block=minecraft:stone
add.box frm=0,0,0 to=23,8,23 block=minecraft:dirt
replace src=minecraft:dirt dst=minecraft:grass_block
add.sphere center=12,14,12 r=5 block=minecraft:glass hollow=true
add.cylinder center=12,1,12 r=1 h=8 block=minecraft:oak_log
subtract.box frm=11,9,11 to=13,12,13
stats
export path=build.schem
preview out_dir=previews
Commands
| Command | Args | Notes |
|---|---|---|
session.new |
size=WxHxD version=V fill=B |
start fresh |
add.box |
frm=x,y,z to=x,y,z block=B hollow=true |
filled or shell |
add.sphere |
center=x,y,z r=N block=B hollow=true |
|
add.cylinder |
center=x,y,z r=N h=N block=B hollow=true |
vertical (y) axis |
subtract.box |
frm=x,y,z to=x,y,z |
carve air |
replace |
src=B dst=B |
global find/replace |
paint |
(mask) block=B |
repaint existing solids |
paint.ramp |
palette=P frm=A to=B axis=y blend=0.15 |
dark->light palette gradient |
road |
points=x,z;x,z width=3 palette=P border=B |
terrain-draped road |
river |
points=x,z;x,z width=3 depth=3 bed=B |
carve + flood channel |
roof.gable / roof.hip |
frm=A to=B palette=P stairs=S |
pitched roofs over wall boxes |
tree2 / forest |
at=x,z kind=spruce / frm=A to=B density=0.05 |
seeded vegetation |
surface |
x=N z=N |
top solid height probe |
palette.list / palette.info |
themed design palettes | |
flatten |
frm=A to=B cap=B |
level build pad (median height) |
plaza |
center=x,z radius=R palette=P |
banded plaza + fountain |
road.net |
points=x,z;x,z width=3 |
MST-connected road network |
tower / battlements |
at=x,z r=4 roof=cone / frm=A to=B |
towers, crenellation |
bridge |
points=x,z;x,z pier_spacing=6 |
elevated deck + piers + lamps |
ruin |
frm=A to=B amount=0.35 |
seeded collapse + rubble |
lighting |
frm=A to=B spacing=7 |
lantern lattice |
caves |
frm=A to=B threshold=0.6 protect=3 |
3D Perlin cave carving |
replace.mix |
src=B pattern="3x a, 1x b" |
weighted find/replace |
fill |
block=B |
fill entire grid |
clear |
all air | |
mirror |
axis=x|y|z |
|
rotate |
times=N axes=xy|xz|yz |
90° increments |
clone.translate |
frm=A to=B offset=dx,dy,dz count=N |
repeat a source box |
clone.cardinal |
frm=A to=B center=x,z |
copy a quadrant/corner to the other 3 rotations |
undo / redo |
history | |
stats |
shape/volume/solid/palette | |
preview |
out_dir=DIR |
top/front/right/iso PNG |
export |
path=FILE.schem |
Sponge v2 |
export.mcedit |
path=FILE.schematic |
legacy 1.12-era MCEdit |
export.litematic |
path=FILE.litematic |
Litematica |
save / load |
path=FILE.json |
native session |
help |
list commands | |
exit |
quit REPL |
Shape toolkit
Primitives: Box, Sphere, Ellipsoid, Cylinder, Cone, Pyramid, Torus, Plane, Wedge, Line, Dome, Helix, Arch, Spiral, Staircase, BezierCurve (16 shapes).
Cylinder, Cone, and Dome accept an axis argument ("x"|"y"|"z") so horizontal
cones / wall-mounted domes are one-liners; Cylinder also accepts start/end
aliases for the along-axis extent (clearer than y0/y1 for non-Y axes). Arch
accepts a plane argument ("xy"|"xz"|"yz") so an arch can lie in any
coordinate plane.
Boolean: Union, Intersect, Subtract, Xor.
SDF smooth blending: SDFShape, SmoothUnion, SmoothIntersect, SmoothSubtract
(signed-distance-field composition with a k-voxel blend radius; k=0 is the
hard boolean op). Uses scipy when available, pure-numpy fallback otherwise.
Polygon (shapely + SVG): Extrude a 2D polygon into a prism along x/y/z. Load
from WKT, GeoJSON, a .json file, or an SVG path d-string
(e.g. "M 0 0 H 10 V 10 H 0 Z" — supports M/L/H/V/C/Q/Z).
Mesh (trimesh): MeshShape voxelizes any OBJ/STL/glTF into the grid.
Heightmap: Heightmap from a 2D array or from_image(path).
Transforms: Translated, Mirror, Rotated90, Rotated (any angle, not just 90°),Array (repeat), NoiseDeformed, Shell.
Session features
add/subtract/intersect/paintforward**shape_kwargsto the
shape's dataclass fields viadataclasses.replace— sos.add(Sphere(...), "stone", hollow=True)works. Unknown kwargs raiseTypeErrorlisting the valid fields.enable_symmetry(axis, center=None)/disable_symmetry(): live mirror
decorator. When enabled, every subsequent add/subtract/paint is automatically
unioned with its mirror image aboutcenter(grid middle by default) alongaxis.symmetry_activeis a read-only property.enable_radial_symmetry(folds=4, plane="xz", center=None)/enable_quad_symmetry(center=None): live rotational cloning. Every
subsequent add/subtract/paint is unioned with its rotations aboutcenter
(grid middle by default) in the named plane.folds=4→ quad,folds=8→
octo,folds=2→ half-turn. Uses the exactRotated90transform for the
default centre; falls back to an exact index-map rotation for offset centres.resample_subregion(frm, to, new_size, block, dest_origin=None): nearest-
neighbour rescale of a sub-box tonew_size, written atdest_origin.set_box/set_many: fast bulk write paths for procedural detail.undo/redo(delta-based history),save/loadsession JSON.marker(name, x, y, z, kind)/region(name, corner, size, kind)/export_markers(path)for annotations.paint_gradient,edge_wear,surface_scatterfor organic detail.walkable_at,clearance_at,is_connected,reachable_area,shortest_pathfor spatial / walkability analysis.
Generators
terrain_heightmap(shape, seed, amplitude, scale)— Perlin-based surface.apply_terrain(session, ...)— fills stone+dirt+grass top layer.apply_tree(session, x, z, height)— trunk + leaf canopy.generate.wfc— wave function collapse from a caller-provided block palette.texture.palette— noise-driven material mix on existing solids.
Architecture
scripts/
schematica/
blocks/ Block, BlockRegistry (minecraft-data JSON + enriched fallback)
core/ VoxelGrid, Palette, ChunkedGrid (sparse big-map backend)
shapes/ primitives, polygon (shapely+SVG), mesh, heightmap,
transforms, boolean, sdf (smooth blending)
generators/ noise, templates, replace, retexture, texture, wfc
procedural/ detail (gradient / edge wear / surface scatter)
analysis/ spatial (walkability / pathfinding)
render/ matplotlib voxel preview -> PNG
export/ Sponge .schem, MCEdit .schematic, Litematica .litematic,
report, validation, materials
constraints.py declarative build constraints
session/ Session, History, Commands (40+ commands)
cli/ REPL, parser, validation
tests/ developer test suite (320+ tests)
references/ docs loaded on demand
Developer notes
Internal conventions
- Sponge block ordering:
index = (y*length + z)*width + x, varint-encoded. - History: deltas store only changed voxels (coords + old/new), so undo of
a 32³ grid where a 3³ box was added touches only 27 voxels. - Preview color map: texture-derived bundled table (~987 blocks, averaged
from vanilla textures) -> per-version cache ->SCHEMATICA_BLOCK_COLORS
override -> variant-family fallback -> stable hash. Seereferences/preview_rendering.md. - Bulk procedural writes: use
Session.set_box(...)andSession.set_many(...)
for high-volume generated detail instead of thousands of tiny shape masks. - Determinism: all procedural generators take a
seed; pin it in tests. - Kwargs delegation:
Session.add/subtract/paint/intersectforward**shape_kwargsto the shape viadataclasses.replace. Unknown kwargs
raiseTypeErrorwith a clear list of valid fields. - Active symmetry:
enable_symmetrywraps each shape in aUnion((shape, Translated(Mirror(shape), ...)))automatically; the wrapper
is rebuilt on every op so the mirror follows the current grid shape. - SDF distance transform:
schematica.shapes.sdf._mask_to_sdfusesscipy.ndimage.distance_transform_edtwhen available; otherwise a pure-numpy
iterative-erosion BFS. Fully-filled masks get a constant negative distance
soSmoothSubtracton a fully-filled box doesn't hang.
Failure modes to watch
- Python 3.14 + amulet-core: amulet-core's C++ extensions may lack wheels on
very new Python. The default backend isnbtlib(pure Python) which works on
3.11-3.14. Installamulet-coreonly on 3.11-3.13. - Large grids: matplotlib 3D voxel preview is comfortable around ~32³.
Larger dense grids automatically use downsampled 2D projected previews;
chunked grids render projected previews without materialising dense arrays.
Projected fallbackisowritespreview_iso_projected.png. - Backslashes in REPL scripts: shlex treats
\as escape. Use forward
slashes inpath=arguments, or quote the whole path. - minecraft-data submodule missing: the registry falls back to a compact
built-in block list with common structural, resource, mapmaking, colored, and
stateful detail blocks, plus the Phase 12 quartz family, concrete slabs/stairs
for all 16 colors, and ~40 stone-variant slabs/stairs (deepslate, tuff,
calcite, blackstone, prismarine, end stone brick, mossy stone brick/cobble-
stone, granite, diorite, andesite, polished deepslate). Validate full-fidelity
builds against a vendoredminecraft_data/. - Legacy versions: for 1.7-1.12 colored blocks, prefer MCEdit
.schematic.
Sponge export warns when a pre-1.13data_versionis paired with modern
flattened blockstate names. MCEdit export warns when a non-air block has no
legacy ID mapping; usestrict=Trueto fail instead.
Extending the toolkit
- Add a shape: implement the
Shapeprotocol (def mask(shape) -> ndarray)
in a new file underscripts/schematica/shapes/. - Add a generator: add a function in
scripts/schematica/generators/templates.py
that takes aSessionand applies shapes. Pin aseedfor determinism. - Add an exporter: add
scripts/schematica/export/<format>.pymirroringsponge.py. - Add a CLI command: register a
CommandSpecinscripts/schematica/session/commands.py
with arg specs and a handler that calls aSessionmethod.
Testing
cd scripts
python -m pytest tests -q
python -m ruff check schematica
python -m mypy schematica
The suite has 320+ tests covering shapes, boolean ops, transforms, SDF smooth
blending, Bezier curves, SVG path voxelization, active symmetry, subregion
resampling, session history, chunked backend, export round-trips for all three
formats, spatial analysis, constraints, and CLI dispatch.
License
MIT
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found