Minecraft Schematic — Sponge Format for WorldEdit, Litematica, and Build the Earth

Minecraft Schematic (.schem) is a binary save format for fragments of a Minecraft world: a cube of blocks with metadata that can be copied, transferred between worlds and servers, or reused as a blueprint in another build. The current version is Sponge Schematic Format v2 (2018), successor to the legacy .schematic format from MCEdit. It is the foundation of the WorldEdit, FastAsyncWorldEdit (FAWE), Litematica, and Build the Earth ecosystems — the global IFTRA-community project reconstructing the entire planet 1:1 in Minecraft based on OpenStreetMap data. On osm2cdr.ru minecraft_schem_exporter.py takes an OSM bbox and converts buildings, roads, water bodies, and green zones into Sponge Schematic v2 — ready for import into WorldEdit or Litematica for placement in a Minecraft world.

History: from Notch to Build the Earth

Minecraft was created by Markus «Notch» Persson in 2009 — initially as an indie experiment with a voxel world inspired by Infiniminer and Dwarf Fortress. The game is built on a fully destructible world of 1×1×1 meter blocks, each stored in a native serialization format Notch designed — NBT (Named Binary Tag), a gzip-compressed tree of named tags. NBT became the universal format for all game data: world chunks, player inventory, server configuration, item metadata. In 2014 Mojang was acquired by Microsoft for $2.5 billion, but Java Edition preserved format openness.

In 2010 developer Wesley «sk89q» Wolfe released WorldEdit — a server-side Bukkit plugin (then the most popular Minecraft server platform) letting administrators mass-edit terrain: copy regions, replace blocks by pattern, generate geometric primitives. WorldEdit needed a format to save copied regions to disk — it used legacy .schematic, an NBT-based format compatible with MCEdit (a standalone editor by ShadowVolt/Codewarrior007, circa 2010). The legacy .schematic was simple: a 3D block array plus minimal metadata, but had a hard limit of 256 block types (1 byte per block ID) — which became a problem as Minecraft grew to thousands of block states.

In 2017 the Sponge Foundation (open-source Minecraft modding platform, competitor to Bukkit/Spigot) published Sponge Schematic Specification v1 — a modernized successor to .schematic. Key innovations: palette-based block storage (varint indices into an array of unique block states, removing the 256-types limit), normalized coordinate origin, structured metadata. In 2018 v2 was released — adding BlockEntities (tile entities: chests with inventory, signs with text, furnaces) and Entities (mobs, dropped items, item frames) as first-class parts of the schematic. V2 is the current standard, supported by WorldEdit since 7.0, FAWE, Litematica, Amulet Editor. V3 (proposed 2022) extends the palette to entities and adds block tick scheduling — not yet finalized, but the WorldEdit experimental branch already supports reading.

In parallel in 2020 Build the Earth emerged — an ambitious IFTRA community project to recreate the entire planet in Minecraft at 1:1 scale, where 1 OSM-meter = 1 Minecraft block. By 2024 the project unified ~3000 active builders divided into sub-projects by country (BTE USA, BTE Germany, BTE Russia, BTE Japan and dozens of others). Build the Earth tooling includes a custom Minecraft client mod Terra++ for streaming large custom-projection worlds, and automated OSM-to-schematic conversion pipelines generating a starting baseline that builders then improve manually.

Inside .schem: NBT, Palette, BlockData

Sponge Schematic is a gzip-compressed NBT file with a fixed top-level Compound tag structure. To understand the format you first need to understand NBT.

NBT (Named Binary Tag). Notch designed NBT in 2010 as a simple tagged tree serialization for Minecraft chunks. Each tag has a 1-byte type prefix (TAG_Byte=1, TAG_Short=2, TAG_Int=3, TAG_Long=4, TAG_Float=5, TAG_Double=6, TAG_String=8, TAG_List=9, TAG_Compound=10, TAG_IntArray=11, TAG_LongArray=12), a name length (2 bytes unsigned), a name string (UTF-8), and a payload. Compound is a dictionary of tagged children, List is a homogeneous array. The whole file is wrapped in a single root Compound. The file is compressed with gzip (DEFLATE with gzip wrapper) for compactness — a typical 100×100×50 block schematic compresses from tens of megabytes down to hundreds of kilobytes thanks to block repetition.

Sponge Schematic v2 root structure:

Schematic (Compound)
├── Version: Int = 2
├── DataVersion: Int (Minecraft data version, e.g. 2865 = 1.17.1)
├── Width: Short (X dimension, unsigned)
├── Height: Short (Y dimension, unsigned)
├── Length: Short (Z dimension, unsigned)
├── Offset: IntArray[3] (relative origin position)
├── PaletteMax: Int (count of unique block states)
├── Palette: Compound (block_state_string → numeric_id)
├── BlockData: ByteArray (varint-encoded indices into Palette)
├── BlockEntities: List<Compound> (tile entities at positions)
├── Entities: List<Compound> (optional, mobs/items)
└── Metadata: Compound (Name, Author, Date, optional WEOffsets)

Palette — the key v2 innovation. Instead of storing a block ID for every block (as in legacy .schematic), the schematic stores a dictionary of unique block states + an array of indices. The palette is a Compound where keys are block state strings in the format minecraft:stone or minecraft:oak_stairs[facing=north,half=bottom,waterlogged=false] (with explicit property values), and values are numeric IDs 0...PaletteMax-1. This removes the 256-blocks limit (legacy .schematic used 1 byte = 256 states max), allowing all modern Minecraft block registry with thousands of states.

BlockData — varint encoding. Array of 3D indices into the Palette, flattened to 1D as index = (y × Length + z) × Width + x. Each index is encoded as a varint (variable-length integer): 7 data bits per byte, MSB = continuation flag, compact for small palettes (1 byte if PaletteMax ≤ 128) and automatically expanding to 5 bytes for larger ones. This gives better compression than fixed-width encoding for typical schematics where most blocks are a few popular types (stone, air, dirt).

BlockEntities — tile entities with inventory. A list of Compound tags for blocks with per-instance data: chests (with inventory items), signs (with text), furnaces (with smelting progress), spawners (with mob type). Each BlockEntity contains Pos: IntArray[3] (relative coordinates in the schematic) and Id: String (minecraft:chest), plus entity-specific tags.

Entities — optional. V2 added the ability to save mobs, item frames, armor stands, dropped items. Each entity is a Compound with Pos: List<Double>[3] (relative position) and full NBT entity data. V1 did not support entities.

Offset and WEOffsets. Offset is the schematic origin's displacement relative to an abstract anchor point (used by WorldEdit for correct paste). WEOffsets in Metadata is a legacy WorldEdit-specific offset for backward compatibility with pre-Sponge .schematic.

The .schem extension (Sponge format) and .schematic (legacy) are often confused, but they are not identical — programmatically distinguishable by the presence of a Version tag (v2 has it, legacy does not) and by structure. WorldEdit can read both; Litematica prefers its own .litematic format but imports .schem without issues.

Use cases: server admins, Build the Earth, education

Server administration. The main historical use case. Large Minecraft server admins (Hypixel, 2b2t, Mineplex) use WorldEdit + .schem for mass operations: copying arenas between worlds for events, deploying identical spawn-area structures across multiple servers, backing up player builds before a wipe. Server-side automation scripts (Skript, Denizen) often include //paste commands with schematic libraries to generate loot rooms, dungeons, parkour courses.

Creative players — Litematica blueprint placement. Litematica (a Fabric/Forge client mod by developer Masa) allows loading a .schem or native .litematic file and displays it as a semi-transparent hologram overlaid on the Minecraft world — the player sees where to place which block and in what order, without needing creative-mode access. This revolutionized the technical Minecraft community: complex redstone contraptions (computers, sorting machines, mob farms) are distributed as schematic libraries that survival players reproduce blueprint-by-blueprint.

Build the Earth — 1:1 OSM in Minecraft. The most ambitious use case with direct OSM connection. Build the Earth recreates the entire Earth in Minecraft at scale 1 meter = 1 block, giving a world of ~40 million × 40 million blocks. OSM data is used as baseline for automatic generation of terrain elevation (via SRTM heightmaps), road networks, building footprints. Builders then manually improve the baseline: add façade textures, architectural details, vegetation. Sub-projects organized by country — BTE Germany, BTE USA, BTE Japan have their own discord communities and technical pipelines. The bottleneck is manual building details (a single real-world city block requires 10-50 person-hours), but baseline OSM-to-schematic generation saves weeks of work.

Historical reconstruction. Serious educational projects use Minecraft for reconstructing historic buildings and cities. Notable examples: pre-fire Notre-Dame de Paris (recreated by the Ubisoft Assassin's Creed Unity team + community), the Parthenon in Athens (reconstructed by Greek archaeological community), Renaissance Florence, Imperial Rome. The schematic format lets architects and historians share ready-made reconstruction modules — porticos, colonnades, typical Roman domus types — for reuse in other projects.

City planning concept. Real urban planners experiment with Minecraft as a low-barrier 3D visualization tool for community engagement. The Block-by-Block Foundation (Mojang + UN-Habitat partnership, 2012-present) runs workshops in developing countries where residents model their neighborhoods in Minecraft to discuss urban improvement projects with city officials. Schematic export lets participants share models and present them to stakeholders.

Modded survival and technical builds. Modded Minecraft (FTB Modpacks, GregTech, Create) uses complex multi-block structures — factories, reactors, automated processing chains — that would otherwise require days of wiring. Schematic libraries (Schematica, predecessor of Litematica, or FTB Schematic Maker) distribute ready setups.

Software/tools ecosystem

WorldEdit (sk89q, AGPL). The canonical tool. github.com/EngineHub/WorldEdit, supports Bukkit, Spigot, Paper, Fabric, Forge, Sponge. Commands //copy saves a selection to the clipboard, //schem save <name> writes a .schem file, //schem load <name> + //paste deploys the schematic into the world. Supports Sponge v2 natively and legacy .schematic for compatibility. The AGPL license means modifications must be open-sourced — which has not stopped forks but ensures basic openness.

FAWE — FastAsyncWorldEdit. github.com/IntellectualSites/FastAsyncWorldEdit, a performance-optimized WorldEdit fork by Empire92. Main advantage — asynchronous operations via main-thread offloading, preventing server lag during large pastes (100K+ blocks). FAWE uses the same .schem format as WorldEdit, but adds compression optimizations (lz4 for intermediate states) and API hooks for plugin developers. On production servers with thousands of players FAWE is the de-facto standard rather than vanilla WorldEdit.

Litematica (Masa). github.com/maruohon/litematica, Fabric/Forge client-side mod. Not a server plugin — installed per-player into the client. Its key feature is a hologram preview of the imported schematic overlaid on the real world view. Also supports material list (showing which blocks are needed and how many), printer mode (auto-placement in creative). Native format .litematic (slightly extended Sponge schematic), but imports .schem without issues.

MCEdit-Unified. Standalone Python editor, fork of the original MCEdit. github.com/Podshot/MCEdit-Unified. Allows opening Minecraft worlds, selecting regions, exporting to .schematic/.schem. Used as an offline tool when server access is unavailable. Development stalled around 2018 (last stable release), but still functional for legacy worlds.

Amulet Editor. github.com/Amulet-Team/Amulet-Map-Editor, modern MCEdit successor. Python + PyOpenGL for 3D viewport. Supports Java Edition and Bedrock Edition worlds, conversion between them, full .schem import/export. Actively maintained, community-recommended over MCEdit for production work.

arnis (Rust, OSM-to-Minecraft converter). github.com/louis-e/arnis — a Rust CLI tool that takes an OSM bbox or .osm.pbf file and generates a Minecraft world directly (or a schematic). Popular in the Build the Earth community as an automated baseline generator. Supports building extrusion from OSM footprints + heights, road networks with lane-aware paving, water bodies, vegetation. Output is either direct Minecraft world saving or .schem for downstream tools.

OpenStreetMap-to-Minecraft (Build the Earth tooling). Build the Earth project tooling includes multiple converters: the Terra++ mod (streaming generation on the fly during gameplay), offline batch scripts (Python + osmium) for pre-generation of regions, custom schematic libraries for standard building types (typical American suburb home, European apartment block, Japanese row house). These tools are community-maintained, scattered across various GitHub repositories.

Workflow in OSM2CDR: OSM → Sponge Schematic v2

Our minecraft_schem_exporter.py converts OSM bbox data into Sponge Schematic v2 — useful as a baseline for Build the Earth builders (skip manual digitization), educators (teaching geography via familiar Minecraft), or city visualization experiments for community engagement.

Step 1: Extract OSM features. PostGIS query through local_osm_loader.py for the bbox filtering key tags: building=* with height/building:levels for footprints + heights, highway=* for road networks, natural=water/waterway=* for water bodies, landuse=grass/leisure=park for parks, natural=tree for individual trees. WKB geometry is loaded via the layer_builder fast-path.

Step 2: Coordinate transformation. OSM lat/lon (WGS84) is converted to local meters via Web Mercator projection recentered on bbox centroid. Then — 1 meter = 1 block mapping. This gives integer block coordinates (X, Y, Z) where Y is height (default 64 for ground level, Minecraft world height range -64...320 in 1.18+).

Step 3: Block palette assignment. Each OSM feature type maps to a specific Minecraft block: - Roads (highway=primary/secondary) — minecraft:gray_concrete (motorways), minecraft:light_gray_concrete (residential), minecraft:dirt_path (footways). - Buildings — variants by height: 1-2 floors → minecraft:sandstone, 3-5 floors → minecraft:smooth_sandstone, 6+ floors → minecraft:polished_andesite (highrise contrast). Roof — minecraft:smooth_stone_slab[type=top] (flat). - Water (natural=water, waterway=river) — minecraft:water (live water) or minecraft:blue_stained_glass (for visual clarity without water mechanics). - Parks/grass (landuse=grass, leisure=park) — minecraft:grass_block + scattered minecraft:oak_leaves columns for trees. - Default ground — minecraft:dirt under all flat areas.

Step 4: Building extrusion. For each building footprint polygon — an extruded column is generated: ground-floor polygon → fill blocks layer-by-layer up to height (or building:levels × 3 if height absent). Outline blocks — wall material, interior — minecraft:air (hollow buildings for playability). Roof — single flat layer flush with top floor.

Step 5: BlockData encoding. The 3D block array is serialized to 1D via canonical Sponge ordering index = (y × Length + z) × Width + x. Each block lookup → palette ID → varint encoding into ByteArray. The palette is built on the fly as unique block states are encountered.

Step 6: NBT serialization + gzip. The Compound tree is assembled with Version=2, Width/Height/Length, PaletteMax, Palette, BlockData, BlockEntities (empty for OSM — no inventories), Metadata (Name, Author=«OSM2CDR», Date). The tree is serialized to a bytestream via NBT format, wrapped in gzip, written as a .schem file.

Limitations and trade-offs. Max practical schematic size — about 512×512×128 blocks. Tools handle up to ~33 million blocks, but for placement of very large schematics WorldEdit/FAWE may cause server lag or client crashes. For bbox >500×500 meters we automatically split into multiple .schem files via tiling. 1 OSM meter = 1 Minecraft block gives city-scale geography but without sub-block detail (you cannot represent a 2.5-meter sidewalk width — it rounds to 2 or 3 blocks). Building roofs are flat, because the Minecraft block grid cannot handle arbitrary slope roofs without massive complexity (sloped roofs are possible via stairs/slabs, but require complex meshing — not implemented in v1 of our exporter, planned for v2). Vegetation uses aggressive simplification — individual tree positions from OSM natural=tree render as a single 4-block tall oak column, not as realistic procedural trees. Building interiors are not modeled — buildings are hollow shells.

Recommended workflow for Build the Earth contributors. Use our schematic export as a starting baseline, import via WorldEdit //schem load + //paste into your regional BTE world, then improve manually: add window detail to façades, replace flat roofs with sloped constructions via stairs/slabs, add vegetation textures via leaves variants, prop placement (lampposts, benches, cars) via decoration blocks. One city block (~100×100 meters) typically requires 5-15 person-hours of post-baseline polishing to meet BTE quality standard.

Conclusion

Sponge Schematic v2 is the modern industry-standard format for saving and loading Minecraft builds, the foundation of the WorldEdit, FAWE, Litematica ecosystem. Its three key strengths — palette-based block storage (removing the 256-types limit of the legacy format), gzip-compressed NBT (compact storage for repetitive worlds), first-class BlockEntities (preserved inventories and signs) — make it versatile across the entire use-case spectrum: from administering large servers to educational projects reconstructing historic cities. The Build the Earth project showed how .schem can serve as a bridge between real-world geography (OSM data) and the Minecraft creative community.

On osm2cdr.ru we provide minecraft-schem export through /api/render — a baseline for post-processing, not a fully detailed model: building extrusion, road network, water bodies, vegetation. For production Build the Earth deployment the typical plan: osm2cdr baseline → import into Litematica/WorldEdit → manual detail refinement → integration into a regional BTE world. For educators and city planners the baseline is already useful as a starting point for community presentations.

Try exporting OSM to Minecraft Schematic for your city and import the result via WorldEdit //schem load <filename> or Litematica hologram preview.

Related

• STL — standard 3D mesh for printing and BIM
• Tiled TMX — 2D tile-based map editor for indie games
• OBJ — Wavefront 3D objects with materials
• glTF — JSON 3D asset standard from Khronos

Sources

• Sponge Schematic Format Specification — github.com/SpongePowered/Schematic-Specification
• WorldEdit GitHub repository (sk89q/EngineHub) — github.com/EngineHub/WorldEdit
• FastAsyncWorldEdit (IntellectualSites) — github.com/IntellectualSites/FastAsyncWorldEdit
• Litematica mod (maruohon/Masa) — github.com/maruohon/litematica
• arnis OSM-to-Minecraft converter (louis-e) — github.com/louis-e/arnis
• Build the Earth project — buildtheearth.net
• NBT format specification (Minecraft Wiki) — minecraft.wiki/w/NBT_format