schematica

skill
Guvenlik Denetimi
Uyari
Health Uyari
  • 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 Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

AI skill for generating Minecraft Java Edition schematics with Python, voxel geometry, procedural builders, previews, and Sponge/MCEdit/Litematica export.

README.md

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 at
scripts/schematica/blocks/data/fallback_blocks.json
(SCHEMATICA_FALLBACK_BLOCKS overrides). Previews pick colors from a bundled
texture-derived table; regenerate per version with
python -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 / paint forward **shape_kwargs to the
    shape's dataclass fields via dataclasses.replace — so
    s.add(Sphere(...), "stone", hollow=True) works. Unknown kwargs raise
    TypeError listing 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 about center (grid middle by default) along
    axis. symmetry_active is 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 about center
    (grid middle by default) in the named plane. folds=4 → quad, folds=8 →
    octo, folds=2 → half-turn. Uses the exact Rotated90 transform 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 to new_size, written at dest_origin.
  • set_box / set_many: fast bulk write paths for procedural detail.
  • undo / redo (delta-based history), save / load session JSON.
  • marker(name, x, y, z, kind) / region(name, corner, size, kind) /
    export_markers(path) for annotations.
  • paint_gradient, edge_wear, surface_scatter for organic detail.
  • walkable_at, clearance_at, is_connected, reachable_area,
    shortest_path for 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. See
    references/preview_rendering.md.
  • Bulk procedural writes: use Session.set_box(...) and Session.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/intersect forward
    **shape_kwargs to the shape via dataclasses.replace. Unknown kwargs
    raise TypeError with a clear list of valid fields.
  • Active symmetry: enable_symmetry wraps each shape in a
    Union((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_sdf uses
    scipy.ndimage.distance_transform_edt when available; otherwise a pure-numpy
    iterative-erosion BFS. Fully-filled masks get a constant negative distance
    so SmoothSubtract on 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 is nbtlib (pure Python) which works on
    3.11-3.14. Install amulet-core only 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 fallback iso writes preview_iso_projected.png.
  • Backslashes in REPL scripts: shlex treats \ as escape. Use forward
    slashes in path= 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 vendored minecraft_data/.
  • Legacy versions: for 1.7-1.12 colored blocks, prefer MCEdit .schematic.
    Sponge export warns when a pre-1.13 data_version is paired with modern
    flattened blockstate names. MCEdit export warns when a non-air block has no
    legacy ID mapping; use strict=True to fail instead.

Extending the toolkit

  • Add a shape: implement the Shape protocol (def mask(shape) -> ndarray)
    in a new file under scripts/schematica/shapes/.
  • Add a generator: add a function in scripts/schematica/generators/templates.py
    that takes a Session and applies shapes. Pin a seed for determinism.
  • Add an exporter: add scripts/schematica/export/<format>.py mirroring sponge.py.
  • Add a CLI command: register a CommandSpec in scripts/schematica/session/commands.py
    with arg specs and a handler that calls a Session method.

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

Yorumlar (0)

Sonuc bulunamadi