LitematicaQL adds a macOS Quick Look preview extension for Minecraft schematics and structures. It previews .litematic, .schem, .schematic, .nbt, .snbt, .mcstructure, .nusn, and .mca.
If you are on Windows, check out the sister project LitematicaPreview for rendering speed as fast as LitematicaQL!
| Previewing Schematics | Previewing World Saves |
|---|---|
Valkyria.mp4 |
mca.mp4 |
Install with Homebrew:
brew install --cask arcadi4/tap/litematicaqlOr install manually:
- Download from the release page
- Move
LitematicaQL.appto/Applications. - Open the app once so macOS registers its preview extension.
- Select a supported file in Finder and press Space.
This app requires macOS 13 Ventura or later and a Metal-capable GPU.
Previews use native Metal with streamed chunk meshing, compact GPU buffers, and on-demand drawing. See the rendering architecture.
Note
If the preview doesn't show up, enable LitematicaQL under System Settings → General → Login Items & Extensions → Quick Look.
Open LitematicaQL → Settings… (⌘+,) and choose Add Texture Packs… to import Minecraft Java resource-pack ZIPs.
| Extension | File format |
|---|---|
.litematic |
Litematica |
.schem |
Sponge schematic |
.schematic |
MCEdit |
.nbt |
Java structure block |
.snbt |
Structure SNBT, brace or bracket block states |
.mcstructure |
Bedrock structure |
.nusn |
Nucleation snapshot |
.mca |
Minecraft Anvil world saves (4 chunks per file) |
Everything is driven by just. Run it with no arguments to list every recipe:
just| Command | What it does |
|---|---|
just doctor |
Check that the toolchain prerequisites are installed |
just build |
Build the ad-hoc signed app for Apple silicon and Intel |
just run |
Build the app and open it |
just test |
Run the Swift file-validation tests and the Rust bridge tests |
just check |
Type-check the Rust bridge |
just clean |
Delete every generated build artifact |
just ci |
Reproduce the CI pipeline locally |
just unregister |
Clean stale LitematicaQL Quick Look registrations, keeping the installed /Applications copy |
just bump patch |
Bump the version on main (patch by default, or minor, major), commit it, and tag it |
just release 1.2.6 arm64 |
Archive, verify, and package one architecture |
just demos |
Regenerate the bundled demo schematics |
just honors CONFIGURATION, ARCHS, and CURRENT_PROJECT_VERSION from the
environment, which is how CI and the release matrix drive these same recipes.
Prerequisites:
git clone https://github.com/Arcadi4/LitematicaQL.git
cd LitematicaQL
just buildGreat thanks to @Nano112's project Nucleation for powering the whole parsing and meshing pipeline.
Thanks to my generous friend @johnbean393 for sharing their Apple signature to notarize the app, providing better unboxing experience while saving me $100 in Apple tax! Consider looking into their project Chiboard, an ML-based Pinyin input method that speeds up Chinese typing manifold.