Skip to content

About

🔥 Blazing fast Minecraft schematic rendering. Seamlessly wired into Quick Look.

Topics

Resources

Stars

18 stars

Watchers

0 watching

Forks

Repository files navigation

LitematicaQL icon

LitematicaQL

Quick Look preview for Minecraft schematics on macOS

English | 中文

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

Install with Homebrew:

brew install --cask arcadi4/tap/litematicaql

Or install manually:

  1. Download from the release page
  2. Move LitematicaQL.app to /Applications.
  3. Open the app once so macOS registers its preview extension.
  4. Select a supported file in Finder and press Space.

This app requires macOS 13 Ventura or later and a Metal-capable GPU.

You can check for updates through LitematicaQL → Check for Updates….

Previews use native Metal with streamed chunk meshing, compact GPU buffers, and on-demand drawing. The shared LitematicaPreview Core prepares validated vertex/index buffers and first-use RGBA textures; the native hosts upload them to GPU-private Metal buffers. Geometry uploads borrow the native allocation's whole pages without a staging copy; only partial boundary pages are copied. Native batches remain alive until Metal finishes reading them, and at most two uploads are in flight.

Note

If the preview doesn't show up, enable LitematicaQL under System Settings → General → Login Items & Extensions → Quick Look.

Texture Packs

Open LitematicaQL → Settings… (⌘ + ,) and choose Add Texture Packs… to import Minecraft Java resource-pack ZIPs.

Enable packs in the inline list. Drag enabled rows or use the arrow buttons to set their priority: the top pack wins. Missing textures, models, and blockstates fall back to lower packs, then bundled vanilla.

Changes reload open app previews and apply to subsequent Quick Look previews. Existing single-pack selections are preserved. Removing a saved pack keeps the original ZIP.

Preview Limits

Very large schematics are refused with an offer to render them anyway. To skip the warning and always render them, enable Render oversized schematics without asking under LitematicaQL → Settings… (⌘ + ,). The choice applies to the app and Quick Look; oversized previews may take a long time or exhaust memory.

Supported Formats

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)

Development

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 test-metal Check real Metal uploads and native-memory lifetimes (requires a Metal-capable Mac)
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.

Release tags use cf and cloudflare/cloudflare.config.ts to publish archives to the apps-download R2 bucket and architecture-specific Sparkle feeds to the apps-update Worker. The release workflow requires SPARKLE_PRIVATE_KEY and CLOUDFLARE_API_TOKEN repository secrets. The Cloudflare token needs access to upload bucket objects and deploy the Worker and its custom domain. Keep a secure backup of the Sparkle private key: installed apps use its public key to authenticate updates.

The Worker deployment replaces its entire static asset set. Add feeds for other apps to the same deployment before sharing apps-update with another project.

Build

Prerequisites:

  • just
  • Xcode 26 or later, including the Metal Toolchain component
  • Rust (rustup)
  • XcodeGen
git clone https://github.com/Arcadi4/LitematicaQL.git
cd LitematicaQL

just build

Acknowledgements

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

About

🔥 Blazing fast Minecraft schematic rendering. Seamlessly wired into Quick Look.

Topics

Resources

Stars

18 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages