Which Sponge version should a script write?

Version 3. The converter reads versions 1 to 3, but version 3 is the current layout, with everything under one Schematic compound.

What is the block-data array?

One unsigned LEB128 varint per cell, each the palette index of the block in that cell, in x + z*Width + y*Width*Length order. A palette index under 128 is a single byte.

Do I need a DataVersion?

Yes, to write a file. It is the Minecraft release data version and tells the converter which release the blocks are from.

Write a .schem a script or ChatGPT can generate

A Sponge version 3 .schem is plain NBT: a palette that maps each block-state string to a number, and a block-data array of those numbers, one per cell. If you can write NBT, a script or a chatbot can write a .schem WorldEdit reads, and the converter turns into any other format.

This page is the layout to write and the few things to get right. When your file is ready, drop it into the converter to check it reads.

It's free, there's no account, and we don't store your file.

Steps

Lay it out as version 3.Put everything under one Schematic compound. Set Version to 3 and DataVersion to the Minecraft release data version (for example 3465 for 1.20.1). Add Width, Height and Length as shorts, and Offset as an int array of three. Save it gzip-compressed: WorldEdit reads a Sponge file through a gzip stream (its Sponge v3 reader, BuiltInClipboardFormat.SPONGE_V3_SCHEMATIC), so a raw file passes the converter but then fails in WorldEdit.
Write the palette.Inside a Blocks compound, add a Palette compound that maps each block-state string, like minecraft:stone or minecraft:oak_stairs[facing=east], to its own integer, counting from 0.
Write the block data.Add Data: one unsigned LEB128 varint per cell, each the palette index of the block there. A value under 128 is a single byte. Order the cells x + z*Width + y*Width*Length.
Check it in the converter.Drop the file into the converter. It reads the palette, the block data and the version, and shows what it holds.

What a valid file holds

Kept

The block of every cell, from its palette index
The palette: each block-state string mapped to a number
The Minecraft release, from DataVersion
The size, from Width, Height and Length
Block entities (chests, signs) in the Blocks compound BlockEntities

Three mistakes the converter repairs

A script does not have to be perfect. The converter repairs the three slips a generated file most often has, so it still reads.

First, a file whose every compound ends twice, which closes it early: it is read as one file. This was the most common slip, a second TAG_End that ended the root early. Second, a Litematica file whose block data is packed so no entry crosses a 64-bit boundary, the way a script might pack a chunk: it is read as written. Third, a file that says version 2 but lays its blocks out the version 3 way: it is read as version 3, every block kept.

Common questions

Which Sponge version should a script write?: Version 3. The converter reads versions 1 to 3, but version 3 is the current layout, with everything under one Schematic compound.
What is the block-data array?: One unsigned LEB128 varint per cell, each the palette index of the block in that cell, in x + z*Width + y*Width*Length order. A palette index under 128 is a single byte.
Do I need a DataVersion?: Yes, to write a file. It is the Minecraft release data version and tells the converter which release the blocks are from.

Open the converter and check your file